update ruby & python scrolling tests and documentation to match Java and .NET

titusfortner · titusfortner · commit 7fe7873d8e08 · 2022-05-14T14:54:15.000-05:00
diff --git a/py/selenium/webdriver/common/action_chains.py b/py/selenium/webdriver/common/action_chains.py
@@ -18,9 +18,11 @@
 """
 The ActionChains implementation,
 """
+from typing import Union
 
 from .utils import keys_to_typing
 from .actions.action_builder import ActionBuilder
+from selenium.webdriver.remote.webelement import WebElement
 
 
 class ActionChains:
@@ -321,16 +323,22 @@ def send_keys_to_element(self, element, *keys_to_send):
         self.send_keys(*keys_to_send)
         return self
 
-    def scroll(self, x: int, y: int, delta_x: int, delta_y: int, duration: int = 0, origin= "viewport"):
+    def scroll(self, x: int, y: int, delta_x: int, delta_y: int, duration: int = 0, origin: Union[str,WebElement] = "viewport"):
         """
-        Sends wheel scroll information to the browser to be processed.
+        Scrolls by the provided amount from a designated origination point.
+        The scroll origin is either the center of an element or the upper left of the viewport plus any offsets.
+        If the origin is an element, and the element is not in the viewport, the bottom of the element will first
+        be scrolled to the bottom of the viewport.
 
         :Args:
-         - x: starting X coordinate
-         - y: starting Y coordinate
-         - delta_x: the distance the mouse will scroll on the x axis
-         - delta_y: the distance the mouse will scroll on the y axis
-         - origin: element whose center is the origination point of the scroll; the default is upper left of viewport.
+         - x: The horizontal offset from the origin from which to start the scroll.
+         - y: The vertical offset from the origin from which to start the scroll.
+         - delta_x: Distance along X axis to scroll using the wheel. A negative value scrolls left.
+         - delta_y: Distance along Y axis to scroll using the wheel. A negative value scrolls up.
+         - origin: Where scroll originates (viewport or element center). The default is upper left of viewport.
+
+         :Raises: If the origin with offset is outside the viewport.
+          - MoveTargetOutOfBoundsException - If the origin with offset is outside the viewport.
         """
         self.w3c_actions.wheel_action.scroll(x=x, y=y, delta_x=delta_x, delta_y=delta_y,
                                              duration=duration, origin=origin)
diff --git a/py/test/selenium/webdriver/common/interactions_tests.py b/py/test/selenium/webdriver/common/interactions_tests.py
@@ -284,7 +284,6 @@ def test_can_scroll_from_element_by_amount(driver, pages):
 
     driver.switch_to.frame(iframe)
     checkbox = driver.find_element(By.NAME, "scroll_checkbox")
-
     assert _in_viewport(driver, checkbox)
 
 
@@ -299,7 +298,6 @@ def test_can_scroll_from_element_with_offset_by_amount(driver, pages):
     iframe = driver.find_element(By.TAG_NAME, "iframe")
     driver.switch_to.frame(iframe)
     checkbox = driver.find_element(By.NAME, "scroll_checkbox")
-
     assert _in_viewport(driver, checkbox)
 
 
@@ -318,9 +316,9 @@ def test_errors_when_element_offset_not_in_viewport(driver, pages):
 def test_can_scroll_from_viewport_by_amount(driver, pages):
     pages.load("scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html")
     footer = driver.find_element(By.TAG_NAME, "footer")
-    y = footer.rect['y']
+    delta_y = footer.rect['y']
 
-    ActionChains(driver).scroll(0, 0, 0, y).pause(0.2).perform()
+    ActionChains(driver).scroll(0, 0, 0, delta_y).pause(0.2).perform()
 
     assert _in_viewport(driver, footer)
 
@@ -329,42 +327,24 @@ def test_can_scroll_from_viewport_by_amount(driver, pages):
 @pytest.mark.xfail_remote
 def test_can_scroll_from_viewport_with_offset_by_amount(driver, pages):
     pages.load("scrolling_tests/frame_with_nested_scrolling_frame.html")
-    iframe = driver.find_element(By.TAG_NAME, "iframe")
 
     ActionChains(driver).scroll(10, 10, 0, 200).pause(0.2).perform()
 
+    iframe = driver.find_element(By.TAG_NAME, "iframe")
     driver.switch_to.frame(iframe)
     checkbox = driver.find_element(By.NAME, "scroll_checkbox")
-
     assert _in_viewport(driver, checkbox)
 
 
 @pytest.mark.xfail_firefox
 @pytest.mark.xfail_remote
 def test_errors_when_origin_offset_not_in_viewport(driver, pages):
-    pages.load("scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html")
+    pages.load("scrolling_tests/frame_with_nested_scrolling_frame.html")
 
     with pytest.raises(MoveTargetOutOfBoundsException):
         ActionChains(driver).scroll(-10, -10, 0, 200).perform()
 
 
-@pytest.mark.xfail_firefox
-@pytest.mark.xfail_remote
-def test_can_scroll_mouse_wheel(driver, pages):
-    pages.load("scrollingPage.html")
-    driver.execute_script("document.scrollingElement.scrollTop = 0")
-
-    scrollable = driver.find_element(By.CSS_SELECTOR, "#scrollable")
-    ActionChains(driver).scroll(0, 0, 5, 10, origin=scrollable).perform()
-    events = _get_events(driver)
-    assert len(events) == 1
-    assert events[0]["type"] == "wheel"
-    assert events[0]["deltaX"] >= 5
-    assert events[0]["deltaY"] >= 10
-    assert events[0]["deltaZ"] == 0
-    assert events[0]["target"] == "scrollContent"
-
-
 def _get_events(driver):
     """Return list of key events recorded in the test_keys_page fixture."""
     events = driver.execute_script("return allEvents.events;") or []
