Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Fix Mouse.scroll() silently redirecting an explicit x=0/y=0 to viewport center

Andrew Chendb8a1d4af0c3
diff --git a/browser_use/actor/mouse.py b/browser_use/actor/mouse.py
index c4a05801d..e78ee7124 100644
--- a/browser_use/actor/mouse.py
+++ b/browser_use/actor/mouse.py
@@ -9,6 +9,17 @@ if TYPE_CHECKING:
from browser_use.browser.session import BrowserSession
+def _resolve_scroll_anchor(x: int | None, y: int | None, viewport_width: float, viewport_height: float) -> tuple[float, float]:
+ """Resolve the (x, y) point a scroll event should be dispatched at.
+
+ An explicit 0 must be honored as "left/top edge", not treated as "unset".
+ Only a genuinely missing (None) coordinate falls back to the viewport center.
+ """
+ scroll_x = x if x is not None else viewport_width / 2
+ scroll_y = y if y is not None else viewport_height / 2
+ return scroll_x, scroll_y
+
+
class Mouse:
"""Mouse operations for a target."""
@@ -82,27 +93,29 @@ class Mouse:
params: 'DispatchMouseEventParameters' = {'type': 'mouseMoved', 'x': x, 'y': y}
await self._client.send.Input.dispatchMouseEvent(params, session_id=self._session_id)
- async def scroll(self, x: int = 0, y: int = 0, delta_x: int | None = None, delta_y: int | None = None) -> None:
+ async def scroll(
+ self, x: int | None = None, y: int | None = None, delta_x: int | None = None, delta_y: int | None = None
+ ) -> None:
"""Scroll the page using robust CDP methods."""
if not self._session_id:
raise RuntimeError('Session ID is required for scroll operations')
- # Method 1: Try mouse wheel event (most reliable)
+ # Get viewport dimensions (used to resolve x/y when the caller doesn't specify a coordinate)
try:
- # Get viewport dimensions
layout_metrics = await self._client.send.Page.getLayoutMetrics(session_id=self._session_id)
viewport_width = layout_metrics['layoutViewport']['clientWidth']
viewport_height = layout_metrics['layoutViewport']['clientHeight']
+ except Exception:
+ viewport_width = viewport_height = 0
- # Use provided coordinates or center of viewport
- scroll_x = x if x > 0 else viewport_width / 2
- scroll_y = y if y > 0 else viewport_height / 2
+ scroll_x, scroll_y = _resolve_scroll_anchor(x, y, viewport_width, viewport_height)
- # Calculate scroll deltas (positive = down/right)
- scroll_delta_x = delta_x or 0
- scroll_delta_y = delta_y or 0
+ # Calculate scroll deltas (positive = down/right)
+ scroll_delta_x = delta_x or 0
+ scroll_delta_y = delta_y or 0
- # Dispatch mouse wheel event
+ # Method 1: Try mouse wheel event (most reliable)
+ try:
await self._client.send.Input.dispatchMouseEvent(
params={
'type': 'mouseWheel',
@@ -120,7 +133,12 @@ class Mouse:
# Method 2: Fallback to synthesizeScrollGesture
try:
- params: 'SynthesizeScrollGestureParameters' = {'x': x, 'y': y, 'xDistance': delta_x or 0, 'yDistance': delta_y or 0}
+ params: 'SynthesizeScrollGestureParameters' = {
+ 'x': scroll_x,
+ 'y': scroll_y,
+ 'xDistance': delta_x or 0,
+ 'yDistance': delta_y or 0,
+ }
await self._client.send.Input.synthesizeScrollGesture(
params,
session_id=self._session_id,
diff --git a/tests/ci/test_actor_mouse_scroll_anchor.py b/tests/ci/test_actor_mouse_scroll_anchor.py
new file mode 100644
index 000000000..d5a795c27
--- /dev/null
+++ b/tests/ci/test_actor_mouse_scroll_anchor.py
@@ -0,0 +1,27 @@
+"""Test Mouse.scroll's anchor-point resolution honors explicit x=0/y=0 (see actor/mouse.py)."""
+
+from browser_use.actor.mouse import _resolve_scroll_anchor
+
+
+def test_explicit_zero_x_is_honored_as_left_edge():
+ scroll_x, scroll_y = _resolve_scroll_anchor(x=0, y=100, viewport_width=1000, viewport_height=800)
+ assert scroll_x == 0
+ assert scroll_y == 100
+
+
+def test_explicit_zero_y_is_honored_as_top_edge():
+ scroll_x, scroll_y = _resolve_scroll_anchor(x=100, y=0, viewport_width=1000, viewport_height=800)
+ assert scroll_x == 100
+ assert scroll_y == 0
+
+
+def test_both_unset_falls_back_to_viewport_center():
+ scroll_x, scroll_y = _resolve_scroll_anchor(x=None, y=None, viewport_width=1000, viewport_height=800)
+ assert scroll_x == 500
+ assert scroll_y == 400
+
+
+def test_positive_coordinates_are_passed_through():
+ scroll_x, scroll_y = _resolve_scroll_anchor(x=42, y=99, viewport_width=1000, viewport_height=800)
+ assert scroll_x == 42
+ assert scroll_y == 99