[py] use convenience methods for scrolling

Author: titusfortner

py/selenium/webdriver/common/action_chains.py

@@ -18,7 +18,7 @@
 """
 The ActionChains implementation,
 """
-from typing import Union
+from .actions.wheel_input import ScrollOrigin
 
 from .utils import keys_to_typing
 from .actions.action_builder import ActionBuilder
@@ -323,25 +323,54 @@ 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: Union[str, WebElement] = "viewport"):
+    def scroll_to_element(self, element: WebElement):
         """
-        Scrolls by the provided amount from a designated origination point.
+        If the element is outside the viewport, scrolls the bottom of the element to the bottom of the viewport.
+
+        :Args:
+         - element: Which element to scroll into the viewport.
+        """
+
+        self.w3c_actions.wheel_action.scroll(origin=element)
+        return self
+
+    def scroll_by_amount(self, delta_x: int, delta_y: int):
+        """
+        Scrolls by provided amounts with the origin in the top left corner of the viewport.
+
+        :Args:
+         - 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.
+        """
+
+        self.w3c_actions.wheel_action.scroll(delta_x=delta_x, delta_y=delta_y)
+        return self
+
+    def scroll_from_origin(self, scroll_origin: ScrollOrigin, delta_x: int, delta_y: int):
+        """
+        Scrolls by provided amount based on a provided origin.
         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: 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.
+         - origin: Where scroll originates (viewport or element center) plus provided offsets.
          - 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)
+
+        if not isinstance(scroll_origin, ScrollOrigin):
+            raise TypeError('Expected object of type ScrollOrigin, got: '
+                            '{}'.format(type(scroll_origin)))
+
+        self.w3c_actions.wheel_action.scroll(origin=scroll_origin.origin,
+                                             x=scroll_origin.x_offset,
+                                             y=scroll_origin.y_offset,
+                                             delta_x=delta_x,
+                                             delta_y=delta_y)
         return self
 
     # Context manager so ActionChains can be used in a 'with .. as' statements.

py/selenium/webdriver/common/actions/wheel_actions.py

@@ -29,6 +29,6 @@ def pause(self, duration=0):
         self.source.create_pause(duration)
         return self
 
-    def scroll(self, x, y, delta_x, delta_y, duration, origin):
+    def scroll(self, x=0, y=0, delta_x=0, delta_y=0, duration=0, origin="viewport"):
         self.source.create_scroll(x, y, delta_x, delta_y, duration, origin)
         return self

py/selenium/webdriver/common/actions/wheel_input.py

@@ -21,6 +21,34 @@
 from selenium.webdriver.remote.webelement import WebElement
 
 
+class ScrollOrigin:
+
+    def __init__(self, origin: Union[str, WebElement], x_offset: int, y_offset: int) -> None:
+        self._origin = origin
+        self._x_offset = x_offset
+        self._y_offset = y_offset
+
+    @classmethod
+    def from_element(cls, element: WebElement, x_offset: int = 0, y_offset: int = 0):
+        return cls(element, x_offset, y_offset)
+
+    @classmethod
+    def from_viewport(cls, x_offset: int = 0, y_offset: int = 0):
+        return cls('viewport', x_offset, y_offset)
+
+    @property
+    def origin(self) -> Union[str, WebElement]:
+        return self._origin
+
+    @property
+    def x_offset(self) -> int:
+        return self._x_offset
+
+    @property
+    def y_offset(self) -> int:
+        return self._y_offset
+
+
 class WheelInput(InputDevice):
 
     def __init__(self, name) -> None:

py/test/selenium/webdriver/common/interactions_tests.py

@@ -18,6 +18,7 @@
 """Tests for advanced user interactions."""
 import pytest
 from selenium.common.exceptions import MoveTargetOutOfBoundsException
+from selenium.webdriver.common.actions.wheel_input import ScrollOrigin
 
 from selenium.webdriver.common.by import By
 from selenium.webdriver.common.keys import Keys
@@ -269,7 +270,7 @@ def test_can_scroll_to_element(driver, pages):
 
     assert not _in_viewport(driver, iframe)
 
-    ActionChains(driver).scroll(0, 0, 0, 0, origin=iframe).perform()
+    ActionChains(driver).scroll_to_element(iframe).perform()
 
     assert _in_viewport(driver, iframe)
 
@@ -279,8 +280,9 @@ def test_can_scroll_to_element(driver, pages):
 def test_can_scroll_from_element_by_amount(driver, pages):
     pages.load("scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html")
     iframe = driver.find_element(By.TAG_NAME, "iframe")
+    scroll_origin = ScrollOrigin.from_element(iframe)
 
-    ActionChains(driver).scroll(0, 0, 0, 200, origin=iframe).pause(0.2).perform()
+    ActionChains(driver).scroll_from_origin(scroll_origin, 0, 200).pause(0.2).perform()
 
     driver.switch_to.frame(iframe)
     checkbox = driver.find_element(By.NAME, "scroll_checkbox")
@@ -292,8 +294,9 @@ def test_can_scroll_from_element_by_amount(driver, pages):
 def test_can_scroll_from_element_with_offset_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")
+    scroll_origin = ScrollOrigin.from_element(footer, 0, -50)
 
-    ActionChains(driver).scroll(0, -50, 0, 200, origin=footer).pause(0.2).perform()
+    ActionChains(driver).scroll_from_origin(scroll_origin, 0, 200).pause(0.2).perform()
 
     iframe = driver.find_element(By.TAG_NAME, "iframe")
     driver.switch_to.frame(iframe)
@@ -306,9 +309,10 @@ def test_can_scroll_from_element_with_offset_by_amount(driver, pages):
 def test_errors_when_element_offset_not_in_viewport(driver, pages):
     pages.load("scrolling_tests/frame_with_nested_scrolling_frame_out_of_view.html")
     footer = driver.find_element(By.TAG_NAME, "footer")
+    scroll_origin = ScrollOrigin.from_element(footer, 0, 50)
 
     with pytest.raises(MoveTargetOutOfBoundsException):
-        ActionChains(driver).scroll(0, 50, 0, 200, origin=footer).perform()
+        ActionChains(driver).scroll_from_origin(scroll_origin, 0, 200).pause(0.2).perform()
 
 
 @pytest.mark.xfail_firefox
@@ -318,7 +322,7 @@ def test_can_scroll_from_viewport_by_amount(driver, pages):
     footer = driver.find_element(By.TAG_NAME, "footer")
     delta_y = footer.rect['y']
 
-    ActionChains(driver).scroll(0, 0, 0, delta_y).pause(0.2).perform()
+    ActionChains(driver).scroll_by_amount(0, delta_y).pause(0.2).perform()
 
     assert _in_viewport(driver, footer)
 
@@ -327,8 +331,9 @@ 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")
+    scroll_origin = ScrollOrigin.from_viewport(10, 10)
 
-    ActionChains(driver).scroll(10, 10, 0, 200).pause(0.2).perform()
+    ActionChains(driver).scroll_from_origin(scroll_origin, 0, 200).pause(0.2).perform()
 
     iframe = driver.find_element(By.TAG_NAME, "iframe")
     driver.switch_to.frame(iframe)
@@ -340,9 +345,10 @@ def test_can_scroll_from_viewport_with_offset_by_amount(driver, pages):
 @pytest.mark.xfail_remote
 def test_errors_when_origin_offset_not_in_viewport(driver, pages):
     pages.load("scrolling_tests/frame_with_nested_scrolling_frame.html")
+    scroll_origin = ScrollOrigin.from_viewport(-10, -10)
 
     with pytest.raises(MoveTargetOutOfBoundsException):
-        ActionChains(driver).scroll(-10, -10, 0, 200).perform()
+        ActionChains(driver).scroll_from_origin(scroll_origin, 0, 200).pause(0.2).perform()
 
 
 def _get_events(driver):