diff --git a/py/test/selenium/webdriver/common/w3c_interaction_tests.py b/py/test/selenium/webdriver/common/w3c_interaction_tests.py
@@ -17,6 +17,7 @@
 
 import pytest
 
+from selenium.webdriver.common.actions.wheel_input import WheelInput
 from selenium.webdriver.common.keys import Keys
 from selenium.webdriver.common.actions.action_builder import ActionBuilder
 from selenium.webdriver.common.actions.pointer_input import PointerInput
@@ -259,6 +260,25 @@ def test_touch_pointer_properties(driver, pages):
     assert events[3]["twist"] == 345
 
 
+def test_can_scroll_mouse_wheel(driver, pages):
+    pages.load("scrollingPage.html")
+    driver.execute_script("document.scrollingElement.scrollTop = 0")
+    scrollable = driver.find_element(By.CSS_SELECTOR, "#scrollable")
+
+    wheel_input = WheelInput("wheel")
+    actions = ActionBuilder(driver, wheel=wheel_input)
+    actions.wheel_action.scroll(0, 0, 5, 10, 0, scrollable)
+
+    actions.perform()
+    events = _get_events(driver)
+    assert len(events) == 1
+    assert events[0]["type"] == "wheel"
+    assert events[0]["deltaX"] >= 5
+    assert events[0]["deltaY"] >= 10
+    assert events[0]["deltaZ"] == 0
+    assert events[0]["target"] == "scrollContent"
+
+
 def _perform_drag_and_drop_with_mouse(driver, pages):
     """Copied from org.openqa.selenium.interactions.TestBasicMouseInterface."""
     pages.load("draggableLists.html")
diff --git a/rb/lib/selenium/webdriver/common/interactions/wheel_actions.rb b/rb/lib/selenium/webdriver/common/interactions/wheel_actions.rb
@@ -25,12 +25,11 @@ def default_scroll_duration
       end
 
       #
-      # This method uses a Scroll Wheel Input to determine where and by how much to scroll
+      # Scrolls by the provided amount from a designated origination point.
       #
-      # The scroll happens from an origin plus an offset.
-      # The amount to scroll is represented by delta_x and delta_y
-      # The origin is either the center of a provided element or the upper left of the current viewport
-      # The offset from the origin is represented by x and y
+      # The scroll origin is either the center of an element or the upper left of the viewport plus offsets.
+      # If the origin is an element, and the element is not in the viewport, the bottom of the element will first
+      #   be scrolled to the bottom of the viewport.
       #
       # @example Scroll to element
       #    el = driver.find_element(id: "some_id")
@@ -57,8 +56,8 @@ def default_scroll_duration
       # @option opts [Integer] delta_x Distance along X axis to scroll using the wheel. A negative value scrolls left.
       # @option opts [Integer] delta_y Distance along Y axis to scroll using the wheel. A negative value scrolls up.
       # @option opts [String, Element] origin The origin of the scroll, either the viewport or the center of an element.
-      # @return [ActionBuilder] A self reference.
-      # @raise [MoveTargetOutOfBoundsError] if the origin plus offset is located outside the viewport.
+      # @return [Selenium::WebDriver::WheelActions] A self reference.
+      # @raise [Error::MoveTargetOutOfBoundsError] If the origin with offset is outside the viewport.
       #
 
       def scroll(**opts)
diff --git a/rb/spec/integration/selenium/webdriver/action_builder_spec.rb b/rb/spec/integration/selenium/webdriver/action_builder_spec.rb
@@ -274,6 +274,7 @@ def in_viewport?(element)
         it 'scrolls to element' do
           driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
           iframe = driver.find_element(tag_name: 'iframe')
+
           expect(in_viewport?(iframe)).to eq false
 
           driver.action.scroll(origin: iframe).perform
@@ -283,8 +284,8 @@ def in_viewport?(element)
 
         it 'scrolls from element by given amount' do
           driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
-
           iframe = driver.find_element(tag_name: 'iframe')
+
           driver.action.scroll(delta_y: 200, origin: iframe).perform
 
           driver.switch_to.frame(iframe)
@@ -294,11 +295,12 @@ def in_viewport?(element)
 
         it 'scrolls from element by given amount with offset' do
           driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
-
           footer = driver.find_element(tag_name: 'footer')
+
           driver.action.scroll(y: -50, delta_y: 200, origin: footer).perform
 
-          driver.switch_to.frame(driver.find_element(tag_name: 'iframe'))
+          iframe = driver.find_element(tag_name: 'iframe')
+          driver.switch_to.frame(iframe)
           checkbox = driver.find_element(name: 'scroll_checkbox')
           expect(in_viewport?(checkbox)).to eq true
         end
@@ -315,8 +317,9 @@ def in_viewport?(element)
         it 'scrolls by given amount' do
           driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
           footer = driver.find_element(tag_name: 'footer')
+          delta_y = footer.rect.y
 
-          driver.action.scroll(delta_y: footer.rect.y).perform
+          driver.action.scroll(delta_y: delta_y).perform
 
           expect(in_viewport?(footer)).to eq true
         end
@@ -333,7 +336,7 @@ def in_viewport?(element)
         end
 
         it 'raises MoveTargetOutOfBoundsError when origin offset is out of viewport' do
-          driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html')
+          driver.navigate.to url_for('scrolling_tests/frame_with_nested_scrolling_frame.html')
 
           expect {
             driver.action.scroll(x: -10, y: -10, delta_y: 200).perform
