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/refactor(mcp)!: Renamed `browser_snapshot` to `browser_extract` while adding more options

Karim shoair890d0c08c1ff
diff --git a/agent-skill/Scrapling-Skill.zip b/agent-skill/Scrapling-Skill.zip
index 2d7d744..d062f33 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 1919130..722cad2 100644
--- a/agent-skill/Scrapling-Skill/references/mcp-server.md
+++ b/agent-skill/Scrapling-Skill/references/mcp-server.md
@@ -2,7 +2,7 @@
The Scrapling MCP server exposes fourteen tools over the MCP protocol. It supports CSS-selector-based content narrowing (reducing tokens by extracting only relevant elements before returning results), plain HTTP requests and stealth browser rendering with anti-bot bypass, persistent browser session management, mouse actions, batch field filling, keyboard shortcuts, page waits, custom JavaScript, network history, and page screenshots returned as real image content blocks. Every fetch takes one URL. One-shot tools (`make_request`, `browser_fetch_once`) close their own client or browser after the call. Use sessions opened with `browser_open` or `open_request_session` for related requests, browser actions, or network history. Browser session calls reuse one tab, so fetch pages and run actions in order. Close each persistent session when done.
-Fetch and HTTP request tools return a `ResponseModel` with fields: `status` (int), `content` (list of strings), `url` (str). The `browser_screenshot` tool returns a list of MCP content blocks: an `ImageContent` (the screenshot bytes) followed by a `TextContent` (the current page URL). `browser_snapshot` and `browser_actions` return plain text. Both network tools return structured JSON; the request list supports pagination. `browser_evaluate` returns compact JSON in one plain text block.
+Fetch and HTTP request tools return a `ResponseModel` with fields: `status` (int), `content` (list of strings), `url` (str). The `browser_screenshot` tool returns a list of MCP content blocks: an `ImageContent` (the screenshot bytes) followed by a `TextContent` (the current page URL). `browser_extract` and `browser_actions` return plain text. Both network tools return structured JSON; the request list supports pagination. `browser_evaluate` returns compact JSON in one plain text block.
## Shadow DOM
@@ -137,21 +137,31 @@ Fetches one URL through a stealthy Chromium session opened with `browser_open`,
With `extraction_type="snapshot"`, the response keeps `status` and `url` and returns one unchanged AI ARIA snapshot string in `content`. These snapshots always include element positions and sizes in viewport CSS pixels. `css_selector` must match exactly one element; omit it for the whole page. `main_content_only` and `pierce_shadow` do not filter snapshots. Snapshot extraction is only available on `browser_fetch`.
-### `browser_snapshot` -- Read the current page without navigation
+### `browser_extract` -- Read current page content without navigation
-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.
+Returns one plain-text block from the current browser page. `extraction_type` defaults to `"snapshot"`; use `"html"`, `"markdown"`, or `"text"` for content extraction after page actions. Call `browser_fetch` first. Unknown or HTTP sessions and missing, closed, or busy pages return an error. The page stays reserved during capture and conversion and is released after success, failure, or cancellation.
-Set `search` to nonempty text for a case-insensitive literal search. Set `regex=true` to treat it as a Python regular expression instead; regex matching is case-sensitive unless you use an inline flag such as `(?i)`. Regex mode requires `search`, and invalid patterns fail before capture. Omit `search` for the unchanged full snapshot.
+Omit `target` for the whole page, or pass a nonempty Playwright selector or `aria-ref=<ref>` from a current snapshot. It must match exactly one element; select a container to read several child items. Selection does not click, scroll, or change the page. Bare ref strings such as `"e2"` are treated as selectors.
-Search applies to each line of the captured snapshot, after the `depth` limit. Results include all matching lines, three lines before and after each match, and parent nodes. Overlapping context appears once; `...` marks omitted lines. Refs and boxes are preserved. If no lines match, the result is an empty string. Search does not navigate or reload the page.
+Snapshots include element roles, names, refs, and viewport bounding boxes by default. Set `boxes=false` to omit boxes or use `depth` to limit the tree. Both settings are ignored for other formats.
+
+Set `search` to a nonempty Python regular expression to search snapshot lines. Matching is case-sensitive; use `(?i)` for case-insensitive matching and escape regex characters when matching them literally. Search requires snapshot output, and invalid patterns fail before capture. There is no `regex` switch. Omit `search` for the full page or target snapshot.
+
+Search runs after target selection and the depth limit. Results include all matching lines, three lines before and after each match, and parent nodes within that snapshot. Overlapping context appears once; `...` marks omitted lines. Refs and boxes are preserved. No matches returns an empty string with no status text.
+
+HTML, Markdown, and text reuse the normal content converter. `main_content_only=true` cleans body/target content for AI; set it to `false` to skip that cleaning. This setting is ignored for snapshots. HTML is parsed output and can include document wrappers around a selected fragment. Serialized HTML does not reflect every live form property or include a host's shadow root or an iframe's document; use snapshots for live control state. Capture does not reload the page or change its forms, focus, or scroll position.
+
+```json
+{"session_id": "browser", "search": "(?i)next|load more"}
+```
```json
-{"session_id": "browser", "search": "Next"}
+{"session_id": "browser", "extraction_type": "markdown", "target": "#results"}
```
### `browser_actions` -- Chain mouse, field, keyboard, dialog, and wait actions
-Runs actions in order on the existing page in a stealthy browser session. Call `browser_fetch` first. The flat `actions` list can mix any of the twelve action types below; use `browser_snapshot` when you need to inspect the page before choosing later actions.
+Runs actions in order on the existing page in a stealthy browser session. Call `browser_fetch` first. The flat `actions` list can mix any of the twelve action types below; use `browser_extract` when you need to inspect the page before choosing later actions.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
@@ -209,7 +219,7 @@ For example, fill and submit a search, wait for its results, then hover over the
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 `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.
+Returns `Actions completed.` as plain text without echoing field values or taking a snapshot. Use `browser_extract` 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.
### `browser_evaluate` -- Run JavaScript on the current page
@@ -238,7 +248,7 @@ Return JSON-compatible data: null, strings, booleans, finite numbers, arrays, or
The result is compact JSON in one `TextContent` block with `structured_output=False`: strings are JSON-quoted, arrays stay in one block, and null is retained. No automatic snapshot, navigation, reload, retry, or tool timeout is added.
-The page stays reserved during evaluation and is released after success, failure, or cancellation. Scripts can change page state or make requests. Errors and cancellation do not undo those effects or guarantee that browser-side JavaScript stops. Use `browser_snapshot` or another read to check effects before repeating a script. Unknown or HTTP sessions and missing, closed, or busy pages return an error; JavaScript errors propagate.
+The page stays reserved during evaluation and is released after success, failure, or cancellation. Scripts can change page state or make requests. Errors and cancellation do not undo those effects or guarantee that browser-side JavaScript stops. Use `browser_extract` or another read to check effects before repeating a script. Unknown or HTTP sessions and missing, closed, or busy pages return an error; JavaScript errors propagate.
### `browser_network_requests` -- Search recorded browser requests
@@ -320,7 +330,7 @@ Call `browser_open`, then `browser_fetch` to open a page first. Use `browser_act
| `quality` | int or null | null | JPEG quality 0-100; an error if supplied for PNG |
| `timeout` | number | 30000 | Finite nonnegative capture timeout in milliseconds; 0 disables it |
-Omit both `selector` and `ref` for the viewport or full-page capture. For an element, pass exactly one target and leave `full_page=false`. Native element capture requires exactly one match, waits for the element to be ready, and may scroll it into view. Refresh stale references with `browser_snapshot`.
+Omit both `selector` and `ref` for the viewport or full-page capture. For an element, pass exactly one target and leave `full_page=false`. Native element capture requires exactly one match, waits for the element to be ready, and may scroll it into view. Refresh stale references with `browser_extract`.
The element image is clipped to its bounding box. A scrollable container includes only its currently visible contents, not all content inside it. Content covered by another element stays covered in the image.
@@ -348,7 +358,7 @@ The page stays reserved during capture and is released after success, failure, o
| Related HTTP requests | `open_request_session` + `session_make_request` per URL |
| Browser automation or network history | `browser_open` + `browser_fetch` per URL |
| Capture the current page or an element | `browser_screenshot` after `browser_open` + `browser_fetch` |
-| Read the current page's AI ARIA snapshot | `browser_snapshot` with `session_id` |
+| Read the current page or one element as a snapshot, HTML, Markdown, or text | `browser_extract` with `session_id` |
| Chain mouse, field, keyboard, or wait actions | `browser_actions` with `session_id` |
| Custom JavaScript extraction or page tasks | `browser_evaluate` with `session_id` |
| Find API calls, HTTP errors, or redirects | `browser_network_requests` with `session_id` |
@@ -443,7 +453,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. The `session_id` you get back is used with `browser_fetch`, `browser_snapshot`, `browser_actions`, `browser_evaluate`, `browser_screenshot`, `browser_network_requests`, and `browser_network_request` 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. The `session_id` you get back is used with `browser_fetch`, `browser_extract`, `browser_actions`, `browser_evaluate`, `browser_screenshot`, `browser_network_requests`, and `browser_network_request` 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 d279576..5410ed5 100644
--- a/docs/ai/mcp-server.md
+++ b/docs/ai/mcp-server.md
@@ -32,9 +32,9 @@ The Scrapling MCP Server provides fourteen tools for web scraping and browser in
- **`browser_screenshot`**: Capture the current page or a chosen element as PNG or JPEG without reloading it. Inspect filled fields, open menus, charts, or result cards, with less unrelated content in element captures. Supports the visible viewport, the full page, or one element, with adjustable JPEG quality. The screenshot is returned as a real image content block the model can see directly.
-#### AI Snapshots
+#### Current Page Content
-- **`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. Search for text to return matching lines with nearby context and parent nodes, making large pages easier to inspect.
+- **`browser_extract`**: Read the current page or one element as an AI snapshot, HTML, Markdown, or text without reloading it. Extract results after filling forms or loading more content. Snapshots include element roles, names, references, positions, and sizes for later actions. Regex search returns matching snapshot lines with nearby context and parent nodes.
#### Browser Actions
@@ -217,7 +217,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.
```
-The `session_id` you get back is used with `browser_fetch`, `browser_snapshot`, `browser_actions`, `browser_evaluate`, `browser_screenshot`, `browser_network_requests`, and `browser_network_request` as usual.
+The `session_id` you get back is used with `browser_fetch`, `browser_extract`, `browser_actions`, `browser_evaluate`, `browser_screenshot`, `browser_network_requests`, and `browser_network_request` 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 3b8419b..4bcdeb0 100644
--- a/docs/api-reference/mcp-server.md
+++ b/docs/api-reference/mcp-server.md
@@ -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, with one response per call. Session management tools use the models below, `browser_screenshot` returns an image of the current page or one element, plus the current page URL, as image and text content blocks, and `browser_snapshot` and `browser_actions` return plain text. Both network tools return structured JSON using the models below. `browser_evaluate` returns its result as JSON in a plain text block.
+The standardized response structure returned by the fetch and HTTP request tools, with one response per call. Session management tools use the models below, `browser_screenshot` returns an image of the current page or one element, plus the current page URL, as image and text content blocks, and `browser_extract` and `browser_actions` return plain text. Both network tools return structured JSON using the models below. `browser_evaluate` returns its result as JSON in a plain text block.
## ::: scrapling.core.ai.server.ResponseModel
handler: python
@@ -77,7 +77,7 @@ The main MCP server class that provides all web scraping tools:
- **`make_request`**: Fetch one URL through HTTP with browser impersonation and automatic client cleanup. Supports GET, POST, PUT, and DELETE.
- **`browser_fetch_once`**: Fetch one URL through a stealthy browser with JavaScript rendering and Cloudflare handling, then close the browser. Use a persistent session for later actions or network history.
-- **`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. Search for text to return matching lines with nearby context and parent nodes, making large pages easier to inspect.
+- **`browser_extract`**: Read the current page or one element as an AI snapshot, HTML, Markdown, or text without reloading it. Keep results from forms and page actions. Snapshots include element roles, names, references, positions, and sizes; regex search returns matching lines with nearby context and parent nodes.
- **`browser_actions`**: Chain mouse moves, hovers, clicks, scrolling, field filling, keyboard shortcuts, dialog replies, and waits in one call. Accept or dismiss alerts and confirmations, or enter text in prompts. 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.
diff --git a/scrapling/core/ai/server.py b/scrapling/core/ai/server.py
index a22bb11..2f68d99 100644
--- a/scrapling/core/ai/server.py
+++ b/scrapling/core/ai/server.py
@@ -24,7 +24,7 @@ from msgspec import ValidationError as MsgspecValidationError
from pydantic import AnyHttpUrl, BaseModel, Field
from patchright.async_api import Error as PatchrightError
-from scrapling import __version__
+from scrapling import Selector, __version__
from scrapling.core.utils import log
from ._browser_actions import (
BrowserAction,
@@ -37,6 +37,7 @@ from ._network_formatting import NetworkPart, NetworkRequestInfo, NetworkRequest
from ._snapshot_search import _search_snapshot
from scrapling.core.shell import Convertor, _CONTROL_CHARS_PATTERN
from scrapling.engines.toolbelt.custom import Response as _ScraplingResponse
+from scrapling.engines.toolbelt.convertor import ResponseFactory
from scrapling.fetchers import FetcherSession, AsyncStealthySession
from scrapling.engines._browsers._types import StealthFetchParams
from scrapling.core._types import (
@@ -426,33 +427,54 @@ class ScraplingMCPServer:
)
return _request_details(record, part)
- async def browser_snapshot(
+ async def browser_extract(
self,
session_id: str,
+ extraction_type: SessionExtractionType = "snapshot",
+ target: Optional[NonEmptyString] = None,
depth: Optional[int] = None,
boxes: bool = True,
search: Optional[NonEmptyString] = None,
- regex: bool = False,
+ main_content_only: bool = True,
) -> str:
- """Return the current page's AI ARIA snapshot or search results as plain text, without navigating.
- Search keeps element refs, ancestor paths, and three lines of context around each matching line.
+ """Read the current page or one element as snapshot, HTML, Markdown, or text without navigating.
+ Return plain text; snapshot search keeps refs, ancestor paths and three lines of nearby context.
:param session_id: ID from `browser_open`; call `browser_fetch` first.
- :param depth: Maximum snapshot depth before search; unlimited if omitted.
- :param boxes: Include element bounding boxes in viewport CSS pixels.
- :param search: Case-insensitive literal text; omitted returns the full snapshot.
- :param regex: Treat search as a Python regex; case-sensitive unless (?i) is used.
+ :param extraction_type: Output format; defaults to an AI ARIA snapshot.
+ :param target: Playwright selector or aria-ref=<ref> matching one element; omitted reads the page.
+ :param depth: Snapshot depth before search; unlimited if omitted. Ignored for other formats.
+ :param boxes: Include viewport bounding boxes in snapshots; ignored for other formats.
+ :param search: Snapshot-only Python regex; case-sensitive unless (?i). No matches returns empty text.
+ :param main_content_only: Clean body/target content for AI; ignored for snapshots.
"""
- if regex and search is None:
- raise ValueError("regex requires search.")
pattern = None
if search is not None:
+ if extraction_type != "snapshot":
+ raise ValueError("search requires snapshot output.")
try:
- pattern = re.compile(search if regex else re.escape(search), 0 if regex else re.IGNORECASE)
+ pattern = re.compile(search)
except re.error as error:
raise ValueError(f"Invalid search regex: {error}") from error
- snapshot = await self._browser_snapshot(session_id, depth=depth, boxes=boxes)
- return _search_snapshot(snapshot, pattern) if pattern is not None else snapshot
+ if extraction_type == "snapshot":
+ snapshot = await self._browser_snapshot(session_id, css_selector=target, depth=depth, boxes=boxes)
+ return _search_snapshot(snapshot, pattern) if pattern is not None else snapshot
+ with self._browser_page(session_id) as (_, page):
+ content = (
+ await page.locator(target).evaluate("(element) => element.outerHTML")
+ if target is not None
+ else await ResponseFactory._get_async_page_content(page)
+ )
+ return _CONTROL_CHARS_PATTERN.sub(
+ "",
+ "".join(
+ Convertor._extract_content(
+ Selector(content=content, url=page.url),
+ extraction_type=extraction_type,
+ main_content_only=main_content_only,
+ )
+ ),
+ )
async def _browser_snapshot(
self,
@@ -906,10 +928,10 @@ class ScraplingMCPServer:
"instructions": """1. Close sessions when done. Use `list_sessions` to check sessions and settings. Read needed network data before closing; closing removes access to its history.
2. Unless the user chooses a tool, start with HTTP for low to mid protection; use browsers for strong protection or JavaScript.
3. Use `make_request` or `browser_fetch_once` for standalone fetches; they close automatically. Use sessions for related requests or follow-up browser actions and network history.
-4. Use `css_selector` to reduce output. HTML/Markdown/text return all matches; snapshots require one match or no selector for the whole page.
+4. Fetch tools use `css_selector` to reduce output. HTML/Markdown/text return all matches; snapshots require one match or no selector for the whole page.
5. Session options persist from opening; fetch options apply per call, with schema defaults.
6. Each browser session uses one page; finish each call before starting the next in that session.
-7. Snapshots include refs and boxes by default; `main_content_only` and `pierce_shadow` do not filter them.
+7. `browser_extract` reads the current page without navigation, as a snapshot by default. Snapshots include refs and boxes; `main_content_only` and `pierce_shadow` do not filter them.
8. `browser_actions` chains mouse, field, key, dialog and wait actions on the current page. Element actions use `target`: a Playwright selector or `aria-ref=<ref>` from the current snapshot. Move/click can instead use viewport (x, y) in CSS pixels. Wheel uses the current pointer without waiting for scrolling; coordinate clicks do not wait for navigation. Load waits observe the current document; wait for a result element for delayed navigation.
9. Network history saves completed requests and responses across page changes. Failed/unfinished requests are omitted; closing does not wait for running captures. Use `include_static=True` to list successful non-API traffic. Limits: 1000 requests and 20 MiB of saved response bodies; oldest records are removed first. Only response bodies with a text Content-Type are read and saved. Response bodies over 1 MiB are skipped; unavailable bodies are marked.""",
}
@@ -974,9 +996,9 @@ class ScraplingMCPServer:
annotations=_FETCH_TOOL_ANNOTATIONS,
)
server.add_tool(
- _mcp_tool(self.browser_snapshot),
- title="Browser page snapshot",
- description=self.browser_snapshot.__doc__,
+ _mcp_tool(self.browser_extract),
+ title="Extract page content",
+ description=self.browser_extract.__doc__,
structured_output=False,
annotations=_FETCH_TOOL_ANNOTATIONS,
)
diff --git a/tests/ai/test_ai_mcp.py b/tests/ai/test_ai_mcp.py
index e79d8b8..1f3926b 100644
--- a/tests/ai/test_ai_mcp.py
+++ b/tests/ai/test_ai_mcp.py
@@ -46,7 +46,7 @@ MCP_TOOLS = {
"browser_fetch",
"browser_actions",
"browser_evaluate",
- "browser_snapshot",
+ "browser_extract",
"browser_screenshot",
"browser_network_requests",
"browser_network_request",
@@ -373,7 +373,7 @@ class TestSessionTypeChecks:
[
("browser_fetch", "static", "'stealthy'"),
("browser_screenshot", "static", "'stealthy'"),
- ("browser_snapshot", "static", "'stealthy'"),
+ ("browser_extract", "static", "'stealthy'"),
("session_make_request", "stealthy", "'static'"),
],
)
@@ -384,7 +384,7 @@ class TestSessionTypeChecks:
session = Mock(_is_alive=True)
server._sessions["test"] = _SessionEntry(session, session_type)
args = {"session_id": "test"}
- if tool not in ("browser_snapshot", "browser_screenshot"):
+ if tool not in ("browser_extract", "browser_screenshot"):
args["url"] = "https://example.com"
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(tool, args)
@@ -1297,7 +1297,7 @@ class TestServerToolRegistration:
assert set(tools) == MCP_TOOLS
assert {"bulk_get", "browser_fetch_many_once"}.isdisjoint(tools)
assert tools["browser_screenshot"].output_schema is None
- assert tools["browser_snapshot"].output_schema is None
+ assert tools["browser_extract"].output_schema is None
assert tools["browser_actions"].output_schema is None
assert tools["browser_evaluate"].output_schema is None
assert {
@@ -1328,7 +1328,7 @@ class TestServerToolRegistration:
if name
not in (
"browser_screenshot",
- "browser_snapshot",
+ "browser_extract",
"browser_actions",
"browser_evaluate",
)
@@ -1463,7 +1463,7 @@ class TestServerToolRegistration:
"browser_fetch_once",
"browser_fetch",
"session_make_request",
- "browser_snapshot",
+ "browser_extract",
"browser_screenshot",
):
assert annotations[name].read_only_hint is True
diff --git a/tests/ai/test_browser_actions.py b/tests/ai/test_browser_actions.py
index 5765aa7..265b8ae 100644
--- a/tests/ai/test_browser_actions.py
+++ b/tests/ai/test_browser_actions.py
@@ -158,7 +158,7 @@ async def test_live_mixed_chain_resolves_targets_created_by_earlier_actions(slow
}, 80);
};
</script>""")
- snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ snapshot = await client.call_tool("browser_extract", {"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
@@ -198,7 +198,7 @@ async def test_live_stale_ref_stops_mixed_chain_without_retargeting(kind: str) -
document.querySelector('#field').outerHTML = '<input id=field value=new>';
};
</script>""")
- snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ snapshot = await client.call_tool("browser_extract", {"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
@@ -231,7 +231,7 @@ async def test_live_targets_keep_explicit_refs_and_ref_shaped_selectors_distinct
await page.set_content("""<e12 role=textbox aria-label=Literal contenteditable=true
style="display:block;width:200px;height:50px"
onmouseenter="this.dataset.hovered='yes'" onclick="this.dataset.clicked='yes'">initial</e12>""")
- snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ snapshot = await client.call_tool("browser_extract", {"session_id": "browser"})
assert not snapshot.is_error and isinstance(snapshot.content[0], TextContent)
ref = search(r'textbox "Literal".*?\[ref=([^\]]+)\]', snapshot.content[0].text)
assert ref is not None
diff --git a/tests/ai/test_browser_evaluate.py b/tests/ai/test_browser_evaluate.py
index 924b7b8..d44d535 100644
--- a/tests/ai/test_browser_evaluate.py
+++ b/tests/ai/test_browser_evaluate.py
@@ -231,7 +231,7 @@ async def test_browser_evaluate_reserves_page_until_cancelled(cancel_mode: str)
with pytest.raises(RuntimeError, match="busy"):
await server.browser_evaluate("browser", "1")
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_snapshot("browser")
+ await server.browser_extract("browser")
scope.cancel() if cancel_mode == "scope" else task.cancel()
if cancel_mode == "scope":
await asyncio.wait_for(task, 5)
diff --git a/tests/ai/test_browser_snapshot.py b/tests/ai/test_browser_extract.py
similarity index 78%
rename from tests/ai/test_browser_snapshot.py
rename to tests/ai/test_browser_extract.py
index 92d82a0..6965f51 100644
--- a/tests/ai/test_browser_snapshot.py
+++ b/tests/ai/test_browser_extract.py
@@ -41,16 +41,33 @@ def _server(session_type: SessionType = "stealthy") -> tuple[ScraplingMCPServer,
@pytest.mark.asyncio
@pytest.mark.parametrize("boxes", [None, False, True])
-async def test_browser_snapshot_returns_plain_mcp_text(boxes: bool | None) -> None:
+async def test_browser_extract_returns_plain_mcp_text(boxes: bool | None) -> None:
server, session, page = _server()
async with Client(server._build_server("127.0.0.1", 8000)) as client:
tools = {tool.name: tool for tool in (await client.list_tools()).tools}
- assert "session_snapshot" not in tools
- tool = tools["browser_snapshot"]
+ assert {"session_snapshot", "browser_snapshot"}.isdisjoint(tools)
+ assert not hasattr(server, "browser_snapshot")
+ tool = tools["browser_extract"]
+ assert tool.title == "Extract page content"
assert tool.output_schema is None
- assert set(tool.input_schema["properties"]) == {"session_id", "depth", "boxes", "search", "regex"}
+ assert set(tool.input_schema["properties"]) == {
+ "session_id",
+ "extraction_type",
+ "target",
+ "depth",
+ "boxes",
+ "search",
+ "main_content_only",
+ }
+ assert tool.input_schema["properties"]["extraction_type"]["default"] == "snapshot"
+ assert set(tool.input_schema["properties"]["extraction_type"]["enum"]) == {
+ "snapshot",
+ "html",
+ "markdown",
+ "text",
+ }
assert tool.input_schema["properties"]["boxes"]["default"] is True
- assert tool.input_schema["properties"]["regex"]["default"] is False
+ assert tool.input_schema["properties"]["main_content_only"]["default"] is True
assert tool.input_schema["properties"]["search"]["default"] is None
assert {"type": "string", "minLength": 1} in tool.input_schema["properties"]["search"]["anyOf"]
assert tool.input_schema["required"] == ["session_id"]
@@ -61,7 +78,7 @@ async def test_browser_snapshot_returns_plain_mcp_text(boxes: bool | None) -> No
args: dict[str, Any] = {"session_id": "browser", "depth": 3}
if boxes is not None:
args["boxes"] = boxes
- result = await client.call_tool("browser_snapshot", args)
+ result = await client.call_tool("browser_extract", args)
assert not result.is_error
assert result.structured_content is None
assert result.content == [TextContent(type="text", text=SNAPSHOT)]
@@ -75,6 +92,37 @@ async def test_browser_snapshot_returns_plain_mcp_text(boxes: bool | None) -> No
page.set_default_navigation_timeout.assert_not_called()
[email protected]("target", ["main", "aria-ref=e2", "e12"])
+async def test_browser_extract_snapshot_target_uses_the_native_locator(target: str) -> None:
+ server, session, page = _server()
+ page.locator.return_value.aria_snapshot = AsyncMock(return_value=SNAPSHOT)
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ result = await client.call_tool(
+ "browser_extract",
+ {"session_id": "browser", "target": target, "depth": 2, "boxes": False, "search": "Save"},
+ )
+ assert not result.is_error
+ assert result.content == [TextContent(type="text", text=SNAPSHOT)]
+ page.locator.assert_called_once_with(target)
+ page.locator.return_value.aria_snapshot.assert_awaited_once_with(mode="ai", depth=2, boxes=False)
+ page.aria_snapshot.assert_not_awaited()
+ page.goto.assert_not_called()
+ assert session.page_pool.pages[0].state == "ready"
+
+
+async def test_browser_extract_rejects_empty_target_before_page_capture() -> None:
+ server, session, page = _server()
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ result = await client.call_tool("browser_extract", {"session_id": "browser", "target": ""})
+ assert result.is_error
+ page.is_closed.assert_not_called()
+ page.locator.assert_not_called()
+ page.aria_snapshot.assert_not_awaited()
+ assert session.page_pool.pages[0].state == "ready"
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize(
"state, message",
@@ -87,7 +135,7 @@ async def test_browser_snapshot_returns_plain_mcp_text(boxes: bool | None) -> No
("closed", "closed"),
],
)
-async def test_browser_snapshot_errors_reach_the_mcp_client(state: str, message: str) -> None:
+async def test_browser_extract_errors_reach_the_mcp_client(state: str, message: str) -> None:
server, session, page = _server("static" if state == "static" else "stealthy")
if state == "missing":
server._sessions.clear()
@@ -100,7 +148,7 @@ async def test_browser_snapshot_errors_reach_the_mcp_client(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_snapshot", {"session_id": "browser"})
+ result = await client.call_tool("browser_extract", {"session_id": "browser"})
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
assert message in result.content[0].text
@@ -112,20 +160,20 @@ async def test_browser_snapshot_errors_reach_the_mcp_client(state: str, message:
@pytest.mark.asyncio
-async def test_browser_snapshot_releases_the_page_after_failure() -> None:
+async def test_browser_extract_releases_the_page_after_failure() -> None:
server, session, page = _server()
page.aria_snapshot.side_effect = PatchrightTimeoutError("snapshot timeout")
with pytest.raises(PatchrightTimeoutError, match="snapshot timeout"):
- await server.browser_snapshot("browser")
+ await server.browser_extract("browser")
assert session.page_pool.pages[0].state == "ready"
page.close.assert_not_called()
page.aria_snapshot.side_effect = None
- assert await server.browser_snapshot("browser") == SNAPSHOT
+ assert await server.browser_extract("browser") == SNAPSHOT
@pytest.mark.asyncio
@pytest.mark.parametrize("css_selector", [None, "main"])
-async def test_browser_snapshot_live_mcp_round_trip(css_selector: str | None) -> None:
+async def test_browser_extract_live_mcp_round_trip(css_selector: str | None) -> None:
server = ScraplingMCPServer(executable_path=getenv("SCRAPLING_EXECUTABLE_PATH"))
requests: list[str] = []
@@ -175,7 +223,7 @@ async def test_browser_snapshot_live_mcp_round_trip(css_selector: str | None) ->
navigations: list[str] = []
page.on("framenavigated", lambda frame: navigations.append(frame.url))
previous_requests = requests.copy()
- result = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ result = await client.call_tool("browser_extract", {"session_id": "browser"})
assert not result.is_error
assert result.structured_content is None
assert len(result.content) == 1 and isinstance(result.content[0], TextContent)
@@ -189,11 +237,22 @@ async def test_browser_snapshot_live_mcp_round_trip(css_selector: str | None) ->
assert match is not None
await page.locator(f"aria-ref={match[1]}").click()
assert await page.locator("output").inner_text() == "live value"
- without_boxes = await client.call_tool("browser_snapshot", {"session_id": "browser", "boxes": False})
+ without_boxes = await client.call_tool("browser_extract", {"session_id": "browser", "boxes": False})
assert not without_boxes.is_error
assert len(without_boxes.content) == 1 and isinstance(without_boxes.content[0], TextContent)
assert "[box=" not in without_boxes.content[0].text
assert "[ref=" in without_boxes.content[0].text
+ for target in ("main", f"aria-ref={match[1]}"):
+ scoped = await client.call_tool("browser_extract", {"session_id": "browser", "target": target})
+ assert not scoped.is_error
+ assert scoped.structured_content is None
+ assert len(scoped.content) == 1 and isinstance(scoped.content[0], TextContent)
+ assert 'button "Save"' in scoped.content[0].text
+ assert "Outside scope" not in scoped.content[0].text
+ assert "[ref=" in scoped.content[0].text and "[box=" in scoped.content[0].text
+ assert requests == previous_requests and not navigations
+ assert await page.get_by_label("Name").input_value() == "live value"
+ assert session.page_pool.pages == [page_info] and page_info.state == "ready"
for selector in ("#missing", "button", "["):
previous_count = len(requests)
failed = await client.call_tool(
@@ -215,7 +274,7 @@ async def test_browser_snapshot_live_mcp_round_trip(css_selector: str | None) ->
@pytest.mark.asyncio
-async def test_browser_snapshot_reserves_and_releases_the_page_on_cancel() -> None:
+async def test_browser_extract_reserves_and_releases_the_page_on_cancel() -> None:
server, session, page = _server()
entered = asyncio.Event()
release = asyncio.Event()
@@ -226,13 +285,13 @@ async def test_browser_snapshot_reserves_and_releases_the_page_on_cancel() -> No
return SNAPSHOT
page.aria_snapshot.side_effect = capture
- task = asyncio.create_task(server.browser_snapshot("browser"))
+ task = asyncio.create_task(server.browser_extract("browser"))
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):
- await server.browser_snapshot("browser")
+ await server.browser_extract("browser")
finally:
task.cancel()
with pytest.raises(asyncio.CancelledError):
@@ -396,32 +455,32 @@ def test_snapshot_search_keeps_all_matches_without_a_result_limit() -> None:
@pytest.mark.asyncio
@pytest.mark.parametrize(
- "snapshot, query, regex, expected",
+ "snapshot, query, expected",
[
- (SNAPSHOT, "save", False, SNAPSHOT),
- (SNAPSHOT, "save", True, ""),
- (SNAPSHOT, "(?i)save", True, SNAPSHOT),
- (SNAPSHOT, '^.*button "S.ve"', True, SNAPSHOT),
- (SNAPSHOT, "/Save/", True, ""),
+ (SNAPSHOT, "save", ""),
+ (SNAPSHOT, "(?i)save", SNAPSHOT),
+ (SNAPSHOT, '^.*button "S.ve"', SNAPSHOT),
+ (SNAPSHOT, "/Save/", ""),
+ (SNAPSHOT, "Save|Cancel", SNAPSHOT),
(
"- text: Price [USD]\n- text: Price USD",
- "[USD]",
- False,
+ r"\[USD\]",
"- text: Price [USD]\n- text: Price USD",
),
- ("- text: C++", "C++", False, "- text: C++"),
- ("- text: Αθήνα", "ΑΘΉΝΑ", False, "- text: Αθήνα"),
- (SNAPSHOT, None, False, SNAPSHOT),
- ('- main:\n - button "Save"\n', None, False, '- main:\n - button "Save"\n'),
+ ("- text: C++", r"C\+\+", "- text: C++"),
+ ("- text: Αθήνα", "ΑΘΉΝΑ", ""),
+ ("- text: Αθήνα", "(?i)ΑΘΉΝΑ", "- text: Αθήνα"),
+ (SNAPSHOT, None, SNAPSHOT),
+ ('- main:\n - button "Save"\n', None, '- main:\n - button "Save"\n'),
],
)
-async def test_browser_snapshot_search_mcp(snapshot: str, query: str | None, regex: bool, expected: str) -> None:
+async def test_browser_extract_search_mcp(snapshot: str, query: str | None, expected: str) -> None:
server, session, page = _server()
page.aria_snapshot.return_value = snapshot
async with Client(server._build_server("127.0.0.1", 8000)) as client:
result = await client.call_tool(
- "browser_snapshot",
- {"session_id": "browser", "search": query, "regex": regex, "depth": 2, "boxes": False},
+ "browser_extract",
+ {"session_id": "browser", "search": query, "depth": 2, "boxes": False},
)
assert not result.is_error
assert result.structured_content is None
@@ -433,16 +492,23 @@ async def test_browser_snapshot_search_mcp(snapshot: str, query: str | None, reg
@pytest.mark.asyncio
@pytest.mark.parametrize(
- "args", [{"regex": True}, {"regex": True, "search": None}, {"regex": True, "search": "["}, {"search": ""}]
+ "args",
+ [
+ {"search": "["},
+ {"search": ""},
+ {"search": "Save", "extraction_type": "html"},
+ {"search": "Save", "extraction_type": "markdown"},
+ {"search": "Save", "extraction_type": "text"},
+ ],
)
-async def test_browser_snapshot_search_rejects_invalid_input_before_page_capture(
+async def test_browser_extract_search_rejects_invalid_input_before_page_capture(
args: dict[str, Any], monkeypatch: pytest.MonkeyPatch
) -> None:
server, session, page = _server()
reserve = Mock(wraps=session.page_pool.get_ready_page)
monkeypatch.setattr(type(session.page_pool), "get_ready_page", reserve)
async with Client(server._build_server("127.0.0.1", 8000)) as client:
- result = await client.call_tool("browser_snapshot", {"session_id": "browser", **args})
+ result = await client.call_tool("browser_extract", {"session_id": "browser", **args})
assert result.is_error
assert result.content and isinstance(result.content[0], TextContent)
assert "search" in result.content[0].text.lower() or "regular expression" in result.content[0].text.lower()
@@ -452,17 +518,17 @@ async def test_browser_snapshot_search_rejects_invalid_input_before_page_capture
@pytest.mark.asyncio
[email protected]("kwargs", [{"regex": True}, {"search": "[", "regex": True}])
-async def test_browser_snapshot_search_errors_are_value_errors(kwargs: dict[str, Any]) -> None:
[email protected]("kwargs", [{"search": "["}, {"search": "Save", "extraction_type": "html"}])
+async def test_browser_extract_search_errors_are_value_errors(kwargs: dict[str, Any]) -> None:
server, session, page = _server()
with pytest.raises(ValueError):
- await server.browser_snapshot("browser", **kwargs)
+ await server.browser_extract("browser", **kwargs)
page.aria_snapshot.assert_not_awaited()
assert session.page_pool.pages[0].state == "ready"
@pytest.mark.asyncio
-async def test_browser_snapshot_search_live_refs_and_state() -> None:
+async def test_browser_extract_search_live_refs_and_state() -> None:
server = ScraplingMCPServer(executable_path=getenv("SCRAPLING_EXECUTABLE_PATH"))
requests: list[str] = []
html = (
@@ -500,7 +566,7 @@ async def test_browser_snapshot_search_live_refs_and_state() -> None:
navigations: list[str] = []
page.on("framenavigated", lambda frame: navigations.append(frame.url))
await page.evaluate("window.snapshotSearchState = 'retained'")
- result = await client.call_tool("browser_snapshot", {"session_id": "browser", "search": "save RESULT"})
+ result = await client.call_tool("browser_extract", {"session_id": "browser", "search": "(?i)save RESULT"})
assert not result.is_error and isinstance(result.content[0], TextContent)
snapshot = result.content[0].text
assert snapshot.startswith('- main "Results"')
@@ -518,15 +584,15 @@ async def test_browser_snapshot_search_live_refs_and_state() -> None:
assert not clicked.is_error
assert await page.locator("output").inner_text() == "Saved"
without_boxes = await client.call_tool(
- "browser_snapshot",
- {"session_id": "browser", "search": '^ +-[ ]button "Save result"', "regex": True, "boxes": False},
+ "browser_extract",
+ {"session_id": "browser", "search": '^ +-[ ]button "Save result"', "boxes": False},
)
assert not without_boxes.is_error and isinstance(without_boxes.content[0], TextContent)
assert without_boxes.content[0].text.startswith('- main "Results"')
assert "[box=" not in without_boxes.content[0].text
assert "[ref=" in without_boxes.content[0].text
shallow = await client.call_tool(
- "browser_snapshot", {"session_id": "browser", "search": "Save result", "depth": 1}
+ "browser_extract", {"session_id": "browser", "search": "Save result", "depth": 1}
)
assert not shallow.is_error
assert shallow.content == [TextContent(type="text", text="")]
diff --git a/tests/ai/test_browser_extract_content.py b/tests/ai/test_browser_extract_content.py
new file mode 100644
index 0000000..0ee78b3
--- /dev/null
+++ b/tests/ai/test_browser_extract_content.py
@@ -0,0 +1,353 @@
+import asyncio
+from contextlib import suppress
+from re import search
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from anyio import CancelScope
+from mcp.client import Client
+from mcp.types import TextContent
+from patchright.async_api import Error as PatchrightError
+
+from scrapling.core.ai import ScraplingMCPServer, SessionType
+from scrapling.core.ai.server import _SessionEntry
+from scrapling.core._types import Any, Literal
+from scrapling.engines._browsers._base import AsyncSession
+from tests.ai.test_browser_wait import _browser
+
+
+HTML = """<!DOCTYPE html><html><head><title>Head title</title></head><body>
+<main><h1>Café مرحبا</h1><p>A &amp; B <a href="/more">More</a></p>
+<p style="display:none">Hidden text</p><script>window.secret = 'Script text';</script></main>
+<p>Outside text</p></body></html>"""
+
+
+def _server(session_type: SessionType = "stealthy") -> tuple[ScraplingMCPServer, AsyncSession, Mock]:
+ server = ScraplingMCPServer()
+ session = AsyncSession()
+ session._is_alive = True
+ page = Mock()
+ page.url = "https://extract.test/"
+ page.is_closed.return_value = False
+ page.content = AsyncMock(return_value=HTML)
+ page.wait_for_timeout = AsyncMock()
+ page.locator.return_value.evaluate = AsyncMock(return_value='<h1 id="title">Café مرحبا</h1>')
+ session.page_pool.add_page(page).mark_ready()
+ server._sessions["browser"] = _SessionEntry(session, session_type)
+ return server, session, page
+
+
+async def _extract(client: Client, **options: Any) -> str:
+ result = await client.call_tool("browser_extract", {"session_id": "browser", **options})
+ assert not result.is_error, result.content
+ assert result.structured_content is None
+ assert len(result.content) == 1 and isinstance(result.content[0], TextContent)
+ return result.content[0].text
+
+
[email protected]("kind", ["html", "markdown", "text"])
[email protected]("main_content_only", [False, True])
+async def test_browser_extract_content_formats_and_cleaning(
+ kind: Literal["html", "markdown", "text"], main_content_only: bool
+) -> None:
+ server, session, page = _server()
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ text = await _extract(client, extraction_type=kind, main_content_only=main_content_only, depth=1, boxes=False)
+ assert "Café مرحبا" in text and "Outside text" in text
+ assert ("Hidden text" in text) is not main_content_only
+ assert ("Head title" in text) is not main_content_only
+ if kind == "html":
+ assert "<h1>Café مرحبا</h1>" in text and '<a href="/more">More</a>' in text
+ assert "A &amp; B" in text
+ assert ("<script>" in text) is not main_content_only
+ elif kind == "markdown":
+ assert "[More](/more)" in text and "A & B" in text and "<h1>" not in text
+ else:
+ assert "A & B" in text and "More" in text and "<" not in text and "Script text" not in text
+ page.content.assert_awaited_once_with()
+ for method in ("locator", "goto", "reload", "evaluate", "aria_snapshot", "set_default_timeout"):
+ getattr(page, method).assert_not_called()
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("kind", ["html", "markdown", "text"])
[email protected]("target", ["#title", "xpath=//h1", "aria-ref=e2"])
+async def test_browser_extract_content_target_is_native_and_strict(kind: str, target: str) -> None:
+ server, session, page = _server()
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ text = await _extract(client, extraction_type=kind, target=target)
+ assert "Café مرحبا" in text and "Outside text" not in text
+ page.locator.assert_called_once_with(target)
+ page.locator.return_value.evaluate.assert_awaited_once_with("(element) => element.outerHTML")
+ page.locator.return_value.first.evaluate.assert_not_called()
+ page.content.assert_not_awaited()
+ page.goto.assert_not_called()
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("kind", ["html", "markdown", "text"])
[email protected]("main_content_only", [False, True])
+async def test_browser_extract_content_strips_control_characters(kind: str, main_content_only: bool) -> None:
+ server, _, page = _server()
+ page.content.return_value = "<html><body><p>Café\x01مرحبا\x08世界\x1f</p></body></html>"
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ text = await _extract(client, extraction_type=kind, main_content_only=main_content_only)
+ assert "Caféمرحبا世界" in text
+ assert all(character not in text for character in ("\x01", "\x08", "\x1f"))
+
+
[email protected]("kind", ["markdown", "text"])
[email protected]("target", [None, "#empty"])
+async def test_browser_extract_content_empty_result_is_empty_text(kind: str, target: str | None) -> None:
+ server, _, page = _server()
+ page.content.return_value = '<html><body><p id="empty"></p></body></html>'
+ page.locator.return_value.evaluate.return_value = '<p id="empty"></p>'
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ assert await _extract(client, extraction_type=kind, target=target) == ""
+
+
+ "options",
+ [
+ {"extraction_type": "json"},
+ {"target": ""},
+ {"target": 123},
+ *[{"extraction_type": kind, "search": ".*"} for kind in ("html", "markdown", "text")],
+ ],
+)
+async def test_browser_extract_content_invalid_options_do_not_reserve_page(options: 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_extract", {"session_id": "browser", **options})
+ assert result.is_error
+ page.is_closed.assert_not_called()
+ page.content.assert_not_awaited()
+ page.locator.assert_not_called()
+ assert session.page_pool.pages[0].state == "ready"
+
+
+async def test_browser_extract_content_uses_existing_page_content_retry() -> None:
+ server, session, page = _server()
+ page.content.side_effect = [PatchrightError("Document is changing"), HTML]
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ assert "Café مرحبا" in await _extract(client, extraction_type="text")
+ assert page.content.await_count == 2
+ page.wait_for_timeout.assert_awaited_once_with(500)
+ assert session.page_pool.pages[0].state == "ready"
+
+
[email protected]("closed", [False, True])
+async def test_browser_extract_content_target_failure_releases_page(closed: bool) -> None:
+ server, session, page = _server()
+
+ async def fail(*args: Any, **kwargs: Any) -> None:
+ page.is_closed.return_value = closed
+ raise PatchrightError("Target detached")
+
+ page.locator.return_value.evaluate.side_effect = fail
+ async with Client(server._build_server("127.0.0.1", 8000)) as client:
+ result = await client.call_tool(
+ "browser_extract", {"session_id": "browser", "extraction_type": "html", "target": "#title"}
+ )
+ assert result.is_error and isinstance(result.content[0], TextContent)
+ assert "Target detached" in result.content[0].text
+ page.locator.return_value.evaluate.assert_awaited_once()
+ page.content.assert_not_awaited()
+ page.close.assert_not_called()
+ assert session.page_pool.pages_count == (0 if closed else 1)
+ if not closed:
+ assert session.page_pool.pages[0].state == "ready"
+
+
+ "state, message",
+ [
+ ("missing", "not found"),
+ ("dead", "no longer alive"),
+ ("static", "'stealthy'"),
+ ("empty", "browser_fetch"),
+ ("busy", "busy"),
+ ("closed", "closed"),
+ ],
+)
+async def test_browser_extract_content_session_errors(state: str, message: str) -> None:
+ server, session, page = _server("static" if state == "static" else "stealthy")
+ if state == "missing":
+ server._sessions.clear()
+ elif state == "dead":
+ session._is_alive = False
+ elif state == "empty":
+ session.page_pool.clear()
+ elif state == "busy":
+ session.page_pool.pages[0].mark_busy()
+ 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_extract", {"session_id": "browser", "extraction_type": "html"})
+ assert result.is_error and isinstance(result.content[0], TextContent)
+ assert message in result.content[0].text
+ page.content.assert_not_awaited()
+ page.locator.assert_not_called()
+ if state == "closed":
+ assert session.page_pool.pages_count == 0
+ elif state == "busy":
+ assert session.page_pool.pages[0].state == "busy"
+
+
[email protected]("target", [None, "#title"])
[email protected]("cancel_mode", ["task", "scope"])
+async def test_browser_extract_content_cancellation_releases_page(target: str | None, cancel_mode: str) -> None:
+ server, session, page = _server()
+ entered = asyncio.Event()
+ scope = CancelScope()
+
+ async def pending(*args: Any, **kwargs: Any) -> str:
+ entered.set()
+ await asyncio.Event().wait()
+ return ""
+
+ async def extract() -> None:
+ with scope:
+ await server.browser_extract("browser", extraction_type="html", target=target)
+
+ capture = page.locator.return_value.evaluate if target else page.content
+ capture.side_effect = pending
+ task = asyncio.create_task(extract())
+ try:
+ await asyncio.wait_for(entered.wait(), 5)
+ assert session.page_pool.pages[0].state == "busy"
+ with pytest.raises(RuntimeError, match="busy"):
+ await server.browser_extract("browser")
+ scope.cancel() if cancel_mode == "scope" else task.cancel()
+ if cancel_mode == "scope":
+ await asyncio.wait_for(task, 5)
+ assert scope.cancelled_caught
+ else:
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ finally:
+ if not task.done():
+ task.cancel()
+ with suppress(asyncio.CancelledError):
+ await task
+ capture.assert_awaited_once()
+ assert session.page_pool.pages[0].state == "ready"
+ page.close.assert_not_called()
+
+
+async def test_browser_extract_content_live_formats_preserve_current_page() -> None:
+ async with _browser() as (client, session, page):
+ await page.set_content("""<!DOCTYPE html><html><head><title>Head title</title></head><body>
+ <main><h1>Café مرحبا</h1><input id=name value=initial><input id=agree type=checkbox>
+ <button id=save onclick="document.querySelector('output').textContent = document.querySelector('#name').value">Save</button>
+ <output>Before click</output><p><a href="/more">More</a></p>
+ <p style="display:none">Hidden text</p><script>window.secret = 'Script text';</script></main>
+ <p>Outside text</p><div style="height: 3000px"></div></body></html>""")
+ result = await client.call_tool(
+ "browser_actions",
+ {
+ "session_id": "browser",
+ "actions": [
+ {"type": "textbox", "target": "#name", "value": "نتائج جديدة 🌍"},
+ {"type": "checkbox", "target": "#agree", "value": True},
+ {"type": "click", "target": "#save"},
+ ],
+ },
+ )
+ assert not result.is_error
+ await page.locator("#name").focus()
+ await page.evaluate("window.scrollTo(0, 500)")
+ state_expression = """() => ({
+ html: document.documentElement.outerHTML,
+ value: document.querySelector('#name').value,
+ checked: document.querySelector('#agree').checked,
+ focus: document.activeElement.id,
+ scroll: window.scrollY,
+ url: location.href
+ })"""
+ before = await page.evaluate(state_expression)
+ page_info = session.page_pool.pages[0]
+ navigations: list[str] = []
+ requests: list[str] = []
+ page.on("framenavigated", lambda frame: navigations.append(frame.url))
+ page.on("request", lambda request: requests.append(request.url))
+ for kind in ("html", "markdown", "text"):
+ for clean in (False, True):
+ text = await _extract(client, extraction_type=kind, main_content_only=clean)
+ assert "نتائج جديدة 🌍" in text and "Café مرحبا" in text and "Outside text" in text
+ assert ("Hidden text" in text) is not clean
+ assert ("Head title" in text) is not clean
+ if kind == "html":
+ assert "<output>نتائج جديدة 🌍</output>" in text
+ assert ("<script>" in text) is not clean
+ elif kind == "markdown":
+ assert "[More](/more)" in text and "<output>" not in text
+ else:
+ assert "<output>" not in text and "Script text" not in text
+ assert await page.evaluate(state_expression) == before
+ assert session.page_pool.pages == [page_info] and page_info.state == "ready"
+ assert before["value"] == "نتائج جديدة 🌍" and before["checked"] and before["focus"] == "name"
+ assert before["scroll"] == 500 and not navigations and not requests
+
+
+async def test_browser_extract_content_live_selectors_refs_and_snapshot_scope() -> None:
+ async with _browser() as (client, session, page):
+ await page.set_content("""<html><body>
+ <main aria-label="Products"><h1>Café مرحبا</h1><button>Buy now</button>
+ <p style="display:none">Hidden text</p></main><h2>Outside heading</h2><button>Outside button</button>
+ </body></html>""")
+ snapshot = await _extract(client, target="main", search="(?i)buy", boxes=False)
+ assert 'button "Buy now"' in snapshot and "Outside" not in snapshot
+ assert "[box=" not in snapshot
+ ref = search(r'button "Buy now".*?\[ref=([^\]]+)\]', snapshot)
+ assert ref is not None
+ for target in ("main", "xpath=//main", 'role=main[name="Products"]'):
+ for kind in ("html", "markdown", "text"):
+ text = await _extract(client, extraction_type=kind, target=target)
+ assert "Café مرحبا" in text and "Buy now" in text
+ assert "Outside" not in text and "Hidden text" not in text
+ for kind in ("html", "markdown", "text"):
+ text = await _extract(client, extraction_type=kind, target=f"aria-ref={ref[1]}")
+ assert "Buy now" in text and "Café" not in text and "Outside" not in text
+ button_snapshot = await _extract(client, target=f"aria-ref={ref[1]}")
+ assert 'button "Buy now"' in button_snapshot and "[box=" in button_snapshot
+ assert "Café" not in button_snapshot and "Outside" not in button_snapshot
+ assert await _extract(client, target="main", search="(?i)absent") == ""
+ assert session.page_pool.pages[0].state == "ready"
+
+
+async def test_browser_extract_content_live_target_errors_allow_next_call() -> None:
+ async with _browser() as (client, session, page):
+ await page.set_content("<main><button id=old>Old button</button><button>Keep button</button></main>")
+ page.set_default_timeout(100)
+ snapshot = await _extract(client)
+ ref = search(r'button "Old button".*?\[ref=([^\]]+)\]', snapshot)
+ assert ref is not None
+ await page.locator("#old").evaluate("element => element.remove()")
+ for target, error in (
+ ("#missing", "Timeout"),
+ ("main, button", "strict mode violation"),
+ ("[", "selector"),
+ (f"aria-ref={ref[1]}", "ref"),
+ ):
+ for kind in ("snapshot", "html", "markdown", "text"):
+ result = await client.call_tool(
+ "browser_extract", {"session_id": "browser", "extraction_type": kind, "target": target}
+ )
+ assert result.is_error and isinstance(result.content[0], TextContent)
+ expected = "does not match any element" if kind == "snapshot" and target == "#missing" else error
+ assert expected.lower() in result.content[0].text.lower(), result.content
+ assert session.page_pool.pages[0].state == "ready"
+ assert await _extract(client, extraction_type="text", target="button") == "Keep button"
diff --git a/tests/ai/test_browser_fill_fields.py b/tests/ai/test_browser_fill_fields.py
index 001f180..14e1f50 100644
--- a/tests/ai/test_browser_fill_fields.py
+++ b/tests/ai/test_browser_fill_fields.py
@@ -513,7 +513,7 @@ async def _browser() -> AsyncGenerator[tuple[Client, Any, Any], None]:
@pytest.mark.asyncio
async def test_browser_actions_fields_live_mixed_fields_and_clearing() -> None:
async with _browser() as (client, session, page):
- snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ snapshot = await client.call_tool("browser_extract", {"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)
@@ -583,7 +583,7 @@ async def test_browser_actions_fields_live_mixed_fields_and_clearing() -> None:
@pytest.mark.asyncio
async def test_browser_actions_fields_live_slow_typing_and_field_delays() -> None:
async with _browser() as (client, session, page):
- snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ snapshot = await client.call_tool("browser_extract", {"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)
@@ -638,7 +638,7 @@ async def test_browser_actions_fields_live_slow_typing_and_field_delays() -> Non
@pytest.mark.parametrize("slowly", [False, True])
async def test_browser_actions_fields_live_caret_selection_and_submit(slowly: bool) -> None:
async with _browser() as (client, session, page):
- snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ snapshot = await client.call_tool("browser_extract", {"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)
diff --git a/tests/ai/test_browser_mouse.py b/tests/ai/test_browser_mouse.py
index 31a0c40..25e4176 100644
--- a/tests/ai/test_browser_mouse.py
+++ b/tests/ai/test_browser_mouse.py
@@ -391,7 +391,7 @@ async def test_browser_mouse_reserves_page_until_cancelled(target: dict[str, Any
with pytest.raises(RuntimeError, match="busy"):
await server.browser_actions("browser", [{"type": "click", "x": 10, "y": 20}])
with pytest.raises(RuntimeError, match="busy"):
- await server.browser_snapshot("browser")
+ await server.browser_extract("browser")
finally:
task.cancel()
with pytest.raises(asyncio.CancelledError):
@@ -697,7 +697,7 @@ async def test_browser_mouse_live_native_events_and_navigation() -> None:
)
assert not clicked.is_error
await page.wait_for_url("https://mouse.test/next", timeout=5000)
- snapshot = await client.call_tool("browser_snapshot", {"session_id": "browser"})
+ snapshot = await client.call_tool("browser_extract", {"session_id": "browser"})
assert not snapshot.is_error
assert snapshot.content and isinstance(snapshot.content[0], TextContent)
assert "Arrived" in snapshot.content[0].text
@@ -737,7 +737,7 @@ async def test_browser_mouse_live_cancelled_click_releases_native_button(cancel_
page_info = session.page_pool.pages[0]
page = page_info.page
if target_type == "ref":
- match = search(r'button "Target".*?\[ref=([^\]]+)\]', await server.browser_snapshot("browser"))
+ match = search(r'button "Target".*?\[ref=([^\]]+)\]', await server.browser_extract("browser"))
assert match is not None
target = {"target": f"aria-ref={match[1]}"}
task = asyncio.create_task(click())
@@ -794,7 +794,7 @@ async def test_browser_mouse_live_selectors_refs_and_scroll(tool: str) -> None:
assert not fetched.is_error
page_info = session.page_pool.pages[0]
page = page_info.page
- match = search(r'button "Target".*?\[ref=([^\]]+)\]', await server.browser_snapshot("browser"))
+ match = search(r'button "Target".*?\[ref=([^\]]+)\]', await server.browser_extract("browser"))
assert match is not None
ref = match[1]
initial_dom = await page.content()
diff --git a/tests/ai/test_browser_screenshot.py b/tests/ai/test_browser_screenshot.py
index ab3c2d3..8abd249 100644
--- a/tests/ai/test_browser_screenshot.py
+++ b/tests/ai/test_browser_screenshot.py
@@ -508,7 +508,7 @@ async def test_browser_screenshot_live_preserves_actions_and_current_page() -> N
assert requests == initial_requests
assert session.page_pool.pages == [page_info] and page_info.state == "ready"
assert dimensions[1][1] > dimensions[0][1]
- snapshot = await server.browser_snapshot("browser")
+ snapshot = await server.browser_extract("browser")
ref = search(r'button "Open menu".*?\[ref=([^\]]+)\]', snapshot)
assert ref is not None
for target in ({"selector": "#toggle"}, {"ref": ref[1]}):