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

feat(mcp)!: Combine all four browser action tools into one chain-able tool

Karim shoair9e36038ca904
diff --git a/agent-skill/Scrapling-Skill.zip b/agent-skill/Scrapling-Skill.zip
index 0af83ee..c4b3a3a 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 9703fb7..1a5205d 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 eighteen 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, page waits, 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 fifteen 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, page waits, 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`, `browser_fill_fields`, `browser_press_key`, and `browser_wait` 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` and `browser_actions` return plain text.
## Shadow DOM
@@ -163,115 +163,60 @@ 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` -- Chain mouse moves, hovers, clicks, and scrolling
+### `browser_actions` -- Chain mouse, field, keyboard, and wait actions
-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.
+Runs actions in order on the existing page in a dynamic or stealthy browser session. Call `browser_fetch` first. The flat `actions` list can mix any of the eleven action types below; use `browser_snapshot` when you need to inspect the page before choosing later actions.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `session_id` | str | required | ID of an open browser session |
-| `actions` | list[object] | required | Nonempty ordered list of `move`, `click`, or `wheel` actions |
+| `actions` | list[object] | required | Nonempty ordered list; each item has a `type` and that type's fields |
+| `slowly` | bool | false | Fresh random delays of 50-150 ms per typed character and 100-300 ms between all actions, including waits |
| 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 |
+| `textbox` | Target, `value`, `clear=true`, `timeout=30000` | By default, replace text in an input, textarea, or contenteditable element with a string; an empty string clears it; `clear=false` types at the current caret or selection without clearing |
+| `checkbox` | Target, `value`, `timeout=30000` | Boolean `true` checks the box; `false` unchecks it |
+| `radio` | Target, `value`, `timeout=30000` | Select the radio option; `value` is required and only `true` is supported |
+| `combobox` | Target, `value`, `timeout=30000` | Select native `<select>` options by label; use a string, a list of strings for multiple selections, or `[]` to clear |
+| `press_key` | `key` | Press a nonempty native key name, character, or shortcut at the current focus |
+| `wait_time` | `milliseconds` | Fixed pause in finite nonnegative milliseconds |
+| `wait_element` | `selector`, `state="visible"`, `timeout=30000` | Wait for a nonempty Playwright selector to reach `"visible"`, `"hidden"`, `"attached"`, or `"detached"` |
+| `wait_load` | `state`, `timeout=30000` | Wait for `"domcontentloaded"`, `"load"`, or `"networkidle"` |
-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`.
+**Targets and timing.** 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 from the main frame's top-left, not full-page screenshot coordinates. Field actions need exactly one nonempty `selector` or `ref` and can target fields anywhere on the page without a `<form>` parent. Element waits use a selector only. Mouse and field selectors must match exactly one element. Use current snapshot references; do not build a chain with references that need a future snapshot.
-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.
+Each action with a `timeout` accepts finite nonnegative milliseconds, default 30000; 0 disables the limit. Mouse coordinate actions ignore it. For text input, the limit applies separately to each native operation, including clearing and each character press in slow mode. Keyboard, wheel, and fixed-pause actions have no timeout option. Pauses between actions are outside action timeouts.
-For example, hover over a panel and scroll it in one call:
+**Mouse actions.** Element targets use native locator hover or click, which waits for readiness and scrolls into view. Coordinate actions use the native mouse without automatic waiting or scrolling. 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.
-```json
-{
- "session_id": "browser",
- "actions": [
- {"type": "move", "selector": "#results"},
- {"type": "wheel", "delta_y": 500}
- ]
-}
-```
-
-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 `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
-
-Fills fields anywhere on the existing page in a dynamic or stealthy browser session. Fields do not need a `<form>` parent. Call `browser_fetch` first. Each field needs exactly one nonempty `selector` or snapshot `ref`, plus its `type` and `value`.
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `session_id` | str | required | ID of an open browser session |
-| `fields` | list[object] | required | Nonempty ordered list of field targets, types, and values |
-| `timeout` | number | 30000 | Finite nonnegative timeout in milliseconds per operation; 0 disables the limit |
-| `slowly` | bool | false | Add fresh random delays: 50-150 ms per character, 100-300 ms between fields |
-
-| Field `type` | `value` | Behavior |
-|--------------|---------|----------|
-| `textbox` | str | By default, replace text in an input, textarea, or contenteditable element; an empty string clears it |
-| `checkbox` | bool | `true` checks the box; `false` unchecks it |
-| `radio` | `true` | Select the radio option; `false` is not supported |
-| `combobox` | str or list[str] | Select native `<select>` options by label; use a list for multiple selections or `[]` to clear |
-
-Textbox fields also accept `clear` (bool, default `true`). With `clear=false`, native `press_sequentially` types at the current caret or selection without clearing first, even when `slowly=false`. An empty value preserves existing content when `clear=false`; otherwise it clears the field.
-
-Selectors must match exactly one element. Use current snapshot references, such as `"e2"`. MCP validates all field types and values before execution, and target combinations are checked before reserving the page. One page stays reserved for the whole batch. Native locator `fill`, `press_sequentially`, `set_checked`, and `select_option(label=...)` run in list order. Combobox fields support native `<select>` elements, not custom dropdown widgets.
-
-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.
+**Fields and keys.** Field actions use native locator `fill`, `press_sequentially`, `set_checked`, and `select_option(label=...)`. Combobox actions support native `<select>` elements, not custom dropdown widgets. With `clear=false`, text uses `press_sequentially` even when `slowly=false`; an empty value preserves existing content. With `slowly=true`, text clears first unless `clear=false`, then each character gets a fresh 50-150 ms delay. Every pair of actions also gets a fresh 100-300 ms pause, including explicit wait actions, with no leading or trailing pause.
-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.
+Each `press_key` uses native `page.keyboard.press` at the current focus. Keep a shortcut such as `"ControlOrMeta+A"` in one `key` string, then use another `press_key` action with `"Backspace"` to delete. A space (`" "`) and plus (`"+"`) are valid key strings. The native API validates key names and shortcuts when pressed. Use a click action to focus the intended control before an Enter press when needed. Key presses do not wait for navigation.
-### `browser_press_key` -- Chain keys and shortcuts at the current focus
+**Waits.** Element waits are strict: multiple matches return an error. `attached` means present in the DOM, and `detached` means absent. `visible` requires a nonempty bounding box and no `visibility:hidden`; `hidden` also succeeds when the element is absent. Load waits observe the current committed document and return immediately if the state was already reached. A click or key press followed by `wait_load` does not guarantee waiting for delayed future navigation. `domcontentloaded` waits for DOMContentLoaded, not all future JavaScript work; `load` waits for the load event; `networkidle` requires no active network connections for at least 500 ms and does not prove application readiness. Prefer a specific result element when it signals readiness.
-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 |
-|-----------|------|---------|-------------|
-| `session_id` | str | required | ID of an open browser session |
-| `keys` | list[str] | required | Nonempty ordered list of nonempty native key names, characters, or shortcuts |
-
-Use `["ControlOrMeta+A", "Backspace"]` to select all with the platform's modifier and then delete, or `["Tab", "Enter"]` to move focus and activate a control. Keep a shortcut in one item; separate items are separate presses. Use `["Escape"]` for one press; a space (`" "`) and plus (`"+"`) are valid list items. MCP validates the whole list and its string items before execution; the native API validates each key name or shortcut when pressed.
-
-Returns `Keys pressed.` as plain text without an automatic snapshot or a wait for navigation. An error or cancellation stops the remaining presses; completed actions are not undone or retried. The page reservation is released after success, failure, or cancellation. Use `browser_snapshot` to check partial effects before retrying. Invalid keys, unknown or HTTP sessions, and missing, closed, or busy pages return an error.
-
-### `browser_wait` -- Chain waits on the current page
-
-Runs native waits in order on the existing page in a dynamic or stealthy browser session without reloading it. Call `browser_fetch` first.
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `session_id` | str | required | ID of an open browser session |
-| `actions` | list[object] | required | Nonempty ordered list of `time`, `element`, or `load` waits |
-
-| Action `type` | Fields | Behavior |
-|---------------|--------|----------|
-| `time` | `milliseconds` | Fixed pause in finite nonnegative milliseconds |
-| `element` | `selector`, `state="visible"`, `timeout=30000` | Wait for a nonempty Playwright selector to reach `"visible"`, `"hidden"`, `"attached"`, or `"detached"` |
-| `load` | `state`, `timeout=30000` | Wait for `"domcontentloaded"`, `"load"`, or `"networkidle"` |
-
-Element and load timeouts are finite nonnegative milliseconds per action; 0 disables the limit. Element waits are strict: multiple matches return an error. `attached` means present in the DOM, and `detached` means absent. `visible` requires a nonempty bounding box and no `visibility:hidden`; `hidden` also succeeds when the element is absent.
-
-Load states use the same native browser waits as the fetchers. An already reached state returns immediately for the current document. `domcontentloaded` waits for the DOMContentLoaded event, not all future JavaScript work. `load` waits for the load event. `networkidle` requires no active network connections for at least 500 ms; it does not prove the application is ready. Prefer a specific element state when it signals readiness.
-
-For example, wait for the document, results, and loading overlay in order:
+For example, fill and submit a search, wait for its results, then hover over the results panel and scroll it:
```json
{
"session_id": "browser",
"actions": [
- {"type": "load", "state": "domcontentloaded"},
- {"type": "element", "selector": "#results", "state": "visible"},
- {"type": "element", "selector": "#loading", "state": "hidden"}
+ {"type": "textbox", "selector": "#search", "value": "books"},
+ {"type": "press_key", "key": "Enter"},
+ {"type": "wait_element", "selector": "#results"},
+ {"type": "move", "selector": "#results"},
+ {"type": "wheel", "delta_y": 500}
]
}
```
-MCP validates the whole list before execution. The page stays reserved for the full sequence and is released after success, failure, or cancellation. The first failure stops the remaining waits and reports the one-based action number, type, and native error. Cancellation also stops the sequence. Completed waits are not undone or retried.
+MCP validates the entire action schema, and all target combinations are checked before execution. Targets are resolved only when their action runs, so earlier actions can create later targets. One page stays reserved for the whole sequence, including waits and random pauses. The first runtime failure stops the chain and reports its one-based action number, type, and native error. Earlier effects remain, and the failed action itself may partly apply. Nothing is retried or rolled back. Cancellation also stops the chain and remains cancellation. A cancelled or timed-out click attempts to release its button while the page is open, preserving the original error if release fails. The page reservation is released after success, failure, or cancellation.
-Returns `Wait completed.` as plain text without a snapshot. Unknown or HTTP sessions and missing, closed, or busy pages return an error. Use `browser_snapshot` afterward to inspect the result.
+Returns `Actions completed.` as plain text without echoing field values or taking a snapshot. Use `browser_snapshot` before retrying after an error or when later actions depend on inspecting a page change. Unknown or HTTP sessions and missing, closed, or busy pages return an error.
### `session_make_request` -- HTTP request through an open requests session
@@ -326,10 +271,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, 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` |
-| Wait for content or a page load state | `browser_wait` with `session_id` |
+| Chain mouse, field, keyboard, or wait actions | `browser_actions` with `session_id` |
Start with `make_request` (fastest, lowest resource cost). Escalate to `browser_fetch_once` if content requires JS rendering. Escalate to `browser_stealth_fetch_once` only if blocked. For multiple pages from the same site, use a persistent session to avoid browser launch overhead.
@@ -420,7 +362,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`, `browser_fill_fields`, `browser_press_key`, `browser_wait`, 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_actions`, 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 a2c12b1..0d67f4f 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 eighteen 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 fifteen 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
@@ -41,18 +41,15 @@ The Scrapling MCP Server provides eighteen tools for web scraping and browser in
- **`browser_snapshot`**: Give the AI a structured text view of the current page without reloading it. Includes element roles, names, references, positions, and sizes to help the AI understand the page and target clicks.
-#### Mouse Actions
+#### Browser Actions
-- **`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.
+- **`browser_actions`**: Chain mouse actions, field filling, keyboard shortcuts, and waits in one call. For example, fill a search box, submit it, wait for results, and open a result. The AI can combine known steps while keeping snapshots separate when it needs to inspect a page change.
-#### Text Input and Keyboard
+ Reveal hover menus and tooltips, click buttons and links, or move over a nested panel and scroll it vertically or horizontally. Moves and clicks support 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 one or more fields anywhere on the page in one call, including text, checkboxes, radio buttons, and native dropdowns. Target fields through selectors or snapshot references. Replace or clear text, or type at the current caret without clearing existing content. Supports checking or unchecking boxes and choosing one or more dropdown options by their visible labels. Slow mode types text one character at a time with random pauses between characters and fields.
-- **`browser_press_key`**: Chain keys and shortcuts on the current page to move between fields, submit forms, or dismiss menus in one call. Supports actions such as selecting all text and then deleting it, using the browser's current focus for each press.
+ Target fields anywhere on the page through selectors or snapshot references. Fill text, check or uncheck boxes, select radio buttons, and choose one or more native dropdown options by their visible labels. Text can replace existing content, clear it, or continue at the current caret. Keyboard shortcuts can select and delete text, move focus, submit forms, or dismiss menus. Slow mode types one character at a time with random pauses between characters and all actions.
-#### Waiting
-
-- **`browser_wait`**: Chain waits for delayed content, loading overlays, and page load events in one call without reloading the current page. For example, wait for the document to load, results to appear, and a loading overlay to disappear before the next action. Also supports fixed pauses and waiting for network activity to settle.
+ Wait for results to appear, loading overlays to disappear, or page load events before the next action. Also supports fixed pauses and waiting for network activity to settle.
### Shadow DOM
@@ -213,7 +210,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`, `browser_fill_fields`, `browser_press_key`, `browser_wait`, 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_actions`, 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 4f71b92..64ec8f9 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 eighteen 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 fifteen 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`, `browser_fill_fields`, `browser_press_key`, and `browser_wait` 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` and `browser_actions` return plain text.
## ::: scrapling.core.ai.ResponseModel
handler: python
@@ -57,10 +57,13 @@ 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`**: 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_wait`**: Chain waits for page load events, content appearing, and loading overlays disappearing in one call on the current page. Supports fixed pauses and waiting for network activity to settle without reloading the page.
+- **`browser_actions`**: Chain mouse moves, hovers, clicks, scrolling, field filling, keyboard shortcuts, and waits in one call. Fill a search box, submit it, wait for results, and open a result without a separate call for each step.
+
+ Moves and clicks target selectors, snapshot references, or coordinates; element targets wait and scroll into view. Supports movement in multiple steps, left, right, and middle clicks, double-clicks, and scrolling nested panels.
+
+ Target fields anywhere on the page through selectors or snapshot references. Fill text, check or uncheck boxes, select radio buttons, and choose one or more native dropdown options by label. Replace or clear text, or type at the current caret. Keyboard shortcuts use the current focus. Slow mode adds random pauses between typed characters and all actions.
+
+ Wait for content, loading overlays, page load events, or settled network activity, or add a fixed pause before continuing.
- **`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.
## ::: scrapling.core.ai.ScraplingMCPServer
diff --git a/scrapling/core/ai.py b/scrapling/core/ai.py
index 6f6f39c..017c526 100644
--- a/scrapling/core/ai.py
+++ b/scrapling/core/ai.py
@@ -143,11 +143,8 @@ class _MouseWheel(TypedDict):
]
-MouseAction = Annotated[Union[_MouseMove, _MouseClick, _MouseWheel], Field(discriminator="type")]
-
-
class _TimeWait(TypedDict):
- type: Literal["time"]
+ type: Literal["wait_time"]
milliseconds: NonNegativeFiniteFloat
@@ -156,25 +153,32 @@ class _ConditionWait(TypedDict, total=False):
class _ElementWait(_ConditionWait):
- type: Literal["element"]
+ type: Literal["wait_element"]
selector: Annotated[NonEmptyString, Field(description="Playwright selector for one element.")]
state: NotRequired[Annotated[SelectorWaitStates, Field(default="visible", description="Hidden includes removal.")]]
class _LoadWait(_ConditionWait):
- type: Literal["load"]
+ type: Literal["wait_load"]
state: Annotated[
Literal["domcontentloaded", "load", "networkidle"],
Field(description="Current document readiness; networkidle waits for 500 ms without active connections."),
]
-WaitAction = Annotated[Union[_TimeWait, _ElementWait, _LoadWait], Field(discriminator="type")]
+class _KeyPress(TypedDict):
+ type: Literal["press_key"]
+ key: Annotated[
+ NonEmptyString, Field(description="Key or shortcut at current focus, e.g. Enter or ControlOrMeta+A.")
+ ]
class _FormTarget(TypedDict, total=False):
selector: Optional[NonEmptyString]
ref: Optional[NonEmptyString]
+ timeout: Annotated[
+ NonNegativeFiniteFloat, Field(default=30000, description="Limit per native operation in ms; 0 disables it.")
+ ]
class _TextFormField(_FormTarget):
@@ -200,8 +204,21 @@ class _SelectFormField(_FormTarget):
value: Annotated[Union[str, List[str]], Field(description="Option label(s); [] clears selection.")]
-FormField = Annotated[
- Union[_TextFormField, _CheckboxFormField, _RadioFormField, _SelectFormField], Field(discriminator="type")
+BrowserAction = Annotated[
+ Union[
+ _MouseMove,
+ _MouseClick,
+ _MouseWheel,
+ _TextFormField,
+ _CheckboxFormField,
+ _RadioFormField,
+ _SelectFormField,
+ _KeyPress,
+ _TimeWait,
+ _ElementWait,
+ _LoadWait,
+ ],
+ Field(discriminator="type"),
]
@@ -508,137 +525,104 @@ class ScraplingMCPServer:
else:
page_info.mark_ready()
- async def browser_wait(
- self,
- session_id: str,
- actions: Annotated[List[WaitAction], Field(min_length=1)],
- ) -> str:
- """Run time, element, or load waits in order on the current page; return plain text. No navigation or snapshot.
- Stop on the first error, identifying its action. Load states do not guarantee all later JavaScript has finished.
-
- :param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param actions: Ordered waits; each condition has its own timeout. Time actions use milliseconds.
- """
- with self._browser_page(session_id) as (_, page):
- for index, action in enumerate(actions, 1):
- try:
- if action["type"] == "time":
- await page.wait_for_timeout(action["milliseconds"])
- elif action["type"] == "element":
- await page.locator(action["selector"]).wait_for(
- state=action.get("state", "visible"), timeout=action.get("timeout", 30000)
- )
- else:
- await page.wait_for_load_state(action["state"], timeout=action.get("timeout", 30000))
- except Exception as exc:
- raise RuntimeError(f"Wait action {index} ({action['type']}) failed: {exc}") from exc
- return "Wait completed."
-
- async def browser_mouse(
+ async def browser_actions(
self,
session_id: str,
- actions: Annotated[List[MouseAction], Field(min_length=1)],
+ actions: Annotated[List[BrowserAction], Field(min_length=1)],
+ slowly: bool = False,
) -> str:
- """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.
+ """Run mouse, field, key, and wait actions in order; return plain text without a snapshot.
+ Stop on the first error, identifying its action; partial effects remain. No retries.
+ Element mouse targets auto-wait and scroll into view; coordinates and wheel do not wait for navigation or scrolling.
+ Cancelled/timed-out clicks attempt button release. Load waits observe the current document, not future navigation.
:param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param actions: Ordered actions; move/click need exactly one selector, snapshot ref, or (x, y) pair in viewport CSS pixels.
+ :param actions: Ordered actions; fields need one selector/ref, mouse targets one selector/ref or viewport (x, y).
+ :param slowly: Fresh random delays: 50-150 ms per character, 100-300 ms between all actions, including waits.
"""
for index, action in enumerate(actions, 1):
- if action["type"] != "wheel" and (
+ if action["type"] in ("move", "click") 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'."
+ f"Action {index} ({action['type']}) needs exactly one target: 'selector', 'ref', or both 'x' and 'y'."
)
+ if action["type"] in ("textbox", "checkbox", "radio", "combobox") and (
+ (action.get("selector") is None) == (action.get("ref") is None)
+ ):
+ raise ValueError(f"Action {index} ({action['type']}) needs exactly one target: 'selector' or 'ref'.")
with self._browser_page(session_id) as (_, page):
for index, action in enumerate(actions, 1):
try:
- if action["type"] == "wheel":
+ if slowly and index > 1:
+ await sleep(uniform(0.1, 0.3))
+ if action["type"] == "wait_time":
+ await page.wait_for_timeout(action["milliseconds"])
+ elif action["type"] == "wait_element":
+ await page.locator(action["selector"]).wait_for(
+ state=action.get("state", "visible"), timeout=action.get("timeout", 30000)
+ )
+ elif action["type"] == "wait_load":
+ await page.wait_for_load_state(action["state"], timeout=action.get("timeout", 30000))
+ elif action["type"] == "press_key":
+ await page.keyboard.press(action["key"])
+ elif 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
- )
- 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))
+ selector, ref = action.get("selector"), action.get("ref")
+ timeout = action.get("timeout", 30000)
+ if action["type"] == "move" or action["type"] == "click":
+ locator = (
+ page.locator(selector or f"aria-ref={ref}")
+ if selector is not None or ref is not None
+ else None
+ )
+ if action["type"] == "move":
+ if locator is not None:
+ await locator.hover(timeout=timeout)
+ else:
+ await page.mouse.move(
+ action.get("x"), action.get("y"), steps=action.get("steps", 1)
+ )
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
+ 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=timeout)
+ 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
+ else:
+ locator = page.locator(selector or f"aria-ref={ref}")
+ if action["type"] == "textbox":
+ if action.get("clear", True):
+ await locator.fill("" if slowly else action["value"], timeout=timeout)
+ if slowly and action["value"]:
+ for character in action["value"]:
+ await locator.press_sequentially(
+ character, delay=uniform(50, 150), timeout=timeout
+ )
+ elif not action.get("clear", True):
+ await locator.press_sequentially(action["value"], timeout=timeout)
+ elif action["type"] == "combobox":
+ await locator.select_option(label=action["value"], timeout=timeout)
+ else:
+ await locator.set_checked(action["value"], timeout=timeout)
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)]
- ) -> str:
- """Press keys or shortcuts in order at the current focus; stop on error and return plain text on success.
-
- :param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param keys: Ordered presses, e.g. ["ControlOrMeta+A", "Backspace"] or ["Tab", "Enter"].
- """
- with self._browser_page(session_id) as (_, page):
- for key in keys:
- await page.keyboard.press(key)
- return "Keys pressed."
-
- async def browser_fill_fields(
- self,
- session_id: str,
- fields: Annotated[List[FormField], Field(min_length=1)],
- timeout: NonNegativeFiniteFloat = 30000,
- slowly: bool = False,
- ) -> str:
- """Fill fields in order; stop on error and return plain text on success.
-
- :param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param fields: Ordered field values; each needs exactly one selector or snapshot ref.
- :param timeout: Limit per operation in milliseconds; 0 disables it.
- :param slowly: Type with random pauses: 50-150 ms per character, 100-300 ms between fields.
- """
- if any((item.get("selector") is None) == (item.get("ref") is None) for item in fields):
- raise ValueError("Each field must have exactly one target: 'selector' or 'ref'.")
- with self._browser_page(session_id) as (_, page):
- for index, item in enumerate(fields):
- if slowly and index:
- await sleep(uniform(0.1, 0.3))
- locator = page.locator(item.get("selector") or f"aria-ref={item.get('ref')}")
- if item["type"] == "textbox":
- if item.get("clear", True):
- await locator.fill("" if slowly else item["value"], timeout=timeout)
- if slowly and item["value"]:
- for character in item["value"]:
- await locator.press_sequentially(character, delay=uniform(50, 150), timeout=timeout)
- elif not item.get("clear", True):
- await locator.press_sequentially(item["value"], timeout=timeout)
- elif item["type"] == "combobox":
- await locator.select_option(label=item["value"], timeout=timeout)
- else:
- await locator.set_checked(item["value"], timeout=timeout)
- return "Fields filled."
+ raise RuntimeError(f"Action {index} ({action['type']}) failed: {exc}") from exc
+ return "Actions completed."
async def browser_screenshot(
self,
@@ -1367,8 +1351,8 @@ 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` 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"].
+12. Use `browser_actions` for ordered mouse, field, key, and wait actions on the current page. Move/click targets use exactly one selector, current snapshot ref, or viewport (x, y) pair in CSS pixels; fields use one selector/ref. Wheel acts at the current pointer and does not wait for scrolling; coordinate clicks do not wait for navigation. Load waits observe the current document, so prefer a result-specific element for delayed navigation.
+13. Use `browser_snapshot` to inspect results before repeating failed actions or choosing targets that depend on page changes. Actions may partly complete before an error; completed effects are not undone or retried. To submit with Enter, focus the intended control and use a press_key action with key="Enter".
""",
}
if self._auth_token:
@@ -1461,30 +1445,9 @@ class ScraplingMCPServer:
annotations=_FETCH_TOOL_ANNOTATIONS,
)
server.add_tool(
- self.browser_wait,
- title="Wait",
- description=self.browser_wait.__doc__,
- structured_output=False,
- annotations=_FETCH_TOOL_ANNOTATIONS,
- )
- server.add_tool(
- self.browser_mouse,
- title="Mouse actions",
- description=self.browser_mouse.__doc__,
- structured_output=False,
- annotations=_INPUT_TOOL_ANNOTATIONS,
- )
- server.add_tool(
- self.browser_press_key,
- title="Press keys",
- description=self.browser_press_key.__doc__,
- structured_output=False,
- annotations=_INPUT_TOOL_ANNOTATIONS,
- )
- server.add_tool(
- self.browser_fill_fields,
- title="Fill fields",
- description=self.browser_fill_fields.__doc__,
+ self.browser_actions,
+ title="Browser actions",
+ description=self.browser_actions.__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 f1064bd..8fba5a6 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 18 tools are advertised, with plain content for screenshots, snapshots, waits, and input actions"""
+ """All 15 tools are advertised, with plain content for screenshots, snapshots, waits, and input actions"""
server = ScraplingMCPServer()._build_server("127.0.0.1", 8000)
async with Client(server) as client:
assert client.instructions
@@ -990,6 +990,10 @@ class TestServerToolRegistration:
for name in (
"browser_type",
"browser_fill_form",
+ "browser_fill_fields",
+ "browser_mouse",
+ "browser_wait",
+ "browser_press_key",
"open_session",
"session_fetch",
"screenshot",
@@ -1005,16 +1009,17 @@ class TestServerToolRegistration:
result = await client.call_tool(name, {})
assert result.is_error
- assert len(tools) == 18
+ assert len(tools) == 15
assert tools["browser_screenshot"].output_schema is None
assert tools["browser_snapshot"].output_schema is None
- assert tools["browser_wait"].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 tools["browser_actions"].output_schema is None
assert {
"browser_type",
"browser_fill_form",
+ "browser_fill_fields",
+ "browser_mouse",
+ "browser_wait",
+ "browser_press_key",
"session_snapshot",
"open_session",
"session_fetch",
@@ -1041,10 +1046,7 @@ class TestServerToolRegistration:
not in (
"browser_screenshot",
"browser_snapshot",
- "browser_wait",
- "browser_mouse",
- "browser_press_key",
- "browser_fill_fields",
+ "browser_actions",
)
)
@@ -1110,7 +1112,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) == 18
+ assert len(annotations) == 15
for name in (
"make_request",
"bulk_get",
@@ -1122,7 +1124,6 @@ class TestServerToolRegistration:
"session_make_request",
"browser_snapshot",
"browser_screenshot",
- "browser_wait",
):
assert annotations[name].read_only_hint is True
assert annotations[name].open_world_hint is True
@@ -1132,11 +1133,7 @@ class TestServerToolRegistration:
assert annotations[name].open_world_hint is True
assert annotations["list_sessions"].read_only_hint is True
assert annotations["list_sessions"].open_world_hint is False
- for name in (
- "browser_mouse",
- "browser_press_key",
- "browser_fill_fields",
- ):
+ for name in ("browser_actions",):
assert annotations[name].read_only_hint is False
assert annotations[name].destructive_hint is True
assert annotations[name].idempotent_hint is False
diff --git a/tests/ai/test_browser_actions.py b/tests/ai/test_browser_actions.py
new file mode 100644
index 0000000..4698d13
--- /dev/null
+++ b/tests/ai/test_browser_actions.py
@@ -0,0 +1,221 @@
+from json import loads
+from re import search
+from unittest.mock import AsyncMock, Mock, call
+
+import pytest
+from mcp.client import Client
+from mcp.types import TextContent
+
+from scrapling.core.ai import ScraplingMCPServer, SessionType, _SessionEntry
+from scrapling.core._types import Any
+from scrapling.engines._browsers._base import AsyncSession
+from tests.ai.test_browser_wait import _browser
+
+
+def _server() -> tuple[ScraplingMCPServer, AsyncSession, Mock]:
+ server = ScraplingMCPServer()
+ session = AsyncSession()
+ session._is_alive = True
+ page = Mock()
+ page.is_closed.return_value = False
+ page.wait_for_timeout = AsyncMock()
+ page.wait_for_load_state = AsyncMock()
+ page.keyboard.press = AsyncMock()
+ page.mouse.wheel = AsyncMock()
+ for name in ("fill", "press_sequentially", "wait_for"):
+ setattr(page.locator.return_value, name, AsyncMock())
+ session.page_pool.add_page(page).mark_ready()
+ server._sessions["browser"] = _SessionEntry(session, "dynamic")
+ return server, session, page
+
+
[email protected]("slowly", [False, True])
+async def test_mixed_actions_keep_order_and_sample_each_delay(slowly: bool, monkeypatch: pytest.MonkeyPatch) -> None:
+ server, session, page = _server()
+ events = Mock()
+ pause = AsyncMock()
+ random = Mock(side_effect=[55, 145, 0.11, 0.12, 0.13, 0.14, 0.15])
+ monkeypatch.setattr("scrapling.core.ai.uniform", random)
+ monkeypatch.setattr("scrapling.core.ai.sleep", pause)
+
+ async def reserved(*args: Any, **kwargs: Any) -> None:
+ assert session.page_pool.pages[0].state == "busy"
+
+ for name, method in (
+ ("fill", page.locator.return_value.fill),
+ ("type", page.locator.return_value.press_sequentially),
+ ("key", page.keyboard.press),
+ ("time", page.wait_for_timeout),
+ ("wheel", page.mouse.wheel),
+ ("element", page.locator.return_value.wait_for),
+ ("load", page.wait_for_load_state),
+ ("pause", pause),
+ ):
+ method.side_effect = reserved
+ events.attach_mock(method, name)
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ result = await client.call_tool(
+ "browser_actions",
+ {
+ "session_id": "browser",
+ "slowly": slowly,
+ "actions": [
+ {"type": "textbox", "selector": "#name", "value": "ab", "timeout": 17},
+ {"type": "press_key", "key": "Tab"},
+ {"type": "wait_time", "milliseconds": 12},
+ {"type": "wheel", "delta_y": 4},
+ {"type": "wait_element", "selector": "#ready", "timeout": 23},
+ {"type": "wait_load", "state": "load", "timeout": 31},
+ ],
+ },
+ )
+ assert not result.is_error and result.structured_content is None
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
+ expected = [call.fill("" if slowly else "ab", timeout=17)]
+ if slowly:
+ expected += [call.type("a", delay=55, timeout=17), call.type("b", delay=145, timeout=17)]
+ for delay, action in zip(
+ (0.11, 0.12, 0.13, 0.14, 0.15),
+ (
+ call.key("Tab"),
+ call.time(12),
+ call.wheel(0, 4),
+ call.element(state="visible", timeout=23),
+ call.load("load", timeout=31),
+ ),
+ ):
+ if slowly:
+ expected.append(call.pause(delay))
+ expected.append(action)
+ assert events.mock_calls == expected
+ assert random.call_args_list == ([call(50, 150)] * 2 + [call(0.1, 0.3)] * 5 if slowly else [])
+ assert page.is_closed.call_count == 2
+ assert session.page_pool.pages[0].state == "ready"
+
+
+ "invalid",
+ [
+ {"type": "textbox", "selector": "#name", "ref": "e1", "value": "bad"},
+ {"type": "click", "x": 10},
+ {"type": "combobox", "selector": "#kind", "value": {}},
+ {"type": "press_key", "key": ""},
+ {"type": "wait_element", "selector": "#ready", "timeout": -1},
+ ],
+)
+async def test_invalid_later_action_prevents_other_action_kinds(invalid: 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_actions",
+ {
+ "session_id": "browser",
+ "actions": [
+ {"type": "wait_time", "milliseconds": 0},
+ {"type": "textbox", "selector": "#name", "value": "unchanged"},
+ invalid,
+ {"type": "press_key", "key": "Enter"},
+ ],
+ },
+ )
+ assert result.is_error
+ page.is_closed.assert_not_called()
+ page.wait_for_timeout.assert_not_awaited()
+ page.locator.assert_not_called()
+ page.keyboard.press.assert_not_awaited()
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("session_type", ["dynamic", "stealthy"])
[email protected]("slowly", [False, True])
+async def test_live_mixed_chain_resolves_targets_created_by_earlier_actions(
+ session_type: SessionType, slowly: bool
+) -> None:
+ async with _browser(session_type) as (client, session, page):
+ await page.set_content("""<form><label>Query<input id=query></label><button>Search</button></form>
+ <div id=loading hidden>Loading</div><div id=results></div><div id=details></div><textarea id=events hidden>[]</textarea>
+ <script>
+ const record = value => {
+ const output = document.querySelector('#events');
+ output.value = JSON.stringify([...JSON.parse(output.value), value]);
+ };
+ document.querySelector('form').onsubmit = event => {
+ event.preventDefault();
+ record('submit:' + document.querySelector('#query').value);
+ document.querySelector('#loading').hidden = false;
+ setTimeout(() => {
+ document.querySelector('#results').innerHTML = '<button id=result>Result</button><button id=choose hidden>Choose</button>';
+ document.querySelector('#loading').hidden = true;
+ document.querySelector('#result').onmouseenter = () => {
+ record('hover');
+ document.querySelector('#choose').hidden = false;
+ };
+ document.querySelector('#choose').onclick = () => {
+ record('choose');
+ document.querySelector('#details').innerHTML = '<input id=note><input id=agree type=checkbox><select id=kind><option value=a>A</option><option value=b>B</option></select>';
+ };
+ }, 80);
+ };
+ </script>""")
+ snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ assert not snapshot.is_error and isinstance(snapshot.content[0], TextContent)
+ ref = search(r'textbox "Query".*?\[ref=([^\]]+)\]', snapshot.content[0].text)
+ assert ref is not None
+ result = await client.call_tool(
+ "browser_actions",
+ {
+ "session_id": "browser",
+ "slowly": slowly,
+ "actions": [
+ {"type": "textbox", "ref": ref[1], "value": "Scrapling"},
+ {"type": "press_key", "key": "Enter"},
+ {"type": "wait_element", "selector": "#result", "timeout": 5000},
+ {"type": "wait_element", "selector": "#loading", "state": "hidden", "timeout": 5000},
+ {"type": "move", "selector": "#result", "timeout": 5000},
+ {"type": "click", "selector": "#choose", "timeout": 5000},
+ {"type": "textbox", "selector": "#note", "value": "Done", "timeout": 5000},
+ {"type": "checkbox", "selector": "#agree", "value": True, "timeout": 5000},
+ {"type": "combobox", "selector": "#kind", "value": "B", "timeout": 5000},
+ ],
+ },
+ )
+ assert not result.is_error and result.content == [TextContent(type="text", text="Actions completed.")]
+ assert loads(await page.locator("#events").input_value()) == ["submit:Scrapling", "hover", "choose"]
+ assert await page.locator("#note").input_value() == "Done"
+ assert await page.locator("#agree").is_checked()
+ assert await page.locator("#kind").input_value() == "b"
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("session_type", ["dynamic", "stealthy"])
+async def test_live_stale_ref_stops_mixed_chain_without_retargeting(session_type: SessionType) -> None:
+ async with _browser(session_type) as (client, session, page):
+ await page.set_content("""<label>Old<input id=field value=old></label><button id=replace>Replace</button>
+ <script>
+ document.querySelector('#replace').onclick = () => {
+ document.querySelector('#field').outerHTML = '<input id=field value=new>';
+ };
+ </script>""")
+ snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ assert not snapshot.is_error and isinstance(snapshot.content[0], TextContent)
+ ref = search(r'textbox "Old".*?\[ref=([^\]]+)\]', snapshot.content[0].text)
+ assert ref is not None
+ result = await client.call_tool(
+ "browser_actions",
+ {
+ "session_id": "browser",
+ "actions": [
+ {"type": "click", "selector": "#replace"},
+ {"type": "textbox", "ref": ref[1], "value": "wrong", "timeout": 100},
+ {"type": "textbox", "selector": "#field", "value": "skipped"},
+ ],
+ },
+ )
+ assert result.is_error and isinstance(result.content[0], TextContent)
+ assert "Action 2 (textbox) failed:" in result.content[0].text
+ assert await page.locator("#field").input_value() == "new"
+ assert session.page_pool.pages[0].state == "ready"
diff --git a/tests/ai/test_browser_fill_fields.py b/tests/ai/test_browser_fill_fields.py
index 6d561bd..d01a875 100644
--- a/tests/ai/test_browser_fill_fields.py
+++ b/tests/ai/test_browser_fill_fields.py
@@ -56,30 +56,43 @@ def _server(session_type: SessionType = "dynamic") -> tuple[ScraplingMCPServer,
@pytest.mark.asyncio
-async def test_browser_fill_fields_schema() -> None:
+async def test_browser_actions_fields_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_fill_fields")
- assert tool.title == "Fill fields"
+ tool = next(tool for tool in (await client.list_tools()).tools if tool.name == "browser_actions")
+ assert tool.title == "Browser actions"
schema = tool.input_schema
- assert set(schema["properties"]) == {"session_id", "fields", "timeout", "slowly"}
- assert schema["required"] == ["session_id", "fields"]
+ assert set(schema["properties"]) == {"session_id", "actions", "slowly"}
+ assert schema["required"] == ["session_id", "actions"]
assert schema["properties"]["slowly"]["type"] == "boolean"
assert schema["properties"]["slowly"]["default"] is False
- assert schema["properties"]["timeout"]["default"] == 30000
- assert schema["properties"]["timeout"]["minimum"] == 0
- fields = schema["properties"]["fields"]
- assert fields["type"] == "array" and fields["minItems"] == 1
- items = fields["items"]
+ 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) == {"textbox", "checkbox", "radio", "combobox"}
- assert len(items["oneOf"]) == 4
- for kind, variant in variants.items():
+ assert set(variants) == {
+ "textbox",
+ "checkbox",
+ "radio",
+ "combobox",
+ "move",
+ "click",
+ "wheel",
+ "press_key",
+ "wait_time",
+ "wait_element",
+ "wait_load",
+ }
+ assert len(items["oneOf"]) == 11
+ for kind in ("textbox", "checkbox", "radio", "combobox"):
+ variant = variants[kind]
assert set(variant["required"]) == {"type", "value"}
- assert set(variant["properties"]) == {"type", "value", "selector", "ref"} | (
+ assert set(variant["properties"]) == {"type", "value", "selector", "ref", "timeout"} | (
{"clear"} if kind == "textbox" else set()
)
assert variant["properties"]["type"]["const"] == kind
+ assert variant["properties"]["timeout"]["default"] == 30000
+ assert variant["properties"]["timeout"]["minimum"] == 0
for target in ("selector", "ref"):
assert {"type": "null"} in variant["properties"][target]["anyOf"]
assert any(option.get("minLength") == 1 for option in variant["properties"][target]["anyOf"])
@@ -93,13 +106,13 @@ async def test_browser_fill_fields_schema() -> None:
@pytest.mark.asyncio
@pytest.mark.parametrize("options, timeout", [({}, 30000), ({"timeout": 0}, 0), ({"timeout": 123.5}, 123.5)])
-async def test_browser_fill_fields_forwards_native_actions_in_order(
+async def test_browser_actions_fields_forwards_native_actions_in_order(
options: dict[str, Any], timeout: float, monkeypatch: pytest.MonkeyPatch
) -> None:
server, session, page = _server()
pause = AsyncMock()
monkeypatch.setattr("scrapling.core.ai.sleep", pause)
- fields = [
+ actions = [
{**TEXT_FIELD, "ref": None},
{"type": "textbox", "selector": None, "ref": "e2", "value": "", "clear": True},
{"type": "checkbox", "selector": "#agree", "value": True},
@@ -111,10 +124,12 @@ async def test_browser_fill_fields_forwards_native_actions_in_order(
{"type": "combobox", "selector": "#colors", "value": []},
]
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_fill_fields", {"session_id": "browser", "fields": fields, **options})
+ result = await client.call_tool(
+ "browser_actions", {"session_id": "browser", "actions": [{**action, **options} for action in actions]}
+ )
assert not result.is_error
assert result.structured_content is None
- assert result.content == [TextContent(type="text", text="Fields filled.")]
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
assert page.locator.mock_calls == [
call("#name"),
call().fill("private value", timeout=timeout),
@@ -146,18 +161,18 @@ async def test_browser_fill_fields_forwards_native_actions_in_order(
@pytest.mark.asyncio
@pytest.mark.parametrize("slowly", [False, True])
@pytest.mark.parametrize("value", ["xy", ""])
-async def test_browser_fill_fields_types_without_clearing(
+async def test_browser_actions_fields_types_without_clearing(
slowly: bool, value: str, monkeypatch: pytest.MonkeyPatch
) -> None:
server, session, page = _server()
monkeypatch.setattr("scrapling.core.ai.uniform", Mock(side_effect=[60, 140]))
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_fill_fields",
- {"session_id": "browser", "fields": [{**TEXT_FIELD, "value": value, "clear": False}], "slowly": slowly},
+ "browser_actions",
+ {"session_id": "browser", "actions": [{**TEXT_FIELD, "value": value, "clear": False}], "slowly": slowly},
)
assert not result.is_error
- assert result.content == [TextContent(type="text", text="Fields filled.")]
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
page.locator.return_value.fill.assert_not_awaited()
assert page.locator.return_value.press_sequentially.await_args_list == (
[call("x", delay=60, timeout=30000), call("y", delay=140, timeout=30000)]
@@ -168,15 +183,15 @@ async def test_browser_fill_fields_types_without_clearing(
@pytest.mark.asyncio
-async def test_browser_fill_fields_slow_pacing_and_empty_text(monkeypatch: pytest.MonkeyPatch) -> None:
+async def test_browser_actions_fields_slow_pacing_and_empty_text(monkeypatch: pytest.MonkeyPatch) -> None:
server, session, page = _server()
- actions = Mock()
- actions.attach_mock(page.locator, "locator")
- actions.pause = AsyncMock()
- monkeypatch.setattr("scrapling.core.ai.sleep", actions.pause)
+ calls = Mock()
+ calls.attach_mock(page.locator, "locator")
+ calls.pause = AsyncMock()
+ monkeypatch.setattr("scrapling.core.ai.sleep", calls.pause)
intervals = Mock(side_effect=[60, 140, 0.12, 0.27, 0.18, 0.22])
monkeypatch.setattr("scrapling.core.ai.uniform", intervals)
- fields = [
+ actions = [
{**TEXT_FIELD, "value": "ab"},
{"type": "textbox", "ref": "e2", "value": ""},
{"type": "checkbox", "selector": "#agree", "value": True},
@@ -185,11 +200,12 @@ async def test_browser_fill_fields_slow_pacing_and_empty_text(monkeypatch: pytes
]
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_fill_fields", {"session_id": "browser", "fields": fields, "slowly": True, "timeout": 0}
+ "browser_actions",
+ {"session_id": "browser", "actions": [{**action, "timeout": 0} for action in actions], "slowly": True},
)
assert not result.is_error
- assert result.content == [TextContent(type="text", text="Fields filled.")]
- assert actions.mock_calls == [
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
+ assert calls.mock_calls == [
call.locator("#name"),
call.locator().fill("", timeout=0),
call.locator().press_sequentially("a", delay=60, timeout=0),
@@ -213,7 +229,7 @@ async def test_browser_fill_fields_slow_pacing_and_empty_text(monkeypatch: pytes
@pytest.mark.asyncio
@pytest.mark.parametrize("method", ["fill", "press_sequentially"])
-async def test_browser_fill_fields_slow_failure_stops_before_next_pause(
+async def test_browser_actions_fields_slow_failure_stops_before_next_pause(
method: str, monkeypatch: pytest.MonkeyPatch
) -> None:
server, session, page = _server()
@@ -224,7 +240,7 @@ async def test_browser_fill_fields_slow_failure_stops_before_next_pause(
monkeypatch.setattr("scrapling.core.ai.sleep", pause)
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_fill_fields", {"session_id": "browser", "fields": [TEXT_FIELD, TEXT_FIELD], "slowly": True}
+ "browser_actions", {"session_id": "browser", "actions": [TEXT_FIELD, TEXT_FIELD], "slowly": True}
)
assert result.is_error
page.locator.assert_called_once_with("#name")
@@ -256,11 +272,11 @@ async def test_browser_fill_fields_slow_failure_stops_before_next_pause(
{"type": "combobox", "value": ["Red", None]},
],
)
-async def test_browser_fill_fields_invalid_later_field_prevents_all_actions(invalid: dict[str, Any]) -> None:
+async def test_browser_actions_fields_invalid_later_field_prevents_all_actions(invalid: 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_fill_fields", {"session_id": "browser", "fields": [TEXT_FIELD, {**TEXT_FIELD, **invalid}]}
+ "browser_actions", {"session_id": "browser", "actions": [TEXT_FIELD, {**TEXT_FIELD, **invalid}]}
)
assert result.is_error
page.is_closed.assert_not_called()
@@ -273,30 +289,32 @@ async def test_browser_fill_fields_invalid_later_field_prevents_all_actions(inva
"values",
[
{},
- {"fields": []},
- {"fields": None},
- {"fields": TEXT_FIELD},
- {"fields": [{"type": "textbox", "selector": "#name"}]},
- {"fields": [{"selector": "#name", "value": "value"}]},
- {"fields": [TEXT_FIELD], "timeout": -1},
- {"fields": [TEXT_FIELD], "slowly": "invalid"},
+ {"actions": []},
+ {"actions": None},
+ {"actions": TEXT_FIELD},
+ {"actions": [{"type": "textbox", "selector": "#name"}]},
+ {"actions": [{"selector": "#name", "value": "value"}]},
+ {"actions": [{**TEXT_FIELD, "timeout": -1}]},
+ {"actions": [TEXT_FIELD], "slowly": "invalid"},
],
)
-async def test_browser_fill_fields_invalid_arguments_do_not_reserve_page(values: dict[str, Any]) -> None:
+async def test_browser_actions_fields_invalid_arguments_do_not_reserve_page(values: dict[str, Any]) -> None:
server, _, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_fill_fields", {"session_id": "browser", **values})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", **values})
assert result.is_error
page.is_closed.assert_not_called()
page.locator.assert_not_called()
@pytest.mark.parametrize("timeout", [float("nan"), float("inf"), float("-inf")])
-def test_browser_fill_fields_rejects_nonfinite_timeout(timeout: float) -> None:
- tool = ScraplingMCPServer()._build_server("127.0.0.1", 8000)._tool_manager.get_tool("browser_fill_fields")
+def test_browser_actions_fields_rejects_nonfinite_timeout(timeout: float) -> None:
+ tool = ScraplingMCPServer()._build_server("127.0.0.1", 8000)._tool_manager.get_tool("browser_actions")
assert tool is not None
with pytest.raises(ValidationError):
- tool.fn_metadata.arg_model.model_validate({"session_id": "browser", "fields": [TEXT_FIELD], "timeout": timeout})
+ tool.fn_metadata.arg_model.model_validate(
+ {"session_id": "browser", "actions": [{**TEXT_FIELD, "timeout": timeout}]}
+ )
@pytest.mark.asyncio
@@ -311,7 +329,7 @@ def test_browser_fill_fields_rejects_nonfinite_timeout(timeout: float) -> None:
("closed", "closed"),
],
)
-async def test_browser_fill_fields_session_errors_reach_mcp(state: str, message: str) -> None:
+async def test_browser_actions_fields_session_errors_reach_mcp(state: str, message: str) -> None:
server, session, page = _server("static" if state == "static" else "dynamic")
if state == "missing":
server._sessions.clear()
@@ -324,7 +342,7 @@ async def test_browser_fill_fields_session_errors_reach_mcp(state: str, message:
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_fill_fields", {"session_id": "browser", "fields": [TEXT_FIELD]})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", "actions": [TEXT_FIELD]})
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
assert message in result.content[0].text
@@ -340,7 +358,7 @@ async def test_browser_fill_fields_session_errors_reach_mcp(state: str, message:
"session_type, error", [("dynamic", PlaywrightTimeoutError), ("stealthy", PatchrightTimeoutError)]
)
@pytest.mark.parametrize("clear, slowly", [(True, False), (False, False), (False, True)])
-async def test_browser_fill_fields_timeout_stops_and_releases_page(
+async def test_browser_actions_fields_timeout_stops_and_releases_page(
session_type: SessionType, error: type[Exception], clear: bool, slowly: bool
) -> None:
server, session, page = _server(session_type)
@@ -348,30 +366,30 @@ async def test_browser_fill_fields_timeout_stops_and_releases_page(
action.side_effect = error("typing timed out")
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_fill_fields",
- {"session_id": "browser", "fields": [{**TEXT_FIELD, "clear": clear}, TEXT_FIELD], "slowly": slowly},
+ "browser_actions",
+ {"session_id": "browser", "actions": [{**TEXT_FIELD, "clear": clear}, TEXT_FIELD], "slowly": slowly},
)
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
- assert "typing timed out" in result.content[0].text
+ assert "Action 1 (textbox) failed: typing timed out" in result.content[0].text
action.assert_awaited_once()
page.locator.assert_called_once_with("#name")
page.locator.return_value.press.assert_not_called()
assert session.page_pool.pages[0].state == "ready"
action.side_effect = None
- assert await server.browser_fill_fields("browser", [TEXT_FIELD]) == "Fields filled."
+ assert await server.browser_actions("browser", [TEXT_FIELD]) == "Actions completed."
@pytest.mark.asyncio
-async def test_browser_fill_fields_error_stops_remaining_fields_and_releases_page() -> None:
+async def test_browser_actions_fields_error_stops_remaining_fields_and_releases_page() -> None:
server, session, page = _server()
page.locator.return_value.fill.side_effect = [None, RuntimeError("field failed")]
- fields = [{**TEXT_FIELD, "value": value} for value in ("first", "second", "third")]
+ actions = [{**TEXT_FIELD, "value": value} for value in ("first", "second", "third")]
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_fill_fields", {"session_id": "browser", "fields": fields})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", "actions": actions})
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
- assert "field failed" in result.content[0].text
+ assert "Action 2 (textbox) failed: field failed" in result.content[0].text
assert page.locator.return_value.fill.await_args_list == [
call("first", timeout=30000),
call("second", timeout=30000),
@@ -382,11 +400,11 @@ async def test_browser_fill_fields_error_stops_remaining_fields_and_releases_pag
@pytest.mark.asyncio
@pytest.mark.parametrize("cancel_mode", ["task", "scope"])
@pytest.mark.parametrize("clear", [False, True])
-async def test_browser_fill_fields_cancellation_stops_remaining_fields(cancel_mode: str, clear: bool) -> None:
+async def test_browser_actions_fields_cancellation_stops_remaining_fields(cancel_mode: str, clear: bool) -> None:
server, session, page = _server()
entered = asyncio.Event()
scope = CancelScope()
- fields = [{**TEXT_FIELD, "value": value, "clear": clear} for value in ("first", "second", "third")]
+ actions = [{**TEXT_FIELD, "value": value, "clear": clear} for value in ("first", "second", "third")]
async def pending(value: str, **kwargs: Any) -> None:
if value == "second":
@@ -395,7 +413,7 @@ async def test_browser_fill_fields_cancellation_stops_remaining_fields(cancel_mo
async def fill() -> None:
with scope:
- await server.browser_fill_fields("browser", fields)
+ await server.browser_actions("browser", actions)
action = page.locator.return_value.fill if clear else page.locator.return_value.press_sequentially
action.side_effect = pending
@@ -404,7 +422,7 @@ async def test_browser_fill_fields_cancellation_stops_remaining_fields(cancel_mo
await asyncio.wait_for(entered.wait(), 5)
assert session.page_pool.pages[0].state == "busy"
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_press_key("browser", ["Enter"])
+ await server.browser_actions("browser", [{"type": "press_key", "key": "Enter"}])
finally:
scope.cancel() if cancel_mode == "scope" else task.cancel()
if cancel_mode == "scope":
@@ -423,7 +441,7 @@ async def test_browser_fill_fields_cancellation_stops_remaining_fields(cancel_mo
@pytest.mark.asyncio
@pytest.mark.parametrize("stage", ["typing", "pause"])
@pytest.mark.parametrize("cancel_mode", ["task", "scope"])
-async def test_browser_fill_fields_slow_cancellation_releases_page(
+async def test_browser_actions_fields_slow_cancellation_releases_page(
stage: str, cancel_mode: str, monkeypatch: pytest.MonkeyPatch
) -> None:
server, session, page = _server()
@@ -436,7 +454,7 @@ async def test_browser_fill_fields_slow_cancellation_releases_page(
async def fill() -> None:
with scope:
- await server.browser_fill_fields("browser", [TEXT_FIELD, TEXT_FIELD], slowly=True)
+ await server.browser_actions("browser", [TEXT_FIELD, TEXT_FIELD], slowly=True)
if stage == "typing":
page.locator.return_value.press_sequentially.side_effect = pending
@@ -447,7 +465,7 @@ async def test_browser_fill_fields_slow_cancellation_releases_page(
await asyncio.wait_for(entered.wait(), 5)
assert session.page_pool.pages[0].state == "busy"
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_press_key("browser", ["Enter"])
+ await server.browser_actions("browser", [{"type": "press_key", "key": "Enter"}])
finally:
scope.cancel() if cancel_mode == "scope" else task.cancel()
if cancel_mode == "scope":
@@ -485,7 +503,7 @@ async def _browser(session_type: SessionType) -> AsyncGenerator[tuple[Client, An
@pytest.mark.asyncio
@pytest.mark.parametrize("session_type", ["dynamic", "stealthy"])
-async def test_browser_fill_fields_live_mixed_fields_and_clearing(session_type: SessionType) -> None:
+async def test_browser_actions_fields_live_mixed_fields_and_clearing(session_type: SessionType) -> None:
async with _browser(session_type) as (client, session, page):
snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
assert not snapshot.is_error
@@ -493,7 +511,7 @@ async def test_browser_fill_fields_live_mixed_fields_and_clearing(session_type:
name = search(r'textbox "Name".*?\[ref=([^\]]+)\]', snapshot.content[0].text)
agree = search(r'checkbox "Agree".*?\[ref=([^\]]+)\]', snapshot.content[0].text)
assert name is not None and agree is not None
- fields = [
+ actions = [
{"type": "textbox", "ref": name[1], "value": "new α name"},
{"type": "textbox", "selector": 'xpath=//textarea[@id="notes"]', "value": "line one\nline two"},
{"type": "textbox", "selector": "#editor", "value": "edited content"},
@@ -503,7 +521,7 @@ async def test_browser_fill_fields_live_mixed_fields_and_clearing(session_type:
{"type": "combobox", "selector": "#country", "value": "United Kingdom"},
{"type": "combobox", "selector": "#colors", "value": ["Red", "Blue"]},
]
- filled = await client.call_tool("browser_fill_fields", {"session_id": "browser", "fields": fields})
+ filled = await client.call_tool("browser_actions", {"session_id": "browser", "actions": actions})
assert not filled.is_error
assert await page.locator("#name").input_value() == "new α name"
assert await page.locator("#notes").input_value() == "line one\nline two"
@@ -533,10 +551,10 @@ async def test_browser_fill_fields_live_mixed_fields_and_clearing(session_type:
"colors",
}
cleared = await client.call_tool(
- "browser_fill_fields",
+ "browser_actions",
{
"session_id": "browser",
- "fields": [
+ "actions": [
{"type": "textbox", "selector": "#name", "value": ""},
{"type": "checkbox", "selector": "#agree", "value": False},
{"type": "checkbox", "selector": "#updates", "value": True},
@@ -556,14 +574,14 @@ async def test_browser_fill_fields_live_mixed_fields_and_clearing(session_type:
@pytest.mark.asyncio
@pytest.mark.parametrize("session_type", ["dynamic", "stealthy"])
-async def test_browser_fill_fields_live_slow_typing_and_field_delays(session_type: SessionType) -> None:
+async def test_browser_actions_fields_live_slow_typing_and_field_delays(session_type: SessionType) -> None:
async with _browser(session_type) as (client, session, page):
snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
assert not snapshot.is_error
assert snapshot.content and isinstance(snapshot.content[0], TextContent)
name = search(r'textbox "Name".*?\[ref=([^\]]+)\]', snapshot.content[0].text)
assert name is not None
- fields = [
+ actions = [
{"type": "textbox", "ref": name[1], "value": "abc"},
{"type": "textbox", "selector": "#notes", "value": "x\ny"},
{"type": "textbox", "selector": "#editor", "value": "xyα🙂"},
@@ -572,7 +590,7 @@ async def test_browser_fill_fields_live_slow_typing_and_field_delays(session_typ
{"type": "combobox", "selector": "#country", "value": "United Kingdom"},
]
result = await client.call_tool(
- "browser_fill_fields", {"session_id": "browser", "fields": fields, "slowly": True}
+ "browser_actions", {"session_id": "browser", "actions": actions, "slowly": True}
)
assert not result.is_error
assert await page.locator("#name").input_value() == "abc"
@@ -600,8 +618,8 @@ async def test_browser_fill_fields_live_slow_typing_and_field_delays(session_typ
)
assert next_time - previous_time >= 80
cleared = await client.call_tool(
- "browser_fill_fields",
- {"session_id": "browser", "fields": [{**TEXT_FIELD, "value": ""}], "slowly": True},
+ "browser_actions",
+ {"session_id": "browser", "actions": [{**TEXT_FIELD, "value": ""}], "slowly": True},
)
assert not cleared.is_error
assert await page.locator("#name").input_value() == ""
@@ -612,7 +630,7 @@ async def test_browser_fill_fields_live_slow_typing_and_field_delays(session_typ
@pytest.mark.asyncio
@pytest.mark.parametrize("session_type", ["dynamic", "stealthy"])
@pytest.mark.parametrize("slowly", [False, True])
-async def test_browser_fill_fields_live_caret_selection_and_submit(session_type: SessionType, slowly: bool) -> None:
+async def test_browser_actions_fields_live_caret_selection_and_submit(session_type: SessionType, slowly: bool) -> None:
async with _browser(session_type) as (client, session, page):
snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
assert not snapshot.is_error
@@ -620,27 +638,27 @@ async def test_browser_fill_fields_live_caret_selection_and_submit(session_type:
name = search(r'textbox "Name".*?\[ref=([^\]]+)\]', snapshot.content[0].text)
assert name is not None
- async def fill(fields: list[dict[str, Any]]) -> None:
+ async def run(actions: list[dict[str, Any]]) -> None:
result = await client.call_tool(
- "browser_fill_fields", {"session_id": "browser", "fields": fields, "slowly": slowly}
+ "browser_actions", {"session_id": "browser", "actions": actions, "slowly": slowly}
)
assert not result.is_error
assert session.page_pool.pages[0].state == "ready"
- async def press(keys: list[str]) -> None:
- result = await client.call_tool("browser_press_key", {"session_id": "browser", "keys": keys})
- assert not result.is_error
-
- await fill([{**TEXT_FIELD, "value": "abcd"}])
- await press(["ArrowLeft"])
- await fill([{"type": "textbox", "ref": name[1], "value": "XY", "clear": False}])
+ await run([{**TEXT_FIELD, "value": "abcd"}, {"type": "press_key", "key": "ArrowLeft"}])
+ await run([{"type": "textbox", "ref": name[1], "value": "XY", "clear": False}])
assert await page.locator("#name").input_value() == "abcXYd"
- await press(["Shift+ArrowLeft", "Shift+ArrowLeft"])
- await fill([{**TEXT_FIELD, "value": "z", "clear": False}])
+ await run(
+ [
+ {"type": "press_key", "key": "Shift+ArrowLeft"},
+ {"type": "press_key", "key": "Shift+ArrowLeft"},
+ {**TEXT_FIELD, "value": "z", "clear": False},
+ ]
+ )
assert await page.locator("#name").input_value() == "abczd"
- await fill([{**TEXT_FIELD, "value": "", "clear": False}])
+ await run([{**TEXT_FIELD, "value": "", "clear": False}])
assert await page.locator("#name").input_value() == "abczd"
- await fill(
+ await run(
[
{**TEXT_FIELD, "value": "!", "clear": False},
{"type": "textbox", "selector": "#notes", "value": "new notes"},
@@ -649,11 +667,7 @@ 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_mouse", {"session_id": "browser", "actions": [{"type": "click", "ref": name[1]}]}
- )
- assert not focused.is_error
- await press(["Enter"])
+ await run([{"type": "click", "ref": name[1]}, {"type": "press_key", "key": "Enter"}])
assert await page.locator("#submitted").inner_text() == "1"
events = loads(await page.locator("#events").input_value())
assert [
@@ -663,24 +677,24 @@ async def test_browser_fill_fields_live_caret_selection_and_submit(session_type:
@pytest.mark.asyncio
@pytest.mark.parametrize("session_type", ["dynamic", "stealthy"])
-async def test_browser_fill_fields_live_failed_field_preserves_prior_changes(session_type: SessionType) -> None:
+async def test_browser_actions_fields_live_failed_field_preserves_prior_changes(session_type: SessionType) -> None:
async with _browser(session_type) as (client, session, page):
for selector in ("#missing", "input"):
await page.locator("#name").fill("initial")
result = await client.call_tool(
- "browser_fill_fields",
+ "browser_actions",
{
"session_id": "browser",
- "timeout": 100,
- "fields": [
+ "actions": [
{**TEXT_FIELD, "value": "changed first"},
- {**TEXT_FIELD, "selector": selector, "value": "fails"},
+ {**TEXT_FIELD, "selector": selector, "value": "fails", "timeout": 100},
{**TEXT_FIELD, "selector": "#notes", "value": "must not run"},
],
},
)
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
+ assert "Action 2 (textbox) failed:" in result.content[0].text
assert ("Timeout" if selector == "#missing" else "strict mode violation") in result.content[0].text
assert await page.locator("#name").input_value() == "changed first"
assert await page.locator("#notes").input_value() == "initial notes"
diff --git a/tests/ai/test_browser_mouse.py b/tests/ai/test_browser_mouse.py
index ab9a687..7e737ee 100644
--- a/tests/ai/test_browser_mouse.py
+++ b/tests/ai/test_browser_mouse.py
@@ -61,22 +61,37 @@ def _server(session_type: SessionType = "dynamic") -> tuple[ScraplingMCPServer,
async def test_browser_mouse_schema_and_annotations() -> None:
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}
- for name in ("browser_mouse_move", "browser_click", "browser_mouse_wheel"):
+ for name in ("browser_mouse", "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"
+ tool = tools["browser_actions"]
+ assert tool.title == "Browser actions"
schema = tool.input_schema
- assert set(schema["properties"]) == {"session_id", "actions"}
+ assert set(schema["properties"]) == {"session_id", "actions", "slowly"}
+ assert schema["properties"]["slowly"]["type"] == "boolean"
+ assert schema["properties"]["slowly"]["default"] is False
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 set(variants) == {
+ "move",
+ "click",
+ "wheel",
+ "wait_time",
+ "wait_element",
+ "wait_load",
+ "textbox",
+ "checkbox",
+ "radio",
+ "combobox",
+ "press_key",
+ }
+ assert len(items["oneOf"]) == 11
+ for kind in ("move", "click", "wheel"):
+ variant = variants[kind]
assert variant["required"] == ["type"]
assert variant["properties"]["type"]["const"] == kind
move = variants["move"]["properties"]
@@ -141,11 +156,11 @@ async def test_browser_mouse_forwards_native_actions(
server, session, page = _server(session_type)
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_mouse", {"session_id": "browser", "actions": [{"type": tool, **target, **options}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": tool, **target, **options}]}
)
assert not result.is_error
assert result.structured_content is None
- assert result.content == [TextContent(type="text", text="Mouse actions completed.")]
+ assert result.content == [TextContent(type="text", text="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()
@@ -203,7 +218,7 @@ async def test_browser_mouse_invalid_input_does_not_reserve_or_use_page(tool: st
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_mouse",
+ "browser_actions",
{
"session_id": "browser",
"actions": [{"type": "move", "x": 1, "y": 2}, {"type": tool, "x": 10, "y": 20, **values}],
@@ -221,7 +236,7 @@ async def test_browser_mouse_invalid_input_does_not_reserve_or_use_page(tool: st
@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("browser_mouse")
+ registered = server._build_server("127.0.0.1", 8000)._tool_manager.get_tool("browser_actions")
assert registered is not None
for field in fields:
with pytest.raises(ValidationError):
@@ -253,7 +268,7 @@ async def test_browser_mouse_requires_exactly_one_complete_target(tool: str, tar
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_mouse",
+ "browser_actions",
{"session_id": "browser", "actions": [{"type": "move", "x": 1, "y": 2}, {"type": tool, **target}]},
)
assert result.is_error
@@ -291,7 +306,7 @@ async def test_browser_mouse_session_errors_reach_mcp(tool: str, state: str, mes
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", {"session_id": "browser", "actions": [{"type": tool, "x": 10, "y": 20}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": tool, "x": 10, "y": 20}]}
)
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
@@ -324,7 +339,7 @@ async def test_browser_mouse_failure_is_not_retried_and_releases_page(
action.side_effect = fail
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_mouse", {"session_id": "browser", "actions": [{"type": tool, **target}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": tool, **target}]}
)
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
@@ -335,7 +350,7 @@ 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 server.browser_mouse("browser", [{"type": tool, **target}])
+ await server.browser_actions("browser", [{"type": tool, **target}])
page.close.assert_not_called()
page.mouse.wheel.assert_not_awaited()
page.mouse.up.assert_not_awaited()
@@ -355,14 +370,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("browser", [{"type": "move", **target, "steps": 3}, {"type": "wheel", "delta_y": 120}])
+ server.browser_actions("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_mouse("browser", [{"type": "click", "x": 10, "y": 20}])
+ await server.browser_actions("browser", [{"type": "click", "x": 10, "y": 20}])
with pytest.raises(RuntimeError, match="busy"):
await server.browser_snapshot("browser")
finally:
@@ -392,16 +407,16 @@ async def test_browser_mouse_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_mouse("browser", [{"type": "click", "selector": "button", "button": "right"}])
+ server.browser_actions("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("browser", [{"type": "move", "x": 30, "y": 40}])
+ await server.browser_actions("browser", [{"type": "move", "x": 30, "y": 40}])
release.set()
- with pytest.raises(RuntimeError, match=r"Mouse action 1 \(click\) failed: click timed out") as error:
+ with pytest.raises(RuntimeError, match=r"Action 1 \(click\) failed: click timed out") as error:
await task
assert isinstance(error.value.__cause__, error_type)
finally:
@@ -437,7 +452,7 @@ async def test_browser_mouse_cancelled_click_holds_page_until_button_is_released
async def click() -> None:
with scope:
- await server.browser_mouse(
+ await server.browser_actions(
"browser",
[{"type": "click", **target, "button": "right", "delay": 60000}, {"type": "wheel", "delta_y": 120}],
)
@@ -453,7 +468,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("browser", [{"type": "move", "x": 30, "y": 40}])
+ await server.browser_actions("browser", [{"type": "move", "x": 30, "y": 40}])
release.set()
if cancel_mode == "scope":
await asyncio.wait_for(task, 5)
@@ -509,7 +524,7 @@ async def test_browser_mouse_cleanup_failure_preserves_click_error(
page.locator.return_value.click.side_effect = press
page.mouse.up.side_effect = unpress
task = asyncio.create_task(
- server.browser_mouse(
+ server.browser_actions(
"browser",
[{"type": "click", "selector": "#target", "button": "right"}, {"type": "wheel", "delta_y": 120}],
)
@@ -521,7 +536,7 @@ async def test_browser_mouse_cleanup_failure_preserves_click_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 str(error.value) == "Action 1 (click) failed: click timed out"
assert original is timeout
assert original is not None and original.__cause__ is cleanup_error
finally:
@@ -543,7 +558,7 @@ async def test_browser_mouse_cleanup_failure_preserves_click_error(
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})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", "actions": actions})
assert result.is_error
page.is_closed.assert_not_called()
assert session.page_pool.pages[0].state == "ready"
@@ -574,9 +589,9 @@ async def test_browser_mouse_mixed_chain_keeps_one_page_reserved(session_type: S
{"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})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", "actions": actions})
assert not result.is_error
- assert result.content == [TextContent(type="text", text="Mouse actions completed.")]
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
assert page.mock_calls == [
call.is_closed(),
call.mouse.move(10, 20, steps=4),
@@ -608,8 +623,8 @@ async def test_browser_mouse_chain_reports_failed_index_and_keeps_completed_acti
{"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)
+ with pytest.raises(RuntimeError, match=rf"Action 2 \({kind}\) failed: native failure") as error:
+ await server.browser_actions("browser", actions)
assert error.value.__cause__ is native_error
page.mouse.move.assert_awaited_once_with(10, 20, steps=1)
failing.assert_awaited_once()
@@ -647,7 +662,7 @@ 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",
+ "browser_actions",
{"session_id": "browser", "actions": [{"type": "move", "x": 140, "y": 110, "steps": 4}]},
)
assert not moved.is_error
@@ -666,7 +681,7 @@ 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_mouse",
+ "browser_actions",
{"session_id": "browser", "actions": [{"type": "click", "x": 140, "y": 110, **options}]},
)
assert not result.is_error
@@ -679,7 +694,7 @@ async def test_browser_mouse_live_native_events_and_navigation(session_type: Ses
assert await page.content() == initial_dom
assert requests == ["https://mouse.test/"]
clicked = await client.call_tool(
- "browser_mouse", {"session_id": "browser", "actions": [{"type": "click", "x": 140, "y": 200}]}
+ "browser_actions", {"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)
@@ -710,7 +725,7 @@ async def test_browser_mouse_live_cancelled_click_releases_native_button(
async def click() -> None:
with scope:
- await server.browser_mouse("browser", [{"type": "click", **target, "delay": 60000, "timeout": 0}])
+ await server.browser_actions("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"})
@@ -744,7 +759,7 @@ async def test_browser_mouse_live_cancelled_click_releases_native_button(
await asyncio.wait_for(task, 5)
assert page_info.state == "ready"
moved = await client.call_tool(
- "browser_mouse", {"session_id": "browser", "actions": [{"type": "move", "x": 150, "y": 120}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "move", "x": 150, "y": 120}]}
)
assert not moved.is_error
events = loads(await page.locator("#events").input_value())
@@ -797,7 +812,7 @@ 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(
- "browser_mouse", {"session_id": "browser", "actions": [{"type": tool, **target}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": tool, **target}]}
)
assert not result.is_error
events = loads(await page.locator("#events").input_value())
@@ -815,8 +830,8 @@ 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(RuntimeError, match=rf"Mouse action 1 \({tool}\) failed:") as error:
- await server.browser_mouse(
+ with pytest.raises(RuntimeError, match=rf"Action 1 \({tool}\) failed:") as error:
+ await server.browser_actions(
"browser",
[{"type": tool, "selector": target.get("selector"), "ref": target.get("ref"), "timeout": 100}],
)
@@ -863,7 +878,7 @@ async def test_browser_mouse_click_live_timeout_releases_native_button(session_t
page_info = session.page_pool.pages[0]
page = page_info.page
failed = await client.call_tool(
- "browser_mouse",
+ "browser_actions",
{
"session_id": "browser",
"actions": [{"type": "click", "selector": "#target", "delay": 1000, "timeout": 300}],
@@ -873,7 +888,7 @@ async def test_browser_mouse_click_live_timeout_releases_native_button(session_t
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", {"session_id": "browser", "actions": [{"type": "move", "x": 150, "y": 120}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "move", "x": 150, "y": 120}]}
)
assert not moved.is_error
events = loads(await page.locator("#events").input_value())
diff --git a/tests/ai/test_browser_press_key.py b/tests/ai/test_browser_press_key.py
index d03fac0..46eaa8c 100644
--- a/tests/ai/test_browser_press_key.py
+++ b/tests/ai/test_browser_press_key.py
@@ -48,26 +48,33 @@ def _server(session_type: SessionType = "dynamic") -> tuple[ScraplingMCPServer,
@pytest.mark.asyncio
-async def test_browser_press_key_schema() -> None:
+async def test_browser_actions_keys_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_press_key")
- assert tool.title == "Press keys"
- assert set(tool.input_schema["properties"]) == {"session_id", "keys"}
- assert tool.input_schema["required"] == ["session_id", "keys"]
- keys = tool.input_schema["properties"]["keys"]
- assert keys["type"] == "array" and keys["minItems"] == 1
- assert keys["items"]["type"] == "string" and keys["items"]["minLength"] == 1
+ tool = next(tool for tool in (await client.list_tools()).tools if tool.name == "browser_actions")
+ assert tool.title == "Browser actions"
+ assert set(tool.input_schema["properties"]) == {"session_id", "actions", "slowly"}
+ assert tool.input_schema["required"] == ["session_id", "actions"]
+ actions = tool.input_schema["properties"]["actions"]
+ assert actions["type"] == "array" and actions["minItems"] == 1
+ ref = actions["items"]["discriminator"]["mapping"]["press_key"]
+ key = tool.input_schema["$defs"][ref.rsplit("/", 1)[1]]
+ assert set(key["required"]) == {"type", "key"}
+ assert set(key["properties"]) == {"type", "key"}
+ assert key["properties"]["type"]["const"] == "press_key"
+ assert key["properties"]["key"]["type"] == "string" and key["properties"]["key"]["minLength"] == 1
@pytest.mark.asyncio
@pytest.mark.parametrize("keys", [["Enter"], ["Escape", "Shift+Tab", "ControlOrMeta+A", "+", " ", "Enter", "Enter"]])
-async def test_browser_press_key_forwards_native_keys_in_order(keys: list[str]) -> None:
+async def test_browser_actions_keys_forwards_native_keys_in_order(keys: list[str]) -> None:
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_press_key", {"session_id": "browser", "keys": keys})
+ result = await client.call_tool(
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "press_key", "key": key} for key in keys]}
+ )
assert not result.is_error
assert result.structured_content is None
- assert result.content == [TextContent(type="text", text="Keys pressed.")]
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
assert page.keyboard.press.await_args_list == [call(key) for key in keys]
page.locator.assert_not_called()
page.aria_snapshot.assert_not_called()
@@ -81,19 +88,21 @@ async def test_browser_press_key_forwards_native_keys_in_order(keys: list[str])
[
{},
{"key": "Enter"},
- {"keys": []},
- {"keys": "Enter"},
- {"keys": None},
- {"keys": ["Enter", ""]},
- {"keys": ["Enter", None]},
- {"keys": ["Enter", 42]},
- {"keys": ["Enter", ["Escape"]]},
+ {"actions": []},
+ {"actions": "Enter"},
+ {"actions": None},
+ {"actions": [{"type": "press_key"}]},
+ {"actions": [{"key": "Enter"}]},
+ *[
+ {"actions": [{"type": "press_key", "key": "Enter"}, {"type": "press_key", "key": key}]}
+ for key in ("", None, 42, ["Escape"])
+ ],
],
)
-async def test_browser_press_key_invalid_input_does_not_reserve_page(values: dict[str, Any]) -> None:
+async def test_browser_actions_keys_invalid_input_does_not_reserve_page(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("browser_press_key", {"session_id": "browser", **values})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", **values})
assert result.is_error
page.is_closed.assert_not_called()
page.keyboard.press.assert_not_awaited()
@@ -104,14 +113,16 @@ async def test_browser_press_key_invalid_input_does_not_reserve_page(values: dic
@pytest.mark.parametrize(
"state, message", [("missing", "not found"), ("static", "'static'"), ("empty", "browser_fetch")]
)
-async def test_browser_press_key_session_errors_reach_mcp(state: str, message: str) -> None:
+async def test_browser_actions_keys_session_errors_reach_mcp(state: str, message: str) -> None:
server, session, page = _server("static" if state == "static" else "dynamic")
if state == "missing":
server._sessions.clear()
elif state == "empty":
session.page_pool.clear()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_press_key", {"session_id": "browser", "keys": ["Enter"]})
+ result = await client.call_tool(
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "press_key", "key": "Enter"}]}
+ )
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
assert message in result.content[0].text
@@ -119,23 +130,26 @@ async def test_browser_press_key_session_errors_reach_mcp(state: str, message: s
@pytest.mark.asyncio
-async def test_browser_press_key_error_stops_remaining_keys_and_releases_page() -> None:
+async def test_browser_actions_keys_error_stops_remaining_keys_and_releases_page() -> None:
server, session, page = _server()
page.keyboard.press.side_effect = [None, RuntimeError("key failed")]
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_press_key", {"session_id": "browser", "keys": ["a", "Bad", "Enter"]})
+ result = await client.call_tool(
+ "browser_actions",
+ {"session_id": "browser", "actions": [{"type": "press_key", "key": key} for key in ["a", "Bad", "Enter"]]},
+ )
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
- assert "key failed" in result.content[0].text
+ assert "Action 2 (press_key) failed: key failed" in result.content[0].text
assert page.keyboard.press.await_args_list == [call("a"), call("Bad")]
assert session.page_pool.pages[0].state == "ready"
page.keyboard.press.side_effect = None
- assert await server.browser_press_key("browser", ["Escape"]) == "Keys pressed."
+ assert await server.browser_actions("browser", [{"type": "press_key", "key": "Escape"}]) == "Actions completed."
@pytest.mark.asyncio
@pytest.mark.parametrize("cancel_mode", ["task", "scope"])
-async def test_browser_press_key_reserves_page_until_cancelled(cancel_mode: str) -> None:
+async def test_browser_actions_keys_reserves_page_until_cancelled(cancel_mode: str) -> None:
server, session, page = _server()
entered = asyncio.Event()
scope = CancelScope()
@@ -147,7 +161,9 @@ async def test_browser_press_key_reserves_page_until_cancelled(cancel_mode: str)
async def press() -> None:
with scope:
- await server.browser_press_key("browser", ["a", "Enter", "Escape"])
+ await server.browser_actions(
+ "browser", [{"type": "press_key", "key": key} for key in ["a", "Enter", "Escape"]]
+ )
page.keyboard.press.side_effect = pending
task = asyncio.create_task(press())
@@ -155,7 +171,7 @@ async def test_browser_press_key_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_press_key("browser", ["Enter"])
+ await server.browser_actions("browser", [{"type": "press_key", "key": "Enter"}])
finally:
scope.cancel() if cancel_mode == "scope" else task.cancel()
if cancel_mode == "scope":
@@ -193,41 +209,46 @@ async def _browser(session_type: SessionType) -> AsyncGenerator[tuple[Client, An
@pytest.mark.asyncio
@pytest.mark.parametrize("session_type", ["dynamic", "stealthy"])
-async def test_browser_press_key_live_focus_editing_and_shortcuts(session_type: SessionType) -> None:
+async def test_browser_actions_keys_live_focus_editing_and_shortcuts(session_type: SessionType) -> None:
async with _browser(session_type) as (client, session, page):
- async def press(keys: list[str]) -> None:
- result = await client.call_tool("browser_press_key", {"session_id": "browser", "keys": keys})
+ async def run(actions: list[dict[str, Any]]) -> None:
+ result = await client.call_tool("browser_actions", {"session_id": "browser", "actions": actions})
assert not result.is_error
assert session.page_pool.pages[0].state == "ready"
typed = await client.call_tool(
- "browser_fill_fields",
- {"session_id": "browser", "fields": [{"type": "textbox", "selector": "#first", "value": "initial"}]},
+ "browser_actions",
+ {"session_id": "browser", "actions": [{"type": "textbox", "selector": "#first", "value": "initial"}]},
)
assert not typed.is_error
await page.locator("#events").evaluate("element => element.value = '[]'")
- await press(["Tab", "z", "Shift+Tab"])
+ await run([{"type": "press_key", "key": key} for key in ["Tab", "z", "Shift+Tab"]])
await page.wait_for_function("document.activeElement.id === 'first'", timeout=5000)
assert await page.locator("#second").input_value() == "z"
assert await page.locator("#first").input_value() == "initial"
- await press(["ControlOrMeta+A", "Backspace"])
+ await run([{"type": "press_key", "key": key} for key in ["ControlOrMeta+A", "Backspace"]])
assert await page.locator("#first").input_value() == ""
- await press(["a", " ", "+", "ArrowLeft", "b"])
+ await run([{"type": "press_key", "key": key} for key in ["a", " ", "+", "ArrowLeft", "b"]])
assert await page.locator("#first").input_value() == "a b+"
- await press(["Escape", "Enter"])
+ await run([{"type": "press_key", "key": key} for key in ["Escape", "Enter"]])
await page.wait_for_function("document.querySelector('#escaped').textContent === 'closed'", timeout=5000)
await page.wait_for_function("document.querySelector('#submitted').dataset.count === '1'", timeout=5000)
assert await page.locator("#submitted").inner_text() == "a b+"
invalid = await client.call_tool(
- "browser_press_key", {"session_id": "browser", "keys": ["c", "ScraplingInvalidKey", "x"]}
+ "browser_actions",
+ {
+ "session_id": "browser",
+ "actions": [{"type": "press_key", "key": key} for key in ["c", "ScraplingInvalidKey", "x"]],
+ },
)
assert invalid.is_error
assert invalid.content and isinstance(invalid.content[0], TextContent)
+ assert "Action 2 (press_key) failed:" in invalid.content[0].text
assert "Unknown key" in invalid.content[0].text
assert session.page_pool.pages[0].state == "ready"
assert await page.locator("#first").input_value() == "a bc+"
- await press(["d"])
+ await run([{"type": "press_key", "key": "d"}])
assert await page.locator("#first").input_value() == "a bcd+"
events = loads(await page.locator("#events").input_value())
assert events and all(event["trusted"] for event in events)
diff --git a/tests/ai/test_browser_wait.py b/tests/ai/test_browser_wait.py
index be0a1e7..0d06ae0 100644
--- a/tests/ai/test_browser_wait.py
+++ b/tests/ai/test_browser_wait.py
@@ -33,11 +33,11 @@ def _server(session_type: SessionType = "dynamic") -> tuple[ScraplingMCPServer,
@pytest.mark.asyncio
async def test_browser_wait_schema_and_annotations() -> 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_wait")
- assert tool.title == "Wait"
+ tool = next(tool for tool in (await client.list_tools()).tools if tool.name == "browser_actions")
+ assert tool.title == "Browser actions"
assert tool.input_schema["required"] == ["session_id", "actions"]
properties = tool.input_schema["properties"]
- assert set(properties) == {"session_id", "actions"}
+ assert set(properties) == {"session_id", "actions", "slowly"}
actions = properties["actions"]
assert actions["type"] == "array" and actions["minItems"] == 1
items = actions["items"]
@@ -46,21 +46,37 @@ async def test_browser_wait_schema_and_annotations() -> None:
kind: tool.input_schema["$defs"][ref.rsplit("/", 1)[1]]
for kind, ref in items["discriminator"]["mapping"].items()
}
- assert set(variants) == {"time", "element", "load"}
- assert len(items["oneOf"]) == 3
- assert variants["time"]["required"] == ["type", "milliseconds"]
- assert variants["time"]["properties"]["milliseconds"]["minimum"] == 0
- assert variants["element"]["required"] == ["type", "selector"]
- assert variants["element"]["properties"]["selector"]["minLength"] == 1
- assert set(variants["element"]["properties"]["state"]["enum"]) == {"attached", "detached", "visible", "hidden"}
- assert variants["element"]["properties"]["state"]["default"] == "visible"
- assert variants["load"]["required"] == ["type", "state"]
- assert set(variants["load"]["properties"]["state"]["enum"]) == {"domcontentloaded", "load", "networkidle"}
- for kind in ("element", "load"):
+ assert set(variants) == {
+ "move",
+ "click",
+ "wheel",
+ "wait_time",
+ "wait_element",
+ "wait_load",
+ "textbox",
+ "checkbox",
+ "radio",
+ "combobox",
+ "press_key",
+ }
+ assert len(items["oneOf"]) == 11
+ assert variants["wait_time"]["required"] == ["type", "milliseconds"]
+ assert variants["wait_time"]["properties"]["milliseconds"]["minimum"] == 0
+ assert variants["wait_element"]["required"] == ["type", "selector"]
+ assert variants["wait_element"]["properties"]["selector"]["minLength"] == 1
+ assert set(variants["wait_element"]["properties"]["state"]["enum"]) == {"attached", "detached", "visible", "hidden"}
+ assert variants["wait_element"]["properties"]["state"]["default"] == "visible"
+ assert variants["wait_load"]["required"] == ["type", "state"]
+ assert set(variants["wait_load"]["properties"]["state"]["enum"]) == {"domcontentloaded", "load", "networkidle"}
+ for kind in ("wait_element", "wait_load"):
assert variants[kind]["properties"]["timeout"]["minimum"] == 0
assert variants[kind]["properties"]["timeout"]["default"] == 30000
assert tool.output_schema is None
- assert tool.annotations and tool.annotations.read_only_hint and tool.annotations.open_world_hint
+ 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
@@ -68,12 +84,12 @@ async def test_browser_wait_schema_and_annotations() -> None:
@pytest.mark.parametrize(
"values, method, args, kwargs",
[
- ({"type": "time", "milliseconds": 0}, "wait_for_timeout", (0,), {}),
- ({"type": "time", "milliseconds": 12.5}, "wait_for_timeout", (12.5,), {}),
- ({"type": "element", "selector": "#ready"}, "locator", (), {"state": "visible", "timeout": 30000}),
+ ({"type": "wait_time", "milliseconds": 0}, "wait_for_timeout", (0,), {}),
+ ({"type": "wait_time", "milliseconds": 12.5}, "wait_for_timeout", (12.5,), {}),
+ ({"type": "wait_element", "selector": "#ready"}, "locator", (), {"state": "visible", "timeout": 30000}),
*[
(
- {"type": "element", "selector": "#ready", "state": state, "timeout": 0},
+ {"type": "wait_element", "selector": "#ready", "state": state, "timeout": 0},
"locator",
(),
{"state": state, "timeout": 0},
@@ -81,7 +97,7 @@ async def test_browser_wait_schema_and_annotations() -> None:
for state in ("attached", "detached", "visible", "hidden")
],
*[
- ({"type": "load", "state": state, "timeout": 12.5}, "wait_for_load_state", (state,), {"timeout": 12.5})
+ ({"type": "wait_load", "state": state, "timeout": 12.5}, "wait_for_load_state", (state,), {"timeout": 12.5})
for state in ("domcontentloaded", "load", "networkidle")
],
],
@@ -91,9 +107,9 @@ async def test_browser_wait_forwards_only_requested_wait(
) -> 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("browser_wait", {"session_id": "browser", "actions": [values]})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", "actions": [values]})
assert not result.is_error and result.structured_content is None
- assert result.content == [TextContent(type="text", text="Wait completed.")]
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
for name in ("wait_for_timeout", "wait_for_load_state", "locator"):
action = page.locator.return_value.wait_for if name == "locator" else getattr(page, name)
if name == method:
@@ -127,14 +143,14 @@ async def test_browser_wait_mixed_chain_keeps_order_and_page_reservation() -> No
method.side_effect = assert_reserved
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_wait",
+ "browser_actions",
{
"session_id": "browser",
"actions": [
- {"type": "load", "state": "domcontentloaded"},
- {"type": "element", "selector": "#ready", "timeout": 15},
- {"type": "time", "milliseconds": 2.5},
- {"type": "element", "selector": "#ready", "state": "hidden", "timeout": 0},
+ {"type": "wait_load", "state": "domcontentloaded"},
+ {"type": "wait_element", "selector": "#ready", "timeout": 15},
+ {"type": "wait_time", "milliseconds": 2.5},
+ {"type": "wait_element", "selector": "#ready", "state": "hidden", "timeout": 0},
],
},
)
@@ -161,20 +177,20 @@ async def test_browser_wait_mixed_chain_keeps_order_and_page_reservation() -> No
[{}],
[{"type": "unknown"}],
*[
- [{"type": "time", "milliseconds": 0}, invalid]
+ [{"type": "wait_time", "milliseconds": 0}, invalid]
for invalid in (
- {"type": "time"},
- {"type": "time", "milliseconds": -1},
- {"type": "time", "milliseconds": "NaN"},
- {"type": "time", "milliseconds": "Infinity"},
- {"type": "element"},
- {"type": "element", "selector": ""},
- {"type": "element", "selector": "#ready", "state": "missing"},
- {"type": "load"},
- {"type": "load", "state": "commit"},
- {"type": "load", "state": "load", "timeout": -1},
- {"type": "load", "state": "load", "timeout": "NaN"},
- {"type": "element", "selector": "#ready", "timeout": "Infinity"},
+ {"type": "wait_time"},
+ {"type": "wait_time", "milliseconds": -1},
+ {"type": "wait_time", "milliseconds": "NaN"},
+ {"type": "wait_time", "milliseconds": "Infinity"},
+ {"type": "wait_element"},
+ {"type": "wait_element", "selector": ""},
+ {"type": "wait_element", "selector": "#ready", "state": "missing"},
+ {"type": "wait_load"},
+ {"type": "wait_load", "state": "commit"},
+ {"type": "wait_load", "state": "load", "timeout": -1},
+ {"type": "wait_load", "state": "load", "timeout": "NaN"},
+ {"type": "wait_element", "selector": "#ready", "timeout": "Infinity"},
)
],
],
@@ -182,7 +198,7 @@ async def test_browser_wait_mixed_chain_keeps_order_and_page_reservation() -> No
async def test_browser_wait_invalid_batch_does_not_start_or_reserve_page(actions: 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_wait", {"session_id": "browser", "actions": actions})
+ result = await client.call_tool("browser_actions", {"session_id": "browser", "actions": actions})
assert result.is_error
page.is_closed.assert_not_called()
page.wait_for_timeout.assert_not_awaited()
@@ -196,34 +212,34 @@ async def test_browser_wait_invalid_batch_does_not_start_or_reserve_page(actions
"session_type, error", [("dynamic", PlaywrightTimeoutError), ("stealthy", PatchrightTimeoutError)]
)
@pytest.mark.parametrize(
- "values", [{"type": "element", "selector": "#missing"}, {"type": "load", "state": "networkidle"}]
+ "values", [{"type": "wait_element", "selector": "#missing"}, {"type": "wait_load", "state": "networkidle"}]
)
async def test_browser_wait_native_timeout_reaches_mcp_and_releases_page(
session_type: SessionType, error: type[Exception], values: dict[str, Any]
) -> None:
server, session, page = _server(session_type)
- action = page.locator.return_value.wait_for if values["type"] == "element" else page.wait_for_load_state
+ action = page.locator.return_value.wait_for if values["type"] == "wait_element" else page.wait_for_load_state
action.side_effect = error("wait timed out")
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_wait",
+ "browser_actions",
{
"session_id": "browser",
- "actions": [{"type": "time", "milliseconds": 1}, values, {"type": "time", "milliseconds": 2}],
+ "actions": [{"type": "wait_time", "milliseconds": 1}, values, {"type": "wait_time", "milliseconds": 2}],
},
)
assert result.is_error and isinstance(result.content[0], TextContent)
- assert f"Wait action 2 ({values['type']}) failed: wait timed out" in result.content[0].text
+ assert f"Action 2 ({values['type']}) failed: wait timed out" in result.content[0].text
assert page.wait_for_timeout.await_args_list == [call(1)]
assert session.page_pool.pages[0].state == "ready"
assert not (
await client.call_tool(
- "browser_wait", {"session_id": "browser", "actions": [{"type": "time", "milliseconds": 0}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "wait_time", "milliseconds": 0}]}
)
).is_error
assert action.await_count == 1
- with pytest.raises(RuntimeError, match=r"Wait action 1 .* failed: wait timed out") as failed:
- await server.browser_wait("browser", [values])
+ with pytest.raises(RuntimeError, match=r"Action 1 .* failed: wait timed out") as failed:
+ await server.browser_actions("browser", [values])
assert isinstance(failed.value.__cause__, error)
assert session.page_pool.pages[0].state == "ready"
@@ -251,7 +267,7 @@ async def test_browser_wait_session_errors(state: str, message: str) -> None:
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_wait", {"session_id": "browser", "actions": [{"type": "time", "milliseconds": 0}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "wait_time", "milliseconds": 0}]}
)
assert result.is_error and isinstance(result.content[0], TextContent)
assert message in result.content[0].text
@@ -273,12 +289,12 @@ async def test_browser_wait_reserves_page_until_cancelled(cancel_mode: str) -> N
async def wait() -> None:
with scope:
- await server.browser_wait(
+ await server.browser_actions(
"browser",
[
- {"type": "time", "milliseconds": 1},
- {"type": "load", "state": "networkidle", "timeout": 0},
- {"type": "time", "milliseconds": 2},
+ {"type": "wait_time", "milliseconds": 1},
+ {"type": "wait_load", "state": "networkidle", "timeout": 0},
+ {"type": "wait_time", "milliseconds": 2},
],
)
@@ -288,9 +304,9 @@ async def test_browser_wait_reserves_page_until_cancelled(cancel_mode: str) -> N
await asyncio.wait_for(entered.wait(), 5)
assert session.page_pool.pages[0].state == "busy"
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_wait("browser", [{"type": "time", "milliseconds": 0}])
+ await server.browser_actions("browser", [{"type": "wait_time", "milliseconds": 0}])
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_press_key("browser", ["Enter"])
+ await server.browser_actions("browser", [{"type": "press_key", "key": "Enter"}])
finally:
scope.cancel() if cancel_mode == "scope" else task.cancel()
if cancel_mode == "scope":
@@ -301,7 +317,7 @@ async def test_browser_wait_reserves_page_until_cancelled(cancel_mode: str) -> N
await task
assert session.page_pool.pages[0].state == "ready"
assert page.wait_for_timeout.await_args_list == [call(1)]
- assert await server.browser_wait("browser", [{"type": "time", "milliseconds": 0}]) == "Wait completed."
+ assert await server.browser_actions("browser", [{"type": "wait_time", "milliseconds": 0}]) == "Actions completed."
@asynccontextmanager
@@ -331,7 +347,7 @@ async def test_browser_wait_live_pause_and_element_states(session_type: SessionT
started = monotonic()
assert not (
await client.call_tool(
- "browser_wait", {"session_id": "browser", "actions": [{"type": "time", "milliseconds": 80}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "wait_time", "milliseconds": 80}]}
)
).is_error
assert monotonic() - started >= 0.07
@@ -347,10 +363,10 @@ async def test_browser_wait_live_pause_and_element_states(session_type: SessionT
):
await page.evaluate(f"() => {{ {setup}; setTimeout(() => {{ {change} }}, 80); }}")
result = await client.call_tool(
- "browser_wait",
+ "browser_actions",
{
"session_id": "browser",
- "actions": [{"type": "element", "selector": "#target", "state": state, "timeout": 5000}],
+ "actions": [{"type": "wait_element", "selector": "#target", "state": state, "timeout": 5000}],
},
)
assert not result.is_error
@@ -362,19 +378,19 @@ async def test_browser_wait_live_pause_and_element_states(session_type: SessionT
for state in ("hidden", "detached"):
assert not (
await client.call_tool(
- "browser_wait",
+ "browser_actions",
{
"session_id": "browser",
- "actions": [{"type": "element", "selector": "#absent", "state": state, "timeout": 100}],
+ "actions": [{"type": "wait_element", "selector": "#absent", "state": state, "timeout": 100}],
},
)
).is_error
await page.evaluate("document.body.innerHTML = '<div class=duplicate></div><div class=duplicate></div>'")
result = await client.call_tool(
- "browser_wait",
+ "browser_actions",
{
"session_id": "browser",
- "actions": [{"type": "element", "selector": ".duplicate", "state": "attached", "timeout": 100}],
+ "actions": [{"type": "wait_element", "selector": ".duplicate", "state": "attached", "timeout": 100}],
},
)
assert result.is_error and isinstance(result.content[0], TextContent)
@@ -395,7 +411,7 @@ async def test_browser_wait_live_current_document_load_states(session_type: Sess
async def wait(values: dict[str, Any]) -> Any:
return await client.call_tool(
- "browser_wait", {"session_id": "browser", "actions": [{"type": "load", **values}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "wait_load", **values}]}
)
await page.route("**/pending", blocked)
@@ -451,17 +467,17 @@ async def test_browser_wait_live_load_visible_hidden_chain(session_type: Session
}, 100);
}""")
result = await client.call_tool(
- "browser_wait",
+ "browser_actions",
{
"session_id": "browser",
"actions": [
- {"type": "load", "state": "load", "timeout": 5000},
- {"type": "element", "selector": "#target", "state": "visible", "timeout": 5000},
- {"type": "element", "selector": "#target", "state": "hidden", "timeout": 5000},
+ {"type": "wait_load", "state": "load", "timeout": 5000},
+ {"type": "wait_element", "selector": "#target", "state": "visible", "timeout": 5000},
+ {"type": "wait_element", "selector": "#target", "state": "hidden", "timeout": 5000},
],
},
)
assert not result.is_error
- assert result.content == [TextContent(type="text", text="Wait completed.")]
+ assert result.content == [TextContent(type="text", text="Actions completed.")]
assert await page.locator("#target").is_hidden()
assert session.page_pool.pages[0].state == "ready"
diff --git a/tests/ai/test_browser_wheel.py b/tests/ai/test_browser_wheel.py
index dfe0c38..c66c1a0 100644
--- a/tests/ai/test_browser_wheel.py
+++ b/tests/ai/test_browser_wheel.py
@@ -48,7 +48,7 @@ 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")
+ tool = next(tool for tool in (await client.list_tools()).tools if tool.name == "browser_actions")
schema = tool.input_schema
ref = schema["properties"]["actions"]["items"]["discriminator"]["mapping"]["wheel"]
wheel = schema["$defs"][ref.rsplit("/", 1)[1]]
@@ -67,11 +67,11 @@ async def test_browser_wheel_forwards_deltas_without_moving_or_capturing(values:
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": [{"type": "wheel", **values}]}
+ "browser_actions", {"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="Mouse actions completed.")]
+ assert result.content == [TextContent(type="text", text="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()
@@ -87,7 +87,7 @@ async def test_browser_wheel_invalid_input_does_not_reserve_page(field: str, val
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": [{"type": "wheel", field: value}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "wheel", field: value}]}
)
assert result.is_error
page.is_closed.assert_not_called()
@@ -97,7 +97,7 @@ 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")
+ tool = ScraplingMCPServer()._build_server("127.0.0.1", 8000)._tool_manager.get_tool("browser_actions")
assert tool is not None
for field in ("delta_x", "delta_y"):
with pytest.raises(ValidationError):
@@ -132,7 +132,7 @@ async def test_browser_wheel_session_errors_reach_mcp(state: str, message: str)
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", {"session_id": "browser", "actions": [{"type": "wheel", "delta_y": 120}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "wheel", "delta_y": 120}]}
)
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
@@ -146,15 +146,15 @@ async def test_browser_wheel_error_is_not_retried_and_releases_page() -> None:
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", {"session_id": "browser", "actions": [{"type": "wheel", "delta_y": 120}]}
+ "browser_actions", {"session_id": "browser", "actions": [{"type": "wheel", "delta_y": 120}]}
)
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
- assert "Mouse action 1 (wheel) failed: wheel failed" in result.content[0].text
+ assert "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("browser", [{"type": "wheel", "delta_y": -120}]) == "Mouse actions completed."
+ assert await server.browser_actions("browser", [{"type": "wheel", "delta_y": -120}]) == "Actions completed."
@pytest.mark.asyncio
@@ -170,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("browser", [{"type": "wheel", "delta_y": 120}])
+ await server.browser_actions("browser", [{"type": "wheel", "delta_y": 120}])
page.mouse.wheel.side_effect = pending
task = asyncio.create_task(wheel())
@@ -178,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("browser", [{"type": "wheel", "delta_y": 120}])
+ await server.browser_actions("browser", [{"type": "wheel", "delta_y": 120}])
finally:
scope.cancel() if cancel_mode == "scope" else task.cancel()
if cancel_mode == "scope":
@@ -223,7 +223,7 @@ async def test_browser_wheel_live_scrolls_under_current_pointer(session_type: Se
for target, x, y in (("page", 400, 300), ("panel", 100, 100)):
for dx, dy in ((0, 120), (80, 0), (0, -60), (-40, 0)):
result = await client.call_tool(
- "browser_mouse",
+ "browser_actions",
{
"session_id": "browser",
"actions": ([{"type": "move", "x": x, "y": y}] if (dx, dy) == (0, 120) else [])