Skip to content

🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev

refactor(mcp)!: Combine all mouse tools into one mouse actions tool to chain actions

Karim shoair69bdfd5335a7
diff --git a/agent-skill/Scrapling-Skill.zip b/agent-skill/Scrapling-Skill.zip
index 9b2ca83..57032da 100644
Binary files a/agent-skill/Scrapling-Skill.zip and b/agent-skill/Scrapling-Skill.zip differ
diff --git a/agent-skill/Scrapling-Skill/references/mcp-server.md b/agent-skill/Scrapling-Skill/references/mcp-server.md
index a07d1ef..b149f9a 100644
--- a/agent-skill/Scrapling-Skill/references/mcp-server.md
+++ b/agent-skill/Scrapling-Skill/references/mcp-server.md
@@ -1,8 +1,8 @@
# Scrapling MCP Server
-The Scrapling MCP server exposes nineteen tools over the MCP protocol. It supports CSS-selector-based content narrowing (reducing tokens by extracting only relevant elements before returning results), three levels of scraping capability (plain HTTP, browser-rendered, and stealth/anti-bot bypass), persistent browser session management, mouse actions, batch field filling, keyboard shortcuts, and page screenshots returned as real image content blocks. Fetch tools come in two modes: one-shot tools (`browser_fetch_once`, `browser_fetch_many_once`, `browser_stealth_fetch_once`, `browser_stealth_fetch_many_once`) each launch and close their own browser, while `browser_fetch` and `session_make_request` work through sessions opened with `browser_open`/`open_request_session`.
+The Scrapling MCP server exposes seventeen tools over the MCP protocol. It supports CSS-selector-based content narrowing (reducing tokens by extracting only relevant elements before returning results), three levels of scraping capability (plain HTTP, browser-rendered, and stealth/anti-bot bypass), persistent browser session management, mouse actions, batch field filling, keyboard shortcuts, and page screenshots returned as real image content blocks. Fetch tools come in two modes: one-shot tools (`browser_fetch_once`, `browser_fetch_many_once`, `browser_stealth_fetch_once`, `browser_stealth_fetch_many_once`) each launch and close their own browser, while `browser_fetch` and `session_make_request` work through sessions opened with `browser_open`/`open_request_session`.
-Fetch and HTTP request tools return a `ResponseModel` with fields: `status` (int), `content` (list of strings), `url` (str). Bulk tools return a list of these responses. The `browser_screenshot` tool returns a list of MCP content blocks: an `ImageContent` (the screenshot bytes) followed by a `TextContent` (the post-redirect URL). `browser_snapshot`, `browser_mouse_move`, `browser_mouse_wheel`, `browser_click`, `browser_fill_fields`, and `browser_press_key` return plain text.
+Fetch and HTTP request tools return a `ResponseModel` with fields: `status` (int), `content` (list of strings), `url` (str). Bulk tools return a list of these responses. The `browser_screenshot` tool returns a list of MCP content blocks: an `ImageContent` (the screenshot bytes) followed by a `TextContent` (the post-redirect URL). `browser_snapshot`, `browser_mouse`, `browser_fill_fields`, and `browser_press_key` return plain text.
## Shadow DOM
@@ -163,57 +163,40 @@ With `extraction_type="snapshot"`, the response keeps `status` and `url` and ret
Returns a plain-text AI ARIA snapshot of the current whole page, including element roles, names, and references. Takes `session_id` from `browser_open` and optional `depth` to limit the tree. Element positions and sizes in viewport CSS pixels are included by default; set `boxes=false` to omit them. Use it after `browser_fetch` finishes. Raises for an unknown or HTTP session, or a missing, closed, or busy page.
-### `browser_mouse_move` -- Hover by selector, snapshot reference, or coordinates
+### `browser_mouse` -- Chain mouse moves, hovers, clicks, and scrolling
-Moves the native mouse on the existing page in a dynamic or stealthy browser session. Call `browser_fetch` first, then use `browser_snapshot` to find references or coordinates. Supply exactly one target: `selector`, `ref`, or both `x` and `y`.
+Runs native mouse actions in order on the existing page in a dynamic or stealthy browser session. Call `browser_fetch` first. Use `browser_snapshot` to find current references or coordinates.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `session_id` | str | required | ID of an open browser session |
-| `x`, `y` | number or null | null | Finite CSS pixel coordinates from the main frame viewport's top-left; supply both |
-| `steps` | int | 1 | Number of mousemove events for coordinate moves, at least 1; ignored for selector/reference hovers |
-| `selector` | str or null | null | Nonempty Playwright selector, such as `button[type="submit"]` or `xpath=//button[@type="submit"]` |
-| `ref` | str or null | null | Nonempty reference from the current `browser_snapshot`, such as `e2` |
-| `timeout` | number | 30000 | Finite nonnegative timeout in milliseconds for selector/reference hovers; 0 disables the limit |
+| `actions` | list[object] | required | Nonempty ordered list of `move`, `click`, or `wheel` actions |
-Selector and reference hovers use Playwright's locator hover, which waits for the target to be ready and scrolls it into view. A selector must match exactly one element. Pass the exact snapshot reference value, such as `ref="e2"`. Take a new snapshot if the reference is stale. Coordinate moves use the native mouse directly, without automatic waiting or scrolling. Coordinates are viewport CSS pixels, not full-page screenshot coordinates. `timeout` does not apply to coordinate moves.
+| Action `type` | Fields | Behavior |
+|---------------|--------|----------|
+| `move` | Target, `steps=1`, `timeout=30000` | Hover over an element or move to coordinates; `steps` is the number of coordinate mousemove events, at least 1, and is ignored for element targets |
+| `click` | Target, `button="left"`, `click_count=1`, `delay=0`, `timeout=30000` | Click with the left, right, or middle button; `click_count` must be at least 1, with 2 for a double-click; `delay` is finite nonnegative milliseconds between press and release |
+| `wheel` | `delta_x=0`, `delta_y=0` | Scroll at the current pointer position; finite CSS pixel deltas allow fractions and zero; positive moves right/down, negative moves left/up |
-Returns plain text without an automatic snapshot. Use `browser_snapshot` to inspect the page afterward. Invalid targets, unknown sessions, and missing, closed, or busy pages return an error.
+Each move or click needs exactly one target: a nonempty Playwright `selector`, a nonempty snapshot `ref` such as `"e2"`, or both `x` and `y`. Coordinates must be finite viewport CSS pixels measured from the main frame's top-left, not full-page screenshot coordinates. Selectors must match exactly one element. Refresh stale references with `browser_snapshot`.
-### `browser_mouse_wheel` -- Scroll at the current pointer position
+Element targets use native locator hover or click, which waits for readiness and scrolls into view. Their per-action `timeout` is finite nonnegative milliseconds; 0 disables it. Coordinate actions use the native mouse without automatic waiting or scrolling and ignore `timeout`. Coordinate clicks move the mouse, then press and release, without waiting for navigation. Wheel actions neither move the pointer nor wait for scrolling, animations, or loaded content to finish. The page may prevent scrolling, or the scrollable area may be at its edge.
-Sends a native mouse wheel event on the existing page in a dynamic or stealthy browser session. Call `browser_fetch` first. To target a scrollable area, use `browser_mouse_move` with a selector, snapshot reference, or coordinates before scrolling.
+For example, hover over a panel and scroll it in one call:
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `session_id` | str | required | ID of an open browser session |
-| `delta_x` | number | 0 | Finite horizontal delta in CSS pixels; positive moves right, negative moves left |
-| `delta_y` | number | 0 | Finite vertical delta in CSS pixels; positive moves down, negative moves up |
-
-Fractional values and zero are allowed. Uses `page.mouse.wheel` at the current pointer position without moving the mouse, injecting a page script, or navigating. Dispatch does not guarantee scrolling: the page can prevent the event, or the scrollable area can be at its edge. It does not wait for scrolling, animations, or content loaded by scrolling to finish.
-
-Returns `Wheel event sent.` as plain text without an automatic snapshot. Use `browser_snapshot` to inspect the current page afterward. Errors are not retried. Invalid deltas, unknown or HTTP sessions, and missing, closed, or busy pages return an error.
-
-### `browser_click` -- Click by selector, snapshot reference, or coordinates
-
-Clicks on the existing page in a dynamic or stealthy browser session. Call `browser_fetch` first. Supply exactly one target: `selector`, `ref`, or both `x` and `y`.
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `session_id` | str | required | ID of an open browser session |
-| `selector` | str or null | null | Nonempty Playwright selector, such as `button[type="submit"]` or `xpath=//button[@type="submit"]` |
-| `ref` | str or null | null | Nonempty reference from the current `browser_snapshot`, such as `e2` |
-| `x`, `y` | number or null | null | Finite CSS pixel coordinates from the main frame viewport's top-left; supply both |
-| `button` | `"left"` / `"right"` / `"middle"` | `"left"` | Button to click |
-| `click_count` | int | 1 | Number of clicks, at least 1; use 2 for a double-click |
-| `delay` | number | 0 | Finite nonnegative milliseconds between press and release |
-| `timeout` | number | 30000 | Finite nonnegative timeout in milliseconds for selector/reference clicks; 0 disables the limit |
-
-Selector and reference clicks use Playwright's locator click, which waits for the target to be ready and scrolls it into view. A selector must match exactly one element. Pass the exact snapshot reference value, such as `ref="e2"`. Take a new snapshot if the reference is stale. Coordinate clicks move the mouse before pressing and releasing the button, with no scroll or navigation wait. `timeout` does not apply to coordinate clicks.
+```json
+{
+ "session_id": "browser",
+ "actions": [
+ {"type": "move", "selector": "#results"},
+ {"type": "wheel", "delta_y": 500}
+ ]
+}
+```
-Invalid targets, unknown sessions, and missing, closed, or busy pages return an error.
+The whole list is validated before execution, and the page stays reserved for the full sequence. The first action error stops the batch and reports its one-based action number, type, and native error. Cancellation also stops the batch and remains cancellation. Earlier actions stay in effect and are never retried. A cancelled or timed-out click attempts to release the button while the page is open; this does not undo the click. The page reservation is released after success, error, or cancellation.
-Returns plain text without an automatic snapshot. Use `browser_snapshot` to inspect the page afterward. A cancelled or timed-out click sends a button release before the page can be reused, even if it was still waiting for a target. This does not undo page actions. Do not repeat a failed click without checking the page state.
+Returns `Mouse actions completed.` as plain text without a snapshot. Use `browser_snapshot` before retrying after an error or when the next action depends on a page change. Invalid targets, unknown or HTTP sessions, and missing, closed, or busy pages return an error.
### `browser_fill_fields` -- Fill one or more page fields in order
@@ -239,11 +222,11 @@ Selectors must match exactly one element. Use current snapshot references, such
With `slowly=true`, native `press_sequentially` types each character with a fresh random delay of 50-150 ms, clearing first unless the field has `clear=false`. All field types get a fresh random pause of 100-300 ms before the next field, with no pause before the first or after the last. The timeout applies separately to each native action, including clearing and each character press; pauses between fields are outside it.
-Returns `Fields filled.` as plain text without echoing values, submitting forms, or taking a snapshot. An error or cancellation stops the remaining fields; completed changes stay and are not retried. The page reservation is released afterward. Use `browser_snapshot` to check the page before retrying. To submit with Enter, use `browser_press_key` with `keys=["Enter"]`; first focus the intended control with `browser_click` if needed, since the batch may end on another field. Unknown or HTTP sessions and missing, closed, or busy pages return an error.
+Returns `Fields filled.` as plain text without echoing values, submitting forms, or taking a snapshot. An error or cancellation stops the remaining fields; completed changes stay and are not retried. The page reservation is released afterward. Use `browser_snapshot` to check the page before retrying. To submit with Enter, use `browser_press_key` with `keys=["Enter"]`; first focus the intended control with a `browser_mouse` click action if needed, since the batch may end on another field. Unknown or HTTP sessions and missing, closed, or busy pages return an error.
### `browser_press_key` -- Chain keys and shortcuts at the current focus
-Presses each item in order through native `page.keyboard.press` on the existing page in a dynamic or stealthy browser session. The page stays reserved for the full sequence. Call `browser_fetch` first. Use `browser_click` to focus a control before pressing when needed; later presses follow any focus changes caused by earlier ones.
+Presses each item in order through native `page.keyboard.press` on the existing page in a dynamic or stealthy browser session. The page stays reserved for the full sequence. Call `browser_fetch` first. Use a `browser_mouse` click action to focus a control before pressing when needed; later presses follow any focus changes caused by earlier ones.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
@@ -307,9 +290,7 @@ Requires an open browser session. Call `browser_open` first, then pass the `sess
| Multiple plain HTTP requests to one site | `open_request_session` + `session_make_request` per request |
| Need a screenshot of a page | `browser_open` + `browser_screenshot` with `session_id` |
| Read the current page's AI ARIA snapshot | `browser_snapshot` with `session_id` |
-| Move the mouse on the current page | `browser_mouse_move` with `session_id` |
-| Scroll a page or nested panel | `browser_mouse_wheel` with `session_id` |
-| Click by selector, snapshot ref, or coordinates | `browser_click` with `session_id` |
+| Move, hover, click, or scroll in order | `browser_mouse` with `session_id` |
| Fill one or more page fields in order | `browser_fill_fields` with `session_id` |
| Chain keys or keyboard shortcuts | `browser_press_key` with `session_id` |
@@ -402,7 +383,7 @@ The MCP server name when registering with a client is `ScraplingServer`. The com
## Connecting to remote browsers
-`browser_open` doesn't have to launch a browser locally. Pass a `cdp_url` and it connects to an already-running browser through the Chrome DevTools Protocol, whether that browser is on the same machine, another host, or a managed browser provider. Both session types (`dynamic` and `stealthy`) accept it, and the `session_id` you get back is used with `browser_fetch`, `browser_snapshot`, `browser_mouse_move`, `browser_mouse_wheel`, `browser_click`, `browser_fill_fields`, `browser_press_key`, and `browser_screenshot` as usual.
+`browser_open` doesn't have to launch a browser locally. Pass a `cdp_url` and it connects to an already-running browser through the Chrome DevTools Protocol, whether that browser is on the same machine, another host, or a managed browser provider. Both session types (`dynamic` and `stealthy`) accept it, and the `session_id` you get back is used with `browser_fetch`, `browser_snapshot`, `browser_mouse`, `browser_fill_fields`, `browser_press_key`, and `browser_screenshot` as usual.
The URL can be a WebSocket endpoint (`ws://`/`wss://`), which is what managed browser providers hand out, or the HTTP endpoint of a browser started with `--remote-debugging-port=9222`, reached as `cdp_url="http://localhost:9222"`.
diff --git a/docs/ai/mcp-server.md b/docs/ai/mcp-server.md
index 0613447..e32cffd 100644
--- a/docs/ai/mcp-server.md
+++ b/docs/ai/mcp-server.md
@@ -6,7 +6,7 @@ The **Scrapling MCP Server** is a new feature that brings Scrapling's powerful W
## Features
-The Scrapling MCP Server provides nineteen tools for web scraping and browser interaction, split into two modes: one-shot tools that each launch and close their own browser/client, and session tools that open a browser or an HTTP session once and then work through it.
+The Scrapling MCP Server provides seventeen tools for web scraping and browser interaction, split into two modes: one-shot tools that each launch and close their own browser/client, and session tools that open a browser or an HTTP session once and then work through it.
### One-shot tools
@@ -43,9 +43,7 @@ The Scrapling MCP Server provides nineteen tools for web scraping and browser in
#### Mouse Actions
-- **`browser_mouse_move`**: Move the browser's mouse to reveal hover menus, tooltips, and other content that appears on hover. Target elements through selectors or snapshot references, with automatic waiting and scrolling into view. Coordinate moves support multiple steps for controls that react as the pointer moves.
-- **`browser_mouse_wheel`**: Scroll pages, menus, and nested panels vertically or horizontally with the browser's native mouse wheel. Helps the AI explore long feeds and content that loads as you scroll. The AI can move the mouse first to choose a scrollable area.
-- **`browser_click`**: Click buttons, follow links, and use other page controls through selectors, snapshot references, or page coordinates. Supports left, right, and middle clicks, plus double-clicks.
+- **`browser_mouse`**: Chain native mouse moves, hovers, clicks, and scrolling in one call. Reveal hover menus and tooltips, click buttons and links, and scroll long pages or nested panels vertically or horizontally. Moves and clicks target selectors, snapshot references, or coordinates, with automatic waiting and scrolling into view for element targets. Supports coordinate movement in multiple steps, left, right, and middle clicks, plus double-clicks. The AI can move over a panel and scroll it in the same call.
#### Text Input and Keyboard
@@ -211,7 +209,7 @@ You can also set the `SCRAPLING_EXECUTABLE_PATH` environment variable before sta
```
Open a stealthy browser session on wss://cdp.provider.example/session/abc123, then use it to scrape the product details from https://shop.example.com. Close the session when you're done.
```
-Both browser session types (`dynamic` and `stealthy`) accept it, and the `session_id` you get back is used with `browser_fetch`, `browser_snapshot`, `browser_mouse_move`, `browser_mouse_wheel`, `browser_click`, `browser_fill_fields`, `browser_press_key`, and `browser_screenshot` as usual.
+Both browser session types (`dynamic` and `stealthy`) accept it, and the `session_id` you get back is used with `browser_fetch`, `browser_snapshot`, `browser_mouse`, `browser_fill_fields`, `browser_press_key`, and `browser_screenshot` as usual.
The URL can be a WebSocket endpoint (`ws://`/`wss://`), which is what managed browser providers hand out, or the HTTP endpoint of a browser you started yourself with the remote debugging port enabled:
```commandline
diff --git a/docs/api-reference/mcp-server.md b/docs/api-reference/mcp-server.md
index 9b6e405..d7296bd 100644
--- a/docs/api-reference/mcp-server.md
+++ b/docs/api-reference/mcp-server.md
@@ -5,7 +5,7 @@ search:
# MCP Server API Reference
-The **Scrapling MCP Server** provides nineteen tools for web scraping and browser interaction through the Model Context Protocol (MCP). This server integrates Scrapling's capabilities directly into AI chatbots and agents, allowing conversational web scraping with advanced anti-bot bypass features.
+The **Scrapling MCP Server** provides seventeen tools for web scraping and browser interaction through the Model Context Protocol (MCP). This server integrates Scrapling's capabilities directly into AI chatbots and agents, allowing conversational web scraping with advanced anti-bot bypass features.
You can start the MCP server by running:
@@ -30,7 +30,7 @@ server = ScraplingMCPServer(executable_path="/path/to/chromium")
## Response Model
-The standardized response structure returned by the fetch and HTTP request tools. Bulk tools return a list of these responses. Session management tools use the models below, `browser_screenshot` returns image and text content blocks, and `browser_snapshot`, `browser_mouse_move`, `browser_mouse_wheel`, `browser_click`, `browser_fill_fields`, and `browser_press_key` return plain text.
+The standardized response structure returned by the fetch and HTTP request tools. Bulk tools return a list of these responses. Session management tools use the models below, `browser_screenshot` returns image and text content blocks, and `browser_snapshot`, `browser_mouse`, `browser_fill_fields`, and `browser_press_key` return plain text.
## ::: scrapling.core.ai.ResponseModel
handler: python
@@ -57,9 +57,7 @@ Model classes for session management:
The main MCP server class that provides all web scraping tools:
- **`browser_snapshot`**: Inspect the current page without reloading it. Structured text includes element roles, names, references, positions, and sizes to help the AI target page controls.
-- **`browser_mouse_move`**: Reveal hover menus and tooltips with the browser's mouse. Target elements through selectors or snapshot references, with automatic waiting and scrolling into view, or use coordinates with movement in multiple steps.
-- **`browser_mouse_wheel`**: Scroll pages and nested panels vertically or horizontally with native mouse wheel events. Works at the current pointer position, so mouse movement can choose the scrollable area.
-- **`browser_click`**: Click buttons, links, and other controls using selectors, snapshot references, or page coordinates. Supports left, right, and middle clicks, plus double-clicks.
+- **`browser_mouse`**: Chain native mouse moves, hovers, clicks, and scrolling in one call. Reveal hover menus and tooltips, click buttons and links, or move over a nested panel and scroll it vertically or horizontally. Moves and clicks target selectors, snapshot references, or coordinates, with automatic waiting and scrolling into view for element targets. Supports coordinate movement in multiple steps, left, right, and middle clicks, plus double-clicks.
- **`browser_fill_fields`**: Fill text fields, check or uncheck boxes, select radio buttons, and choose one or more native dropdown options by visible labels in one call. Targets one or more fields anywhere on the page through selectors or snapshot references. Replace or clear text, or type at the current caret without clearing existing content. Slow mode types text one character at a time with random pauses between characters and fields.
- **`browser_press_key`**: Chain keys and shortcuts in one call to move between fields, submit forms, dismiss menus, or select and delete text. Each press uses the browser's current focus.
- **`browser_fetch`**: Fetch a page through an open browser session and extract HTML, Markdown, text, or a structured snapshot. Snapshots can cover the whole page or a chosen element and include element references, positions, and sizes for later interaction.
diff --git a/scrapling/core/ai.py b/scrapling/core/ai.py
index 1a6cead..55a4668 100644
--- a/scrapling/core/ai.py
+++ b/scrapling/core/ai.py
@@ -109,6 +109,43 @@ _INPUT_TOOL_ANNOTATIONS = ToolAnnotations(
)
+class _MouseTarget(TypedDict, total=False):
+ selector: Optional[NonEmptyString]
+ ref: Optional[NonEmptyString]
+ x: Optional[FiniteFloat]
+ y: Optional[FiniteFloat]
+ timeout: Annotated[
+ NonNegativeFiniteFloat, Field(default=30000, description="Selector/ref timeout in ms; 0 disables it.")
+ ]
+
+
+class _MouseMove(_MouseTarget):
+ type: Literal["move"]
+ steps: NotRequired[Annotated[PositiveInt, Field(default=1, description="Mousemove events for coordinates only.")]]
+
+
+class _MouseClick(_MouseTarget):
+ type: Literal["click"]
+ button: NotRequired[Annotated[MouseButton, Field(default="left")]]
+ click_count: NotRequired[Annotated[PositiveInt, Field(default=1, description="2 for a double-click.")]]
+ delay: NotRequired[
+ Annotated[NonNegativeFiniteFloat, Field(default=0, description="Milliseconds between press and release.")]
+ ]
+
+
+class _MouseWheel(TypedDict):
+ type: Literal["wheel"]
+ delta_x: NotRequired[
+ Annotated[FiniteFloat, Field(default=0, description="Horizontal CSS pixels; positive scrolls right.")]
+ ]
+ delta_y: NotRequired[
+ Annotated[FiniteFloat, Field(default=0, description="Vertical CSS pixels; positive scrolls down.")]
+ ]
+
+
+MouseAction = Annotated[Union[_MouseMove, _MouseClick, _MouseWheel], Field(discriminator="type")]
+
+
class _FormTarget(TypedDict, total=False):
selector: Optional[NonEmptyString]
ref: Optional[NonEmptyString]
@@ -445,94 +482,63 @@ class ScraplingMCPServer:
else:
page_info.mark_ready()
- async def browser_mouse_move(
+ async def browser_mouse(
self,
session_id: str,
- x: Optional[FiniteFloat] = None,
- y: Optional[FiniteFloat] = None,
- steps: PositiveInt = 1,
- selector: Optional[NonEmptyString] = None,
- ref: Optional[NonEmptyString] = None,
- timeout: NonNegativeFiniteFloat = 30000,
+ actions: Annotated[List[MouseAction], Field(min_length=1)],
) -> str:
- """Hover using exactly one selector, snapshot ref, or (x, y) pair; return plain text.
- Selector/ref targets wait and scroll into view; coordinate moves do not.
+ """Move, hover, click, or wheel in order; return plain text. Errors identify the failed action; earlier actions remain.
+ Selector/ref targets wait and scroll into view; coordinates do not. Wheel does not wait for scrolling to finish.
+ Cancelled/timed-out clicks attempt button release. Use browser_snapshot separately to check page changes.
:param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param x: Horizontal CSS pixels from the main frame viewport's top-left.
- :param y: Vertical CSS pixels from the same origin.
- :param steps: Number of mousemove events for coordinate moves; ignored for selector/ref targets.
- :param selector: Playwright selector matching exactly one element.
- :param ref: Element reference from the current snapshot, e.g. "e2".
- :param timeout: Selector/ref timeout in milliseconds; 0 disables it. Ignored for coordinates.
+ :param actions: Ordered actions; move/click need exactly one selector, snapshot ref, or (x, y) pair in viewport CSS pixels.
"""
- if sum(value is not None for value in (selector, ref, x)) != 1 or (x is None) != (y is None):
- raise ValueError("Provide exactly one target: 'selector', 'ref', or both 'x' and 'y'.")
- with self._browser_page(session_id) as (_, page):
- if selector is not None or ref is not None:
- await page.locator(selector if selector is not None else f"aria-ref={ref}").hover(timeout=timeout)
- return "Mouse hovered over element."
- await page.mouse.move(x, y, steps=steps)
- return f"Mouse moved to ({x}, {y})."
-
- async def browser_mouse_wheel(
- self,
- session_id: str,
- delta_x: FiniteFloat = 0,
- delta_y: FiniteFloat = 0,
- ) -> str:
- """Send a wheel event at the current mouse position; return plain text.
-
- :param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param delta_x: Horizontal pixels; positive scrolls right, negative scrolls left.
- :param delta_y: Vertical pixels; positive scrolls down, negative scrolls up.
- """
- with self._browser_page(session_id) as (_, page):
- await page.mouse.wheel(delta_x, delta_y)
- return "Wheel event sent."
-
- async def browser_click(
- self,
- session_id: str,
- selector: Optional[NonEmptyString] = None,
- ref: Optional[NonEmptyString] = None,
- x: Optional[FiniteFloat] = None,
- y: Optional[FiniteFloat] = None,
- button: MouseButton = "left",
- click_count: PositiveInt = 1,
- delay: NonNegativeFiniteFloat = 0,
- timeout: NonNegativeFiniteFloat = 30000,
- ) -> str:
- """Click using exactly one selector, snapshot ref, or (x, y) pair; return plain text.
- Selector/ref clicks wait and scroll into view.
- Coordinate clicks do not scroll or wait for navigation. Cancellation/timeouts release the button if the page stays open; completed actions remain.
-
- :param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param selector: Playwright selector (e.g. CSS or XPath) matching exactly one element.
- :param ref: Element reference from the current snapshot, e.g. "e2".
- :param x: Horizontal CSS pixels from the main frame viewport's top-left.
- :param y: Vertical CSS pixels from the same origin.
- :param button: Mouse button.
- :param click_count: Click count; use 2 for a double-click.
- :param delay: Milliseconds between button press and release.
- :param timeout: Selector/ref timeout in milliseconds; 0 disables it. Ignored for coordinates.
- """
- if sum(value is not None for value in (selector, ref, x)) != 1 or (x is None) != (y is None):
- raise ValueError("Provide exactly one target: 'selector', 'ref', or both 'x' and 'y'.")
+ for index, action in enumerate(actions, 1):
+ if action["type"] != "wheel" and (
+ sum(action.get(key) is not None for key in ("selector", "ref", "x")) != 1
+ or (action.get("x") is None) != (action.get("y") is None)
+ ):
+ raise ValueError(
+ f"Mouse action {index} ({action['type']}) needs exactly one target: 'selector', 'ref', or both 'x' and 'y'."
+ )
with self._browser_page(session_id) as (_, page):
- try:
- if selector is not None or ref is not None:
- await page.locator(selector if selector is not None else f"aria-ref={ref}").click(
- button=button, click_count=click_count, delay=delay, timeout=timeout
+ for index, action in enumerate(actions, 1):
+ try:
+ if action["type"] == "wheel":
+ await page.mouse.wheel(action.get("delta_x", 0), action.get("delta_y", 0))
+ continue
+ selector, ref = action.get("selector"), action.get("ref")
+ locator = (
+ page.locator(selector or f"aria-ref={ref}") if selector is not None or ref is not None else None
)
- else:
- await page.mouse.click(x, y, button=button, click_count=click_count, delay=delay)
- except (CancelledError, PlaywrightTimeoutError, PatchrightTimeoutError):
- with CancelScope(shield=True):
- if not page.is_closed():
- await page.mouse.up(button=button)
- raise
- return "Click sent."
+ if action["type"] == "move":
+ if locator is not None:
+ await locator.hover(timeout=action.get("timeout", 30000))
+ else:
+ await page.mouse.move(action.get("x"), action.get("y"), steps=action.get("steps", 1))
+ else:
+ options = {
+ "button": action.get("button", "left"),
+ "click_count": action.get("click_count", 1),
+ "delay": action.get("delay", 0),
+ }
+ try:
+ if locator is not None:
+ await locator.click(**options, timeout=action.get("timeout", 30000))
+ else:
+ await page.mouse.click(action.get("x"), action.get("y"), **options)
+ except (CancelledError, PlaywrightTimeoutError, PatchrightTimeoutError) as exc:
+ try:
+ with CancelScope(shield=True):
+ if not page.is_closed():
+ await page.mouse.up(button=options["button"])
+ except Exception as cleanup_error:
+ raise exc from cleanup_error
+ raise
+ except Exception as exc:
+ raise RuntimeError(f"Mouse action {index} ({action['type']}) failed: {exc}") from exc
+ return "Mouse actions completed."
async def browser_press_key(
self, session_id: str, keys: Annotated[List[NonEmptyString], Field(min_length=1)]
@@ -1309,7 +1315,7 @@ class ScraplingMCPServer:
9. If you are crawling/browsing a website, be more efficient by using the `css_selector` parameter to only access the parts you are interested in and save money/time. Example: use the `a` selector to extract the urls right away.
10. The user can pass a CDP URL to connect to a remote browser session through the `browser_open` tool, then use it with the session tools.
11. Set `extraction_type="snapshot"` on `browser_fetch` to get an AI ARIA snapshot with element references and bounding boxes in its content field. Use `css_selector` to snapshot one element, or omit it for the whole page. `main_content_only` and `pierce_shadow` do not filter snapshots. Use `browser_snapshot` to read the current page without navigating; it returns plain text with boxes by default. Set `depth` to limit the tree or `boxes=False` to omit boxes.
-12. Use `browser_mouse_move` to move the mouse on the current page. Use `browser_click` with exactly one target: `selector`, `ref` from the current snapshot, or both `x` and `y` viewport CSS coordinates. Selector/ref clicks use Playwright's normal waiting and scrolling; coordinate clicks do not scroll or wait for navigation. Get coordinates from `browser_snapshot` and inspect the page afterward with `browser_snapshot`. Clicks can change website data. Do not repeat a click without checking the page state.
+12. Use `browser_mouse` for ordered move/hover, click, and wheel actions. Move/click targets use exactly one selector, current snapshot ref, or viewport (x, y) pair in CSS pixels. Wheel acts at the current pointer and does not wait for scrolling to finish; coordinate clicks do not wait for navigation. Use `browser_snapshot` to inspect results before repeating failed actions or choosing targets that depend on page changes. Completed actions are not undone or retried.
13. Use `browser_snapshot` to inspect the page after `browser_fill_fields` or `browser_press_key`. Actions may partly complete before an error; check the page before repeating them. To submit, focus the intended control and use `browser_press_key` with ["Enter"].
""",
}
@@ -1403,23 +1409,9 @@ class ScraplingMCPServer:
annotations=_FETCH_TOOL_ANNOTATIONS,
)
server.add_tool(
- self.browser_mouse_move,
- title="Move mouse",
- description=self.browser_mouse_move.__doc__,
- structured_output=False,
- annotations=_INPUT_TOOL_ANNOTATIONS,
- )
- server.add_tool(
- self.browser_mouse_wheel,
- title="Scroll",
- description=self.browser_mouse_wheel.__doc__,
- structured_output=False,
- annotations=_INPUT_TOOL_ANNOTATIONS,
- )
- server.add_tool(
- self.browser_click,
- title="Click",
- description=self.browser_click.__doc__,
+ self.browser_mouse,
+ title="Mouse actions",
+ description=self.browser_mouse.__doc__,
structured_output=False,
annotations=_INPUT_TOOL_ANNOTATIONS,
)
diff --git a/tests/ai/test_ai_mcp.py b/tests/ai/test_ai_mcp.py
index 9a49c47..8fc1495 100644
--- a/tests/ai/test_ai_mcp.py
+++ b/tests/ai/test_ai_mcp.py
@@ -982,7 +982,7 @@ class TestServerToolRegistration:
@pytest.mark.asyncio
async def test_tools_are_listed_with_expected_schemas(self):
- """All 19 tools are advertised, with plain content for screenshots, snapshots, and input actions"""
+ """All 17 tools are advertised, with plain content for screenshots, snapshots, and input actions"""
server = ScraplingMCPServer()._build_server("127.0.0.1", 8000)
async with Client(server) as client:
assert client.instructions
@@ -993,7 +993,9 @@ class TestServerToolRegistration:
"open_session",
"session_fetch",
"screenshot",
- "browser_mouse",
+ "browser_mouse_move",
+ "browser_mouse_wheel",
+ "browser_click",
"browser_mouse_move_xy",
"fetch",
"bulk_fetch",
@@ -1003,12 +1005,10 @@ class TestServerToolRegistration:
result = await client.call_tool(name, {})
assert result.is_error
- assert len(tools) == 19
+ assert len(tools) == 17
assert tools["browser_screenshot"].output_schema is None
assert tools["browser_snapshot"].output_schema is None
- assert tools["browser_mouse_move"].output_schema is None
- assert tools["browser_click"].output_schema is None
- assert tools["browser_mouse_wheel"].output_schema is None
+ assert tools["browser_mouse"].output_schema is None
assert tools["browser_press_key"].output_schema is None
assert tools["browser_fill_fields"].output_schema is None
assert {
@@ -1018,7 +1018,9 @@ class TestServerToolRegistration:
"open_session",
"session_fetch",
"screenshot",
- "browser_mouse",
+ "browser_mouse_move",
+ "browser_mouse_wheel",
+ "browser_click",
"browser_mouse_move_xy",
"fetch",
"bulk_fetch",
@@ -1038,9 +1040,7 @@ class TestServerToolRegistration:
not in (
"browser_screenshot",
"browser_snapshot",
- "browser_mouse_move",
- "browser_click",
- "browser_mouse_wheel",
+ "browser_mouse",
"browser_press_key",
"browser_fill_fields",
)
@@ -1108,7 +1108,7 @@ class TestServerToolRegistration:
assert result.ttl_ms == 3_600_000 and result.cache_scope == "public"
annotations = {tool.name: tool.annotations for tool in result.tools if tool.annotations is not None}
- assert len(annotations) == 19
+ assert len(annotations) == 17
for name in (
"make_request",
"bulk_get",
@@ -1130,9 +1130,7 @@ class TestServerToolRegistration:
assert annotations["list_sessions"].read_only_hint is True
assert annotations["list_sessions"].open_world_hint is False
for name in (
- "browser_mouse_move",
- "browser_click",
- "browser_mouse_wheel",
+ "browser_mouse",
"browser_press_key",
"browser_fill_fields",
):
diff --git a/tests/ai/test_browser_fill_fields.py b/tests/ai/test_browser_fill_fields.py
index c861091..6d561bd 100644
--- a/tests/ai/test_browser_fill_fields.py
+++ b/tests/ai/test_browser_fill_fields.py
@@ -649,7 +649,9 @@ async def test_browser_fill_fields_live_caret_selection_and_submit(session_type:
assert await page.locator("#name").input_value() == "abcz!d"
assert await page.locator("#notes").input_value() == "new notes"
assert await page.locator("#submitted").inner_text() == "0"
- focused = await client.call_tool("browser_click", {"session_id": "browser", "ref": name[1]})
+ focused = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "click", "ref": name[1]}]}
+ )
assert not focused.is_error
await press(["Enter"])
assert await page.locator("#submitted").inner_text() == "1"
diff --git a/tests/ai/test_browser_mouse.py b/tests/ai/test_browser_mouse.py
index d83dbe2..ab9a687 100644
--- a/tests/ai/test_browser_mouse.py
+++ b/tests/ai/test_browser_mouse.py
@@ -3,7 +3,7 @@ from contextlib import suppress
from json import loads
from os import getenv
from re import search
-from unittest.mock import AsyncMock, Mock
+from unittest.mock import AsyncMock, Mock, call
import pytest
from anyio import CancelScope
@@ -49,6 +49,7 @@ def _server(session_type: SessionType = "dynamic") -> tuple[ScraplingMCPServer,
page.mouse.move = AsyncMock()
page.mouse.click = AsyncMock()
page.mouse.up = AsyncMock()
+ page.mouse.wheel = AsyncMock()
page.locator.return_value.click = AsyncMock()
page.locator.return_value.hover = AsyncMock()
session.page_pool.add_page(page).mark_ready()
@@ -58,37 +59,49 @@ def _server(session_type: SessionType = "dynamic") -> tuple[ScraplingMCPServer,
@pytest.mark.asyncio
async def test_browser_mouse_schema_and_annotations() -> None:
- server = ScraplingMCPServer()
- async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ async with Client(ScraplingMCPServer()._build_server("127.0.0.1", 8000)) as client:
tools = {tool.name: tool for tool in (await client.list_tools()).tools}
- removed = await client.call_tool("browser_mouse", {"session_id": "browser", "action": "move", "x": 1, "y": 2})
- assert "browser_mouse" not in tools and removed.is_error
- move, click = tools["browser_mouse_move"], tools["browser_click"]
- assert set(move.input_schema["properties"]) == {"session_id", "x", "y", "steps", "selector", "ref", "timeout"}
- assert move.input_schema["required"] == ["session_id"]
- assert move.input_schema["properties"]["steps"]["exclusiveMinimum"] == 0
- assert move.input_schema["properties"]["steps"]["default"] == 1
- assert move.input_schema["properties"]["timeout"]["minimum"] == 0
- assert move.input_schema["properties"]["timeout"]["default"] == 30000
- properties = click.input_schema["properties"]
- assert set(properties) == {"session_id", "selector", "ref", "x", "y", "button", "click_count", "delay", "timeout"}
- assert click.input_schema["required"] == ["session_id"]
- assert set(properties["button"]["enum"]) == {"left", "right", "middle"}
- assert properties["click_count"]["exclusiveMinimum"] == 0
- assert properties["delay"]["minimum"] == properties["timeout"]["minimum"] == 0
- assert {name: properties[name]["default"] for name in ("button", "click_count", "delay", "timeout")} == {
+ for name in ("browser_mouse_move", "browser_click", "browser_mouse_wheel"):
+ assert name not in tools
+ assert (await client.call_tool(name, {"session_id": "browser"})).is_error
+ tool = tools["browser_mouse"]
+ assert tool.title == "Mouse actions"
+ schema = tool.input_schema
+ assert set(schema["properties"]) == {"session_id", "actions"}
+ assert schema["required"] == ["session_id", "actions"]
+ actions = schema["properties"]["actions"]
+ assert actions["type"] == "array" and actions["minItems"] == 1
+ items = actions["items"]
+ assert items["discriminator"]["propertyName"] == "type"
+ variants = {kind: schema["$defs"][ref.rsplit("/", 1)[1]] for kind, ref in items["discriminator"]["mapping"].items()}
+ assert set(variants) == {"move", "click", "wheel"}
+ assert len(items["oneOf"]) == 3
+ for kind, variant in variants.items():
+ assert variant["required"] == ["type"]
+ assert variant["properties"]["type"]["const"] == kind
+ move = variants["move"]["properties"]
+ assert set(move) == {"type", "x", "y", "steps", "selector", "ref", "timeout"}
+ assert move["steps"]["exclusiveMinimum"] == 0
+ assert move["steps"]["default"] == 1
+ assert move["timeout"]["minimum"] == 0
+ assert move["timeout"]["default"] == 30000
+ click = variants["click"]["properties"]
+ assert set(click) == {"type", "selector", "ref", "x", "y", "button", "click_count", "delay", "timeout"}
+ assert set(click["button"]["enum"]) == {"left", "right", "middle"}
+ assert click["click_count"]["exclusiveMinimum"] == 0
+ assert click["delay"]["minimum"] == click["timeout"]["minimum"] == 0
+ assert {name: click[name]["default"] for name in ("button", "click_count", "delay", "timeout")} == {
"button": "left",
"click_count": 1,
"delay": 0,
"timeout": 30000,
}
- for tool in (move, click):
- assert tool.output_schema is None
- assert tool.annotations is not None
- assert tool.annotations.read_only_hint is False
- assert tool.annotations.destructive_hint is True
- assert tool.annotations.idempotent_hint is False
- assert tool.annotations.open_world_hint is True
+ assert tool.output_schema is None
+ assert tool.annotations is not None
+ assert tool.annotations.read_only_hint is False
+ assert tool.annotations.destructive_hint is True
+ assert tool.annotations.idempotent_hint is False
+ assert tool.annotations.open_world_hint is True
@pytest.mark.asyncio
@@ -96,26 +109,26 @@ async def test_browser_mouse_schema_and_annotations() -> None:
@pytest.mark.parametrize(
"tool, target, options, expected",
[
- ("browser_mouse_move", {"x": -12.5, "y": 23.5}, {}, {"steps": 1}),
- ("browser_mouse_move", {"x": -12.5, "y": 23.5}, {"steps": 5, "timeout": 400}, {"steps": 5}),
- ("browser_mouse_move", {"selector": "button"}, {}, {"timeout": 30000}),
- ("browser_mouse_move", {"ref": "e4"}, {"steps": 5, "timeout": 500}, {"timeout": 500}),
- ("browser_mouse_move", {"selector": "button"}, {"timeout": 0}, {"timeout": 0}),
- ("browser_click", {"x": -12.5, "y": 23.5}, {}, {"button": "left", "click_count": 1, "delay": 0}),
+ ("move", {"x": -12.5, "y": 23.5}, {}, {"steps": 1}),
+ ("move", {"x": -12.5, "y": 23.5}, {"steps": 5, "timeout": 400}, {"steps": 5}),
+ ("move", {"selector": "button"}, {}, {"timeout": 30000}),
+ ("move", {"ref": "e4"}, {"steps": 5, "timeout": 500}, {"timeout": 500}),
+ ("move", {"selector": "button"}, {"timeout": 0}, {"timeout": 0}),
+ ("click", {"x": -12.5, "y": 23.5}, {}, {"button": "left", "click_count": 1, "delay": 0}),
(
- "browser_click",
+ "click",
{"x": -12.5, "y": 23.5},
{"button": "middle", "timeout": 400},
{"button": "middle", "click_count": 1, "delay": 0},
),
(
- "browser_click",
+ "click",
{"selector": "button"},
{},
{"button": "left", "click_count": 1, "delay": 0, "timeout": 30000},
),
(
- "browser_click",
+ "click",
{"ref": "e4"},
{"button": "right", "click_count": 2, "delay": 30, "timeout": 500},
{"button": "right", "click_count": 2, "delay": 30, "timeout": 500},
@@ -127,14 +140,13 @@ async def test_browser_mouse_forwards_native_actions(
) -> None:
server, session, page = _server(session_type)
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool(tool, {"session_id": "browser", **target, **options})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": tool, **target, **options}]}
+ )
assert not result.is_error
assert result.structured_content is None
- message = "Click sent."
- if tool == "browser_mouse_move":
- message = "Mouse moved to (-12.5, 23.5)." if "x" in target else "Mouse hovered over element."
- assert result.content == [TextContent(type="text", text=message)]
- if tool == "browser_mouse_move" and "x" in target:
+ assert result.content == [TextContent(type="text", text="Mouse actions completed.")]
+ if tool == "move" and "x" in target:
page.mouse.move.assert_awaited_once_with(-12.5, 23.5, **expected)
page.mouse.click.assert_not_awaited()
page.locator.assert_not_called()
@@ -144,7 +156,7 @@ async def test_browser_mouse_forwards_native_actions(
page.locator.assert_not_called()
else:
page.locator.assert_called_once_with(target["selector"] if "selector" in target else "aria-ref=e4")
- action = "hover" if tool == "browser_mouse_move" else "click"
+ action = "hover" if tool == "move" else "click"
getattr(page.locator.return_value, action).assert_awaited_once_with(**expected)
getattr(page.locator.return_value, "click" if action == "hover" else "hover").assert_not_awaited()
page.mouse.move.assert_not_awaited()
@@ -168,29 +180,35 @@ async def test_browser_mouse_forwards_native_actions(
@pytest.mark.parametrize(
"tool, values",
[
- ("browser_mouse_move", {"x": "invalid"}),
- ("browser_mouse_move", {"y": None}),
- ("browser_mouse_move", {"steps": 1.5}),
- ("browser_mouse_move", {"steps": 0}),
- ("browser_mouse_move", {"steps": -1}),
- ("browser_mouse_move", {"selector": ""}),
- ("browser_mouse_move", {"ref": ""}),
- ("browser_mouse_move", {"timeout": -1}),
- ("browser_click", {"button": "back"}),
- ("browser_click", {"click_count": 1.5}),
- ("browser_click", {"click_count": 0}),
- ("browser_click", {"click_count": -1}),
- ("browser_click", {"delay": -1}),
- ("browser_click", {"delay": "invalid"}),
- ("browser_click", {"timeout": -1}),
- ("browser_click", {"selector": ""}),
- ("browser_click", {"ref": ""}),
+ ("move", {"x": "invalid"}),
+ ("move", {"y": None}),
+ ("move", {"steps": 1.5}),
+ ("move", {"steps": 0}),
+ ("move", {"steps": -1}),
+ ("move", {"selector": ""}),
+ ("move", {"ref": ""}),
+ ("move", {"timeout": -1}),
+ ("click", {"button": "back"}),
+ ("click", {"click_count": 1.5}),
+ ("click", {"click_count": 0}),
+ ("click", {"click_count": -1}),
+ ("click", {"delay": -1}),
+ ("click", {"delay": "invalid"}),
+ ("click", {"timeout": -1}),
+ ("click", {"selector": ""}),
+ ("click", {"ref": ""}),
],
)
async def test_browser_mouse_invalid_input_does_not_reserve_or_use_page(tool: str, values: dict[str, Any]) -> None:
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool(tool, {"session_id": "browser", "x": 10, "y": 20, **values})
+ result = await client.call_tool(
+ "browser_mouse",
+ {
+ "session_id": "browser",
+ "actions": [{"type": "move", "x": 1, "y": 2}, {"type": tool, "x": 10, "y": 20, **values}],
+ },
+ )
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
page.mouse.move.assert_not_awaited()
@@ -199,17 +217,17 @@ async def test_browser_mouse_invalid_input_does_not_reserve_or_use_page(tool: st
assert session.page_pool.pages[0].state == "ready"
- "tool, fields", [("browser_mouse_move", ("x", "y", "timeout")), ("browser_click", ("x", "y", "delay", "timeout"))]
-)
[email protected]("tool, fields", [("move", ("x", "y", "timeout")), ("click", ("x", "y", "delay", "timeout"))])
@pytest.mark.parametrize("value", [float("nan"), float("inf"), float("-inf")])
def test_browser_mouse_schema_rejects_nonfinite_values(tool: str, fields: tuple[str, ...], value: float) -> None:
server, session, page = _server()
- registered = server._build_server("127.0.0.1", 8000)._tool_manager.get_tool(tool)
+ registered = server._build_server("127.0.0.1", 8000)._tool_manager.get_tool("browser_mouse")
assert registered is not None
for field in fields:
with pytest.raises(ValidationError):
- registered.fn_metadata.arg_model.model_validate({"session_id": "browser", "x": 10, "y": 20, field: value})
+ registered.fn_metadata.arg_model.model_validate(
+ {"session_id": "browser", "actions": [{"type": tool, "x": 10, "y": 20, field: value}]}
+ )
page.mouse.move.assert_not_awaited()
page.mouse.click.assert_not_awaited()
page.is_closed.assert_not_called()
@@ -217,7 +235,7 @@ def test_browser_mouse_schema_rejects_nonfinite_values(tool: str, fields: tuple[
@pytest.mark.asyncio
[email protected]("tool", ["browser_mouse_move", "browser_click"])
[email protected]("tool", ["move", "click"])
@pytest.mark.parametrize(
"target",
[
@@ -234,7 +252,10 @@ def test_browser_mouse_schema_rejects_nonfinite_values(tool: str, fields: tuple[
async def test_browser_mouse_requires_exactly_one_complete_target(tool: str, target: dict[str, Any]) -> None:
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool(tool, {"session_id": "browser", **target})
+ result = await client.call_tool(
+ "browser_mouse",
+ {"session_id": "browser", "actions": [{"type": "move", "x": 1, "y": 2}, {"type": tool, **target}]},
+ )
assert result.is_error
page.is_closed.assert_not_called()
page.mouse.move.assert_not_awaited()
@@ -244,7 +265,7 @@ async def test_browser_mouse_requires_exactly_one_complete_target(tool: str, tar
@pytest.mark.asyncio
[email protected]("tool", ["browser_mouse_move", "browser_click"])
[email protected]("tool", ["move", "click"])
@pytest.mark.parametrize(
"state, message",
[
@@ -269,7 +290,9 @@ async def test_browser_mouse_session_errors_reach_mcp(tool: str, state: str, mes
elif state == "closed":
page.is_closed.return_value = True
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool(tool, {"session_id": "browser", "x": 10, "y": 20})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": tool, "x": 10, "y": 20}]}
+ )
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
assert message in result.content[0].text
@@ -282,7 +305,7 @@ async def test_browser_mouse_session_errors_reach_mcp(tool: str, state: str, mes
@pytest.mark.asyncio
[email protected]("tool", ["browser_mouse_move", "browser_click"])
[email protected]("tool", ["move", "click"])
@pytest.mark.parametrize("closed", [False, True])
@pytest.mark.parametrize("target", [{"x": 10, "y": 20}, {"selector": "button"}, {"ref": "e1"}])
async def test_browser_mouse_failure_is_not_retried_and_releases_page(
@@ -294,13 +317,15 @@ async def test_browser_mouse_failure_is_not_retried_and_releases_page(
page.is_closed.return_value = closed
raise RuntimeError("mouse failed")
- if tool == "browser_mouse_move":
+ if tool == "move":
action = page.mouse.move if "x" in target else page.locator.return_value.hover
else:
action = page.mouse.click if "x" in target else page.locator.return_value.click
action.side_effect = fail
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool(tool, {"session_id": "browser", **target})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": tool, **target}]}
+ )
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
assert "mouse failed" in result.content[0].text
@@ -310,8 +335,9 @@ async def test_browser_mouse_failure_is_not_retried_and_releases_page(
else:
assert session.page_pool.pages[0].state == "ready"
action.side_effect = None
- await getattr(server, tool)("browser", **target)
+ await server.browser_mouse("browser", [{"type": tool, **target}])
page.close.assert_not_called()
+ page.mouse.wheel.assert_not_awaited()
page.mouse.up.assert_not_awaited()
@@ -329,16 +355,14 @@ async def test_browser_mouse_reserves_page_until_cancelled(target: dict[str, Any
action = page.mouse.move if "x" in target else page.locator.return_value.hover
action.side_effect = move
task = asyncio.create_task(
- server.browser_mouse_move("browser", 10, 20, 3)
- if "x" in target
- else server.browser_mouse_move("browser", **target)
+ server.browser_mouse("browser", [{"type": "move", **target, "steps": 3}, {"type": "wheel", "delta_y": 120}])
)
try:
await asyncio.wait_for(entered.wait(), 5)
assert session.page_pool.pages[0].state == "busy"
assert session.page_pool.get_ready_page() is None
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_click("browser", x=10, y=20)
+ await server.browser_mouse("browser", [{"type": "click", "x": 10, "y": 20}])
with pytest.raises(RuntimeError, match="busy"):
await server.browser_snapshot("browser")
finally:
@@ -347,13 +371,14 @@ async def test_browser_mouse_reserves_page_until_cancelled(target: dict[str, Any
await task
assert session.page_pool.pages[0].state == "ready"
page.close.assert_not_called()
+ page.mouse.wheel.assert_not_awaited()
@pytest.mark.asyncio
@pytest.mark.parametrize(
"session_type, error_type", [("dynamic", PlaywrightTimeoutError), ("stealthy", PatchrightTimeoutError)]
)
-async def test_browser_click_timeout_holds_page_until_button_is_released(
+async def test_browser_mouse_click_timeout_holds_page_until_button_is_released(
session_type: SessionType, error_type: type[Exception]
) -> None:
server, session, page = _server(session_type)
@@ -366,24 +391,28 @@ async def test_browser_click_timeout_holds_page_until_button_is_released(
page.locator.return_value.click.side_effect = error_type("click timed out")
page.mouse.up.side_effect = unpress
- task = asyncio.create_task(server.browser_click("browser", selector="button", button="right"))
+ task = asyncio.create_task(
+ server.browser_mouse("browser", [{"type": "click", "selector": "button", "button": "right"}])
+ )
try:
await asyncio.wait_for(releasing.wait(), 5)
assert session.page_pool.pages[0].state == "busy"
assert session.page_pool.get_ready_page() is None
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_mouse_move("browser", 30, 40)
+ await server.browser_mouse("browser", [{"type": "move", "x": 30, "y": 40}])
release.set()
- with pytest.raises(error_type, match="click timed out"):
+ with pytest.raises(RuntimeError, match=r"Mouse action 1 \(click\) failed: click timed out") as error:
await task
+ assert isinstance(error.value.__cause__, error_type)
finally:
release.set()
- with suppress(error_type):
+ with suppress(RuntimeError):
await task
page.mouse.up.assert_awaited_once_with(button="right")
page.locator.return_value.click.assert_awaited_once()
assert session.page_pool.pages[0].state == "ready"
page.close.assert_not_called()
+ page.mouse.wheel.assert_not_awaited()
@pytest.mark.asyncio
@@ -408,7 +437,10 @@ async def test_browser_mouse_cancelled_click_holds_page_until_button_is_released
async def click() -> None:
with scope:
- await server.browser_click("browser", **target, button="right", delay=60000)
+ await server.browser_mouse(
+ "browser",
+ [{"type": "click", **target, "button": "right", "delay": 60000}, {"type": "wheel", "delta_y": 120}],
+ )
action = page.mouse.click if "x" in target else page.locator.return_value.click
action.side_effect = press
@@ -421,7 +453,7 @@ async def test_browser_mouse_cancelled_click_holds_page_until_button_is_released
assert session.page_pool.pages[0].state == "busy"
assert session.page_pool.get_ready_page() is None
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_mouse_move("browser", 30, 40)
+ await server.browser_mouse("browser", [{"type": "move", "x": 30, "y": 40}])
release.set()
if cancel_mode == "scope":
await asyncio.wait_for(task, 5)
@@ -439,6 +471,151 @@ async def test_browser_mouse_cancelled_click_holds_page_until_button_is_released
action.assert_awaited_once()
assert session.page_pool.pages[0].state == "ready"
page.close.assert_not_called()
+ page.mouse.wheel.assert_not_awaited()
+
+
+ "session_type, timeout_type, native_error_type",
+ [("dynamic", PlaywrightTimeoutError, PlaywrightError), ("stealthy", PatchrightTimeoutError, PatchrightError)],
+)
[email protected]("cancelled", [False, True])
[email protected]("native_cleanup_error", [False, True])
[email protected]("closed", [False, True])
+async def test_browser_mouse_cleanup_failure_preserves_click_error(
+ session_type: SessionType,
+ timeout_type: type[Exception],
+ native_error_type: type[Exception],
+ cancelled: bool,
+ native_cleanup_error: bool,
+ closed: bool,
+) -> None:
+ server, session, page = _server(session_type)
+ entered = asyncio.Event()
+ release = asyncio.Event()
+ timeout = timeout_type("click timed out")
+ cleanup_error = (native_error_type if native_cleanup_error else RuntimeError)("button release failed")
+
+ async def press(*args: Any, **kwargs: Any) -> None:
+ entered.set()
+ await release.wait()
+ raise timeout
+
+ async def unpress(*args: Any, **kwargs: Any) -> None:
+ assert session.page_pool.pages[0].state == "busy"
+ page.is_closed.return_value = closed
+ raise cleanup_error
+
+ page.locator.return_value.click.side_effect = press
+ page.mouse.up.side_effect = unpress
+ task = asyncio.create_task(
+ server.browser_mouse(
+ "browser",
+ [{"type": "click", "selector": "#target", "button": "right"}, {"type": "wheel", "delta_y": 120}],
+ )
+ )
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ task.cancel() if cancelled else release.set()
+ with pytest.raises(asyncio.CancelledError if cancelled else RuntimeError) as error:
+ await asyncio.wait_for(task, 5)
+ original = error.value if cancelled else error.value.__cause__
+ if not cancelled:
+ assert str(error.value) == "Mouse action 1 (click) failed: click timed out"
+ assert original is timeout
+ assert original is not None and original.__cause__ is cleanup_error
+ finally:
+ if not task.done():
+ task.cancel()
+ with suppress(Exception, asyncio.CancelledError):
+ await task
+ page.locator.return_value.click.assert_awaited_once()
+ page.mouse.up.assert_awaited_once_with(button="right")
+ page.mouse.wheel.assert_not_awaited()
+ if closed:
+ assert session.page_pool.pages_count == 0
+ else:
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("actions", [[], [{}], [{"type": "drag", "x": 10, "y": 20}]])
+async def test_browser_mouse_rejects_empty_or_unknown_actions(actions: list[dict[str, Any]]) -> None:
+ server, session, page = _server()
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ result = await client.call_tool("browser_mouse", {"session_id": "browser", "actions": actions})
+ assert result.is_error
+ page.is_closed.assert_not_called()
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("session_type", ["dynamic", "stealthy"])
+async def test_browser_mouse_mixed_chain_keeps_one_page_reserved(session_type: SessionType) -> None:
+ server, session, page = _server(session_type)
+ reservations = []
+
+ async def record(*args: Any, **kwargs: Any) -> None:
+ reservations.append(session.page_pool.pages[0].state)
+
+ for action in (
+ page.mouse.move,
+ page.mouse.wheel,
+ page.mouse.click,
+ page.locator.return_value.hover,
+ page.locator.return_value.click,
+ ):
+ action.side_effect = record
+ actions = [
+ {"type": "move", "x": 10, "y": 20, "steps": 4},
+ {"type": "move", "selector": "#panel", "timeout": 500},
+ {"type": "wheel", "delta_y": 120},
+ {"type": "click", "ref": "e4", "button": "right"},
+ {"type": "click", "x": 30, "y": 40, "click_count": 2},
+ ]
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ result = await client.call_tool("browser_mouse", {"session_id": "browser", "actions": actions})
+ assert not result.is_error
+ assert result.content == [TextContent(type="text", text="Mouse actions completed.")]
+ assert page.mock_calls == [
+ call.is_closed(),
+ call.mouse.move(10, 20, steps=4),
+ call.locator("#panel"),
+ call.locator().hover(timeout=500),
+ call.mouse.wheel(0, 120),
+ call.locator("aria-ref=e4"),
+ call.locator().click(button="right", click_count=1, delay=0, timeout=30000),
+ call.mouse.click(30, 40, button="left", click_count=2, delay=0),
+ call.is_closed(),
+ ]
+ assert reservations == ["busy"] * len(actions)
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("kind", ["move", "click", "wheel"])
+async def test_browser_mouse_chain_reports_failed_index_and_keeps_completed_actions(kind: str) -> None:
+ server, session, page = _server()
+ native_error = RuntimeError("native failure")
+ failing = {
+ "move": page.locator.return_value.hover,
+ "click": page.locator.return_value.click,
+ "wheel": page.mouse.wheel,
+ }[kind]
+ failing.side_effect = native_error
+ actions = [
+ {"type": "move", "x": 10, "y": 20},
+ {"type": kind, **({"selector": "#target"} if kind != "wheel" else {"delta_y": 120})},
+ {"type": "click", "x": 30, "y": 40},
+ ]
+ with pytest.raises(RuntimeError, match=rf"Mouse action 2 \({kind}\) failed: native failure") as error:
+ await server.browser_mouse("browser", actions)
+ assert error.value.__cause__ is native_error
+ page.mouse.move.assert_awaited_once_with(10, 20, steps=1)
+ failing.assert_awaited_once()
+ page.mouse.click.assert_not_awaited()
+ page.mouse.up.assert_not_awaited()
+ assert session.page_pool.pages[0].state == "ready"
@pytest.mark.asyncio
@@ -470,7 +647,8 @@ async def test_browser_mouse_live_native_events_and_navigation(session_type: Ses
page = page_info.page
initial_dom = await page.content()
moved = await client.call_tool(
- "browser_mouse_move", {"session_id": "browser", "x": 140, "y": 110, "steps": 4}
+ "browser_mouse",
+ {"session_id": "browser", "actions": [{"type": "move", "x": 140, "y": 110, "steps": 4}]},
)
assert not moved.is_error
assert (
@@ -488,7 +666,8 @@ async def test_browser_mouse_live_native_events_and_navigation(session_type: Ses
):
await page.locator("#events").evaluate("element => element.value = '[]'")
result = await client.call_tool(
- "browser_click", {"session_id": "browser", "x": 140, "y": 110, **options}
+ "browser_mouse",
+ {"session_id": "browser", "actions": [{"type": "click", "x": 140, "y": 110, **options}]},
)
assert not result.is_error
events = loads(await page.locator("#events").input_value())
@@ -499,7 +678,9 @@ async def test_browser_mouse_live_native_events_and_navigation(session_type: Ses
assert session.page_pool.pages == [page_info] and page_info.state == "ready"
assert await page.content() == initial_dom
assert requests == ["https://mouse.test/"]
- clicked = await client.call_tool("browser_click", {"session_id": "browser", "x": 140, "y": 200})
+ clicked = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "click", "x": 140, "y": 200}]}
+ )
assert not clicked.is_error
await page.wait_for_url("https://mouse.test/next", timeout=5000)
snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
@@ -529,7 +710,7 @@ async def test_browser_mouse_live_cancelled_click_releases_native_button(
async def click() -> None:
with scope:
- await server.browser_click("browser", **target, delay=60000, timeout=0)
+ await server.browser_mouse("browser", [{"type": "click", **target, "delay": 60000, "timeout": 0}])
async with Client(server._build_server("127.0.0.1", 8000)) as client:
opened = await client.call_tool("browser_open", {"session_type": session_type, "session_id": "browser"})
@@ -562,7 +743,9 @@ async def test_browser_mouse_live_cancelled_click_releases_native_button(
with pytest.raises(asyncio.CancelledError):
await asyncio.wait_for(task, 5)
assert page_info.state == "ready"
- moved = await client.call_tool("browser_mouse_move", {"session_id": "browser", "x": 150, "y": 120})
+ moved = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "move", "x": 150, "y": 120}]}
+ )
assert not moved.is_error
events = loads(await page.locator("#events").input_value())
assert all(event["trusted"] for event in events)
@@ -582,7 +765,7 @@ async def test_browser_mouse_live_cancelled_click_releases_native_button(
@pytest.mark.asyncio
@pytest.mark.parametrize("session_type", ["dynamic", "stealthy"])
[email protected]("tool", ["browser_mouse_move", "browser_click"])
[email protected]("tool", ["move", "click"])
async def test_browser_mouse_live_selectors_refs_and_scroll(session_type: SessionType, tool: str) -> None:
server = ScraplingMCPServer(executable_path=getenv("SCRAPLING_EXECUTABLE_PATH"))
@@ -613,11 +796,13 @@ async def test_browser_mouse_live_selectors_refs_and_scroll(session_type: Sessio
):
await page.mouse.move(0, 0)
await page.locator("#events").evaluate("element => element.value = '[]'")
- result = await client.call_tool(tool, {"session_id": "browser", **target})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": tool, **target}]}
+ )
assert not result.is_error
events = loads(await page.locator("#events").input_value())
expected_id = "below" if target.get("selector") == "#below" else "target"
- if tool == "browser_mouse_move":
+ if tool == "move":
assert events and all(event["type"] == "mousemove" and event["trusted"] for event in events)
assert events[-1]["target"] == expected_id
assert await page.locator(f"#{expected_id}").evaluate("element => element.matches(':hover')")
@@ -630,22 +815,25 @@ async def test_browser_mouse_live_selectors_refs_and_scroll(session_type: Sessio
await page.locator("#target").evaluate("element => element.remove()")
for target in ({"selector": "button, a"}, {"selector": "#missing"}, {"ref": ref}):
await page.locator("#events").evaluate("element => element.value = '[]'")
- with pytest.raises((PlaywrightError, PatchrightError)) as error:
- await getattr(server, tool)(
- "browser", selector=target.get("selector"), ref=target.get("ref"), timeout=100
+ with pytest.raises(RuntimeError, match=rf"Mouse action 1 \({tool}\) failed:") as error:
+ await server.browser_mouse(
+ "browser",
+ [{"type": tool, "selector": target.get("selector"), "ref": target.get("ref"), "timeout": 100}],
)
events = loads(await page.locator("#events").input_value())
if target.get("selector") != "button, a":
assert isinstance(
- error.value, PlaywrightTimeoutError if session_type == "dynamic" else PatchrightTimeoutError
+ error.value.__cause__,
+ PlaywrightTimeoutError if session_type == "dynamic" else PatchrightTimeoutError,
)
assert not any(event["type"] in ("mousedown", "click") for event in events)
released = [event for event in events if event["type"] == "mouseup"]
- if tool == "browser_click":
+ if tool == "click":
assert len(released) == 1 and released[0]["buttons"] == 0
else:
assert not released
else:
+ assert isinstance(error.value.__cause__, (PlaywrightError, PatchrightError))
assert "strict mode violation" in str(error.value)
assert not any(event["type"] in ("mousedown", "mouseup", "click") for event in events)
assert session.page_pool.pages == [page_info] and page_info.state == "ready"
@@ -656,7 +844,7 @@ async def test_browser_mouse_live_selectors_refs_and_scroll(session_type: Sessio
@pytest.mark.asyncio
@pytest.mark.parametrize("session_type", ["dynamic", "stealthy"])
-async def test_browser_click_live_timeout_releases_native_button(session_type: SessionType) -> None:
+async def test_browser_mouse_click_live_timeout_releases_native_button(session_type: SessionType) -> None:
server = ScraplingMCPServer(executable_path=getenv("SCRAPLING_EXECUTABLE_PATH"))
async def serve(route: Any) -> None:
@@ -675,12 +863,18 @@ async def test_browser_click_live_timeout_releases_native_button(session_type: S
page_info = session.page_pool.pages[0]
page = page_info.page
failed = await client.call_tool(
- "browser_click", {"session_id": "browser", "selector": "#target", "delay": 1000, "timeout": 300}
+ "browser_mouse",
+ {
+ "session_id": "browser",
+ "actions": [{"type": "click", "selector": "#target", "delay": 1000, "timeout": 300}],
+ },
)
assert failed.is_error
events = loads(await page.locator("#events").input_value())
assert next(event for event in events if event["type"] == "mousedown")["buttons"] == 1
- moved = await client.call_tool("browser_mouse_move", {"session_id": "browser", "x": 150, "y": 120})
+ moved = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "move", "x": 150, "y": 120}]}
+ )
assert not moved.is_error
events = loads(await page.locator("#events").input_value())
assert (events[-1]["type"], events[-1]["buttons"]) == ("mousemove", 0)
diff --git a/tests/ai/test_browser_wheel.py b/tests/ai/test_browser_wheel.py
index 1ca1953..dfe0c38 100644
--- a/tests/ai/test_browser_wheel.py
+++ b/tests/ai/test_browser_wheel.py
@@ -48,12 +48,15 @@ def _server(session_type: SessionType = "dynamic") -> tuple[ScraplingMCPServer,
@pytest.mark.asyncio
async def test_browser_wheel_schema() -> None:
async with Client(ScraplingMCPServer()._build_server("127.0.0.1", 8000)) as client:
- tool = next(tool for tool in (await client.list_tools()).tools if tool.name == "browser_mouse_wheel")
- assert set(tool.input_schema["properties"]) == {"session_id", "delta_x", "delta_y"}
- assert tool.input_schema["required"] == ["session_id"]
+ tool = next(tool for tool in (await client.list_tools()).tools if tool.name == "browser_mouse")
+ schema = tool.input_schema
+ ref = schema["properties"]["actions"]["items"]["discriminator"]["mapping"]["wheel"]
+ wheel = schema["$defs"][ref.rsplit("/", 1)[1]]
+ assert set(wheel["properties"]) == {"type", "delta_x", "delta_y"}
+ assert wheel["required"] == ["type"]
for field in ("delta_x", "delta_y"):
- assert tool.input_schema["properties"][field]["type"] == "number"
- assert tool.input_schema["properties"][field]["default"] == 0
+ assert wheel["properties"][field]["type"] == "number"
+ assert wheel["properties"][field]["default"] == 0
@pytest.mark.asyncio
@@ -63,10 +66,12 @@ async def test_browser_wheel_schema() -> None:
async def test_browser_wheel_forwards_deltas_without_moving_or_capturing(values: dict[str, float]) -> None:
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_mouse_wheel", {"session_id": "browser", **values})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "wheel", **values}]}
+ )
assert not result.is_error
assert result.structured_content is None
- assert result.content == [TextContent(type="text", text="Wheel event sent.")]
+ assert result.content == [TextContent(type="text", text="Mouse actions completed.")]
page.mouse.wheel.assert_awaited_once_with(values.get("delta_x", 0), values.get("delta_y", 0))
page.mouse.move.assert_not_called()
page.locator.assert_not_called()
@@ -81,7 +86,9 @@ async def test_browser_wheel_forwards_deltas_without_moving_or_capturing(values:
async def test_browser_wheel_invalid_input_does_not_reserve_page(field: str, value: Any) -> None:
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_mouse_wheel", {"session_id": "browser", field: value})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "wheel", field: value}]}
+ )
assert result.is_error
page.is_closed.assert_not_called()
page.mouse.wheel.assert_not_awaited()
@@ -90,11 +97,13 @@ async def test_browser_wheel_invalid_input_does_not_reserve_page(field: str, val
@pytest.mark.parametrize("value", [float("nan"), float("inf"), float("-inf")])
def test_browser_wheel_schema_rejects_nonfinite_deltas(value: float) -> None:
- tool = ScraplingMCPServer()._build_server("127.0.0.1", 8000)._tool_manager.get_tool("browser_mouse_wheel")
+ tool = ScraplingMCPServer()._build_server("127.0.0.1", 8000)._tool_manager.get_tool("browser_mouse")
assert tool is not None
for field in ("delta_x", "delta_y"):
with pytest.raises(ValidationError):
- tool.fn_metadata.arg_model.model_validate({"session_id": "browser", field: value})
+ tool.fn_metadata.arg_model.model_validate(
+ {"session_id": "browser", "actions": [{"type": "wheel", field: value}]}
+ )
@pytest.mark.asyncio
@@ -122,7 +131,9 @@ async def test_browser_wheel_session_errors_reach_mcp(state: str, message: str)
elif state == "closed":
page.is_closed.return_value = True
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_mouse_wheel", {"session_id": "browser", "delta_y": 120})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "wheel", "delta_y": 120}]}
+ )
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
assert message in result.content[0].text
@@ -134,14 +145,16 @@ async def test_browser_wheel_error_is_not_retried_and_releases_page() -> None:
server, session, page = _server()
page.mouse.wheel.side_effect = RuntimeError("wheel failed")
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_mouse_wheel", {"session_id": "browser", "delta_y": 120})
+ result = await client.call_tool(
+ "browser_mouse", {"session_id": "browser", "actions": [{"type": "wheel", "delta_y": 120}]}
+ )
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
- assert "wheel failed" in result.content[0].text
+ assert "Mouse action 1 (wheel) failed: wheel failed" in result.content[0].text
page.mouse.wheel.assert_awaited_once()
assert session.page_pool.pages[0].state == "ready"
page.mouse.wheel.side_effect = None
- assert await server.browser_mouse_wheel("browser", delta_y=-120) == "Wheel event sent."
+ assert await server.browser_mouse("browser", [{"type": "wheel", "delta_y": -120}]) == "Mouse actions completed."
@pytest.mark.asyncio
@@ -157,7 +170,7 @@ async def test_browser_wheel_reserves_page_until_cancelled(cancel_mode: str) ->
async def wheel() -> None:
with scope:
- await server.browser_mouse_wheel("browser", delta_y=120)
+ await server.browser_mouse("browser", [{"type": "wheel", "delta_y": 120}])
page.mouse.wheel.side_effect = pending
task = asyncio.create_task(wheel())
@@ -165,7 +178,7 @@ async def test_browser_wheel_reserves_page_until_cancelled(cancel_mode: str) ->
await asyncio.wait_for(entered.wait(), 5)
assert session.page_pool.pages[0].state == "busy"
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_mouse_wheel("browser", delta_y=120)
+ await server.browser_mouse("browser", [{"type": "wheel", "delta_y": 120}])
finally:
scope.cancel() if cancel_mode == "scope" else task.cancel()
if cancel_mode == "scope":
@@ -208,11 +221,14 @@ async def test_browser_wheel_live_scrolls_under_current_pointer(session_type: Se
expected = {"page": [0, 0], "panel": [0, 0]}
events_count = 0
for target, x, y in (("page", 400, 300), ("panel", 100, 100)):
- moved = await client.call_tool("browser_mouse_move", {"session_id": "browser", "x": x, "y": y})
- assert not moved.is_error
for dx, dy in ((0, 120), (80, 0), (0, -60), (-40, 0)):
result = await client.call_tool(
- "browser_mouse_wheel", {"session_id": "browser", "delta_x": dx, "delta_y": dy}
+ "browser_mouse",
+ {
+ "session_id": "browser",
+ "actions": ([{"type": "move", "x": x, "y": y}] if (dx, dy) == (0, 120) else [])
+ + [{"type": "wheel", "delta_x": dx, "delta_y": dy}],
+ },
)
assert not result.is_error
expected[target][0] += dx