SwiftBrowse v0.1.2 GitHub

Operations

Every operation SwiftBrowse can perform. This page is generated from the engine's own schemas (swiftbrowse sdk --schema, version 0.1.2), so it matches the binary exactly.

The same operation has the same name and arguments everywhere:

  • Test files and run scripts: a step { "op": "fill", "target": "Email", "value": "ada@example.com" }. Test files also have expect.
  • MCP: a tool named after the operation, with the arguments as its input.
  • TypeScript SDK: page.fill('Email', 'ada@example.com', { timeout_ms: 2000 }), a camelCase method, with required arguments in order and the rest in an options object.
  • Python SDK: page.fill("Email", "ada@example.com", timeout_ms=2000), with required arguments positionally and the rest by keyword.

A target is a string or a locator object: see Targets and locators. A condition is described in Assertions. Every operation returns an ActionResult.

Open a URL, wait for the requested load state and report the HTTP status.

Argument Type Description
url (required) string
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).
wait_until "dom_content_loaded" | "load" | "network_idle" Default: "load".

TypeScript: page.navigate(url, { …options }) · Python: page.navigate(url, **options)

go_back

Go back one history entry and wait for the page to load.

Argument Type Description
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.goBack({ …options }) · Python: page.go_back(**options)

go_forward

Go forward one history entry and wait for the page to load.

Argument Type Description
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.goForward({ …options }) · Python: page.go_forward(**options)

reload

Reload the page and wait for it to load.

Argument Type Description
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.reload({ …options }) · Python: page.reload(**options)

Reading the page

get_page_snapshot

Compact structured view of the page: URL, title, headings, visible interactive elements with ref handles, dialogs, alerts and validation messages. Use since_last to get only changes.

Argument Type Description
format "text" | "json" Default: "text".
max_elements integer
mode "compact" | "full" Default: "compact".
since_last boolean Return only what changed since this session's previous snapshot. Default: false.

TypeScript: page.getPageSnapshot({ …options }) · Python: page.get_page_snapshot(**options)

get_accessibility_tree

Bounded accessibility tree (role, name, value) from the browser.

Argument Type Description
max_nodes integer

TypeScript: page.getAccessibilityTree({ …options }) · Python: page.get_accessibility_tree(**options)

find_element

Resolve a locator. Fails with ambiguous when several elements match and no nth is given.

Argument Type Description
target (required) target A string or a locator: see Targets and locators.
all boolean Return every match instead of requiring a unique one. Default: false.

TypeScript: page.findElement(target, { …options }) · Python: page.find_element(target, **options)

get_screenshot

Save a PNG screenshot to the evidence directory and return its path.

Argument Type Description
format ImageFormat Default: "png".
full_page boolean Default: false.
name string File name stem inside the evidence directory; path separators are rejected.

TypeScript: page.getScreenshot({ …options }) · Python: page.get_screenshot(**options)

get_dom_snapshot

A self-contained, script-free HTML copy of the page (form state, shadow roots, live CSS) for trace viewers. Large; prefer get_page_snapshot to read a page.

Argument Type Description
mark string Mark this element (a ref) with data-sb-target in the snapshot.

TypeScript: page.getDomSnapshot({ …options }) · Python: page.get_dom_snapshot(**options)

Actions

click

Click an element after checking it is visible, enabled and not covered. Pass expect to verify the outcome. Consequential actions (buy, pay, delete, ...) need approved=true.

Argument Type Description
target (required) target A string or a locator: see Targets and locators.
approved boolean Set after a human approved a consequential action. Default: false.
consequential boolean Override the policy's consequential-action detection.
expect condition See Assertions.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.click(target, { …options }) · Python: page.click(target, **options)

hover

Move the mouse over an element after checking it is visible and not covered. Pass expect to verify what appears.

Argument Type Description
target (required) target A string or a locator: see Targets and locators.
expect condition See Assertions.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.hover(target, { …options }) · Python: page.hover(target, **options)

check

Leave a checkbox, radio or aria-checked element checked (or unchecked with checked=false), clicking only if needed, and verify the state.

Argument Type Description
target (required) target A string or a locator: see Targets and locators.
checked boolean The state to leave it in. Default true; false unchecks. Default: true.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.check(target, { …options }) · Python: page.check(target, **options)

fill

Replace a field's value and verify the resulting value.

Argument Type Description
target (required) target A string or a locator: see Targets and locators.
value (required) string
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.fill(target, value, { …options }) · Python: page.fill(target, value, **options)

type_text

Type text key by key into the target or focused element.

Argument Type Description
text (required) string
target target A string or a locator: see Targets and locators.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.typeText(text, { …options }) · Python: page.type_text(text, **options)

press_key

Press a key or chord, optionally on a target and with an expected outcome.

Argument Type Description
key (required) string Key name such as Enter, Tab, Escape, ArrowDown, a, or a chord like Control+a.
expect condition See Assertions.
target target A string or a locator: see Targets and locators.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.pressKey(key, { …options }) · Python: page.press_key(key, **options)

select_option

Choose an option of a and verify the selection. Only files inside directories the policy allows.

Argument Type Description
target (required) target A string or a locator: see Targets and locators.
files (required) string[] Files to select; an empty list clears the selection. Must lie in a directory the policy allows for uploads.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.uploadFile(target, files, { …options }) · Python: page.upload_file(target, files, **options)

evaluate

Run a JavaScript expression in the page and return its JSON result. Only available when the session policy allows scripts (the test runner does; MCP needs --allow-evaluate).

Argument Type Description
expression (required) string JavaScript expression evaluated in the page; promises are awaited and the JSON-serializable result is returned. Disabled unless the policy allows it.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.evaluate(expression, { …options }) · Python: page.evaluate(expression, **options)

Waiting and assertions

wait_for

Wait until a condition holds or the timeout expires.

Argument Type Description
condition (required) condition See Assertions.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).

TypeScript: page.waitFor(condition, { …options }) · Python: page.wait_for(condition, **options)

assert_page_state

Check URL, title, element, text, value or diagnostics conditions. Recorded in the test report.

Argument Type Description
conditions (required) condition[] Every condition must hold: see Assertions.
name string Label recorded in the test report.
timeout_ms integer Wait up to this long for all conditions to hold. Default 0: check once.

TypeScript: page.assertPageState(conditions, { …options }) · Python: page.assert_page_state(conditions, **options)

Network

route

Mock the network: requests matching a URL glob or regex (and method) are fulfilled with a status/body/JSON, aborted with a network error, or let through. Newest route wins; times limits uses.

Argument Type Description
action "fulfill" | "abort" | "continue" Default: "fulfill".
body string Response body for fulfill.
delay_ms integer Wait this long before answering (to test loading states).
error string Network error for abort: Failed, Aborted, TimedOut, AccessDenied, ConnectionClosed, ConnectionReset, ConnectionRefused, NameNotResolved, InternetDisconnected, BlockedByClient.
headers object Default: {}.
json any JSON response body for fulfill; sets content-type: application/json.
method string Only this HTTP method (e.g. POST).
status integer Response status for fulfill (default 200).
times integer Only the first N matching requests; afterwards the route is removed.
url string URL glob: ** matches anything, * anything but /, ? one character, e.g. **/api/todos*.
url_regex string Regular expression matched against the full URL, instead of url.

TypeScript: page.route({ …options }) · Python: page.route(**options)

unroute

Remove a route by id, or all routes.

Argument Type Description
id string Route id from route; all routes when omitted.

TypeScript: page.unroute({ …options }) · Python: page.unroute(**options)

list_routes

Active routes with how often each matched.

No arguments.

TypeScript: page.listRoutes() · Python: page.list_routes()

get_requests

Requests the page made (method, URL, status, whether mocked), newest last.

No arguments.

TypeScript: page.getRequests() · Python: page.get_requests()

Tabs and frames

new_tab

Open a new tab (optionally at a URL) in this session and make it active.

Argument Type Description
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).
url string Page to open in the new tab; blank when omitted.
wait_until "dom_content_loaded" | "load" | "network_idle" Default: "load".

TypeScript: page.newTab({ …options }) · Python: page.new_tab(**options)

list_tabs

Open tabs of this session, including popups and target=_blank pages, with the active one marked.

No arguments.

TypeScript: page.listTabs() · Python: page.list_tabs()

switch_tab

Make a tab active by index, URL, title, or the newest one; waits for a matching tab to open (e.g. a popup).

Argument Type Description
index integer Tab index from list_tabs.
last boolean The newest tab. Default: false.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).
title_contains string First tab whose title contains this text. Waits for it to open.
url_contains string First tab whose URL contains this text. Waits for it to open (e.g. a popup).

TypeScript: page.switchTab({ …options }) · Python: page.switch_tab(**options)

close_tab

Close a tab (the active one by default); the opener or the last tab becomes active.

Argument Type Description
index integer Tab index from list_tabs; the active tab when omitted.

TypeScript: page.closeTab({ …options }) · Python: page.close_tab(**options)

list_frames

Frames (iframes) of the active tab with their names and URLs.

No arguments.

TypeScript: page.listFrames() · Python: page.list_frames()

switch_frame

Act inside an iframe (by its element, name or URL) until switch_frame with main=true or a navigation. Works for cross-site iframes.

Argument Type Description
main boolean Back to the tab's main frame. Default: false.
name string Frame name (<iframe name>), anywhere in the tab.
target target A string or a locator: see Targets and locators.
timeout_ms integer How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms).
url_contains string First frame whose URL contains this text, anywhere in the tab.

TypeScript: page.switchFrame({ …options }) · Python: page.switch_frame(**options)

Saved state

save_storage_state

Save this session's cookies and the localStorage of its open origins (a logged-in state) under a name, in Playwright's storageState format.

Argument Type Description
name (required) string Name of the saved state (letters, digits, '-', '_', '.'); stored as <name>.json in the state directory, in Playwright's storageState format.

TypeScript: page.saveStorageState(name) · Python: page.save_storage_state(name)

load_storage_state

Restore a saved state (cookies and localStorage) into this session, e.g. to start logged in.

Argument Type Description
name (required) string Name of the saved state (letters, digits, '-', '_', '.'); stored as <name>.json in the state directory, in Playwright's storageState format.

TypeScript: page.loadStorageState(name) · Python: page.load_storage_state(name)

Video

start_video

Start recording a video of the active tab (follows tab switches).

No arguments.

TypeScript: page.startVideo() · Python: page.start_video()

stop_video

Stop recording and save the video (WebM via ffmpeg) to the evidence directory.

Argument Type Description
name string File name stem in the evidence directory (default video).

TypeScript: page.stopVideo({ …options }) · Python: page.stop_video(**options)

Diagnostics and reports

get_console_errors

Console errors and uncaught exceptions seen in this session.

No arguments.

TypeScript: page.getConsoleErrors() · Python: page.get_console_errors()

get_network_failures

Failed requests and HTTP >= 400 responses seen in this session.

No arguments.

TypeScript: page.getNetworkFailures() · Python: page.get_network_failures()

get_test_report

Assertions, failed actions, diagnostics and evidence for this session.

No arguments.

TypeScript: page.getTestReport() · Python: page.get_test_report()

get_capabilities

Backend, engine version and per-feature support for this session.

No arguments.

TypeScript: page.getCapabilities() · Python: page.get_capabilities()