feat: add ScrollAPI for enhanced page scrolling capabilities

Author: thalissonvs

pydoll/browser/tab.py

@@ -50,6 +50,7 @@
     TopLevelTargetRequired,
     WaitElementTimeout,
 )
+from pydoll.interactions.scroll import ScrollAPI
 from pydoll.protocol.browser.types import DownloadBehavior, DownloadProgressState
 from pydoll.protocol.page.events import PageEvent
 from pydoll.protocol.page.types import ScreenshotFormat
@@ -131,6 +132,7 @@ def __init__(
         self._intercept_file_chooser_dialog_enabled = False
         self._cloudflare_captcha_callback_id: Optional[int] = None
         self._request: Optional[Request] = None
+        self._scroll: Optional[ScrollAPI] = None
         logger.debug(
             (
                 f'Tab initialized: target_id={self._target_id}, '
@@ -176,6 +178,18 @@ def request(self) -> Request:
             self._request = Request(self)
         return self._request
 
+    @property
+    def scroll(self) -> ScrollAPI:
+        """
+        Get the scroll API for controlling page scroll behavior.
+
+        Returns:
+            ScrollAPI: An instance of the ScrollAPI class for scroll operations.
+        """
+        if self._scroll is None:
+            self._scroll = ScrollAPI(self)
+        return self._scroll
+
     @property
     def intercept_file_chooser_dialog_enabled(self) -> bool:
         """Whether file chooser dialog interception is active."""

pydoll/constants.py

@@ -15,6 +15,13 @@ class PageLoadState(str, Enum):
     INTERACTIVE = 'interactive'
 
 
+class ScrollPosition(str, Enum):
+    UP = 'up'
+    DOWN = 'down'
+    LEFT = 'left'
+    RIGHT = 'right'
+
+
 class Scripts:
     ELEMENT_VISIBLE = """
     function() {
@@ -268,6 +275,87 @@ class Scripts:
 }})();
 """
 
+    SCROLL_BY = """
+new Promise((resolve) => {{
+    const behavior = '{behavior}';
+    if (behavior === 'auto') {{
+        window.scrollBy({{
+            {axis}: {distance},
+            behavior: 'auto'
+        }});
+        resolve();
+    }} else {{
+        const onScrollEnd = () => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }};
+        window.addEventListener('scrollend', onScrollEnd);
+        window.scrollBy({{
+            {axis}: {distance},
+            behavior: 'smooth'
+        }});
+        setTimeout(() => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }}, 2000);
+    }}
+}});
+"""
+
+    SCROLL_TO_TOP = """
+new Promise((resolve) => {{
+    const behavior = '{behavior}';
+    if (behavior === 'auto') {{
+        window.scrollTo({{
+            top: 0,
+            behavior: 'auto'
+        }});
+        resolve();
+    }} else {{
+        const onScrollEnd = () => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }};
+        window.addEventListener('scrollend', onScrollEnd);
+        window.scrollTo({{
+            top: 0,
+            behavior: 'smooth'
+        }});
+        setTimeout(() => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }}, 2000);
+    }}
+}});
+"""
+
+    SCROLL_TO_BOTTOM = """
+new Promise((resolve) => {{
+    const behavior = '{behavior}';
+    if (behavior === 'auto') {{
+        window.scrollTo({{
+            top: document.body.scrollHeight,
+            behavior: 'auto'
+        }});
+        resolve();
+    }} else {{
+        const onScrollEnd = () => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }};
+        window.addEventListener('scrollend', onScrollEnd);
+        window.scrollTo({{
+            top: document.body.scrollHeight,
+            behavior: 'smooth'
+        }});
+        setTimeout(() => {{
+            window.removeEventListener('scrollend', onScrollEnd);
+            resolve();
+        }}, 2000);
+    }}
+}});
+"""
+
 
 class Key(tuple[str, int], Enum):
     BACKSPACE = ('Backspace', 8)

pydoll/interactions/__init__.py

@@ -0,0 +1,3 @@
+from pydoll.interactions.scroll import ScrollAPI
+
+__all__ = ['ScrollAPI']

pydoll/interactions/scroll.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydoll.commands import RuntimeCommands
+from pydoll.constants import Scripts, ScrollPosition
+
+if TYPE_CHECKING:
+    from pydoll.browser.tab import Tab
+
+
+class ScrollAPI:
+    """
+    API for controlling page scroll behavior.
+
+    Provides methods for scrolling the page in different directions,
+    to specific positions, or by relative distances.
+    """
+
+    def __init__(self, tab: Tab):
+        """
+        Initialize the ScrollAPI with a tab instance.
+
+        Args:
+            tab: Tab instance to execute scroll commands on.
+        """
+        self._tab = tab
+
+    async def by(
+        self,
+        position: ScrollPosition,
+        distance: int | float,
+        smooth: bool = True,
+    ):
+        """
+        Scroll the page by a relative distance in the specified direction.
+
+        Args:
+            position: Direction to scroll (UP, DOWN, LEFT, RIGHT).
+            distance: Number of pixels to scroll.
+            smooth: Use smooth scrolling animation if True, instant if False.
+        """
+        axis, scroll_distance = self._get_axis_and_distance(position, distance)
+        behavior = self._get_behavior(smooth)
+
+        script = Scripts.SCROLL_BY.format(
+            axis=axis,
+            distance=scroll_distance,
+            behavior=behavior,
+        )
+
+        await self._execute_script_await_promise(script)
+
+    async def to_top(self, smooth: bool = True):
+        """
+        Scroll to the top of the page (Y=0).
+
+        Args:
+            smooth: Use smooth scrolling animation if True, instant if False.
+        """
+        behavior = self._get_behavior(smooth)
+        script = Scripts.SCROLL_TO_TOP.format(behavior=behavior)
+        await self._execute_script_await_promise(script)
+
+    async def to_bottom(self, smooth: bool = True):
+        """
+        Scroll to the bottom of the page (Y=document.body.scrollHeight).
+
+        Args:
+            smooth: Use smooth scrolling animation if True, instant if False.
+        """
+        behavior = self._get_behavior(smooth)
+        script = Scripts.SCROLL_TO_BOTTOM.format(behavior=behavior)
+        await self._execute_script_await_promise(script)
+
+    @staticmethod
+    def _get_axis_and_distance(
+        position: ScrollPosition, distance: int | float
+    ) -> tuple[str, int | float]:
+        """
+        Convert scroll position to axis and signed distance.
+
+        Args:
+            position: Direction to scroll.
+            distance: Absolute distance to scroll.
+
+        Returns:
+            Tuple of (axis, signed_distance) where axis is 'left' or 'top'
+            and signed_distance is positive or negative based on direction.
+        """
+        if position in {ScrollPosition.UP, ScrollPosition.DOWN}:
+            axis = 'top'
+            scroll_distance = -distance if position == ScrollPosition.UP else distance
+            return axis, scroll_distance * 10
+
+        axis = 'left'
+        scroll_distance = -distance if position == ScrollPosition.LEFT else distance
+        return axis, scroll_distance * 10
+
+    @staticmethod
+    def _get_behavior(smooth: bool) -> str:
+        """
+        Convert smooth boolean to CSS scroll behavior value.
+
+        Args:
+            smooth: Whether to use smooth scrolling.
+
+        Returns:
+            'smooth' if smooth is True, 'auto' otherwise.
+        """
+        return 'smooth' if smooth else 'auto'
+
+    async def _execute_script_await_promise(self, script: str):
+        """
+        Execute JavaScript and await promise resolution.
+
+        Args:
+            script: JavaScript code that returns a Promise.
+        """
+        command = RuntimeCommands.evaluate(expression=script, await_promise=True)
+        return await self._tab._execute_command(command)