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:
run scripts: a step { "op": "fill", "target": "Email", "value": "ada@example.com" }. Test files also have expect.page.fill('Email', 'ada@example.com', { timeout_ms: 2000 }), a camelCase method, with required arguments in order and the rest in an options object.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.
navigate, go_back, go_forward, reloadget_page_snapshot, get_accessibility_tree, find_element, get_screenshot, get_dom_snapshotclick, hover, check, fill, type_text, press_key, select_option, upload_file, evaluatewait_for, assert_page_stateroute, unroute, list_routes, get_requestsnew_tab, list_tabs, switch_tab, close_tab, list_frames, switch_framesave_storage_state, load_storage_statestart_video, stop_videoget_console_errors, get_network_failures, get_test_report, get_capabilitiesOpen 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 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 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 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)
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)
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)
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)
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)
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)
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)
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)
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)
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 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 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)
Choose an option of a
| Argument | Type | Description |
|---|---|---|
target (required) |
target | A string or a locator: see Targets and locators. |
option (required) |
string | Option value or visible label. |
timeout_ms |
integer | How long to wait, in ms. Default: the session's timeout (10 s; in swiftbrowse test, --expect-timeout-ms). |
TypeScript: page.selectOption(target, option, { …options }) · Python: page.select_option(target, option, **options)
Select files on an 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)
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)
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)
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)
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)
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)
Active routes with how often each matched.
No arguments.
TypeScript: page.listRoutes() · Python: page.list_routes()
Requests the page made (method, URL, status, whether mocked), newest last.
No arguments.
TypeScript: page.getRequests() · Python: page.get_requests()
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)
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()
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 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)
Frames (iframes) of the active tab with their names and URLs.
No arguments.
TypeScript: page.listFrames() · Python: page.list_frames()
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)
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)
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)
Start recording a video of the active tab (follows tab switches).
No arguments.
TypeScript: page.startVideo() · Python: page.start_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)
Console errors and uncaught exceptions seen in this session.
No arguments.
TypeScript: page.getConsoleErrors() · Python: page.get_console_errors()
Failed requests and HTTP >= 400 responses seen in this session.
No arguments.
TypeScript: page.getNetworkFailures() · Python: page.get_network_failures()
Assertions, failed actions, diagnostics and evidence for this session.
No arguments.
TypeScript: page.getTestReport() · Python: page.get_test_report()
Backend, engine version and per-feature support for this session.
No arguments.
TypeScript: page.getCapabilities() · Python: page.get_capabilities()
# 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`](assertions.md).
- **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](locators.md). A `condition` is described in [Assertions](assertions.md). Every operation returns an [ActionResult](results.md).
- **Navigation:** [`navigate`](#navigate), [`go_back`](#goback), [`go_forward`](#goforward), [`reload`](#reload)
- **Reading the page:** [`get_page_snapshot`](#getpagesnapshot), [`get_accessibility_tree`](#getaccessibilitytree), [`find_element`](#findelement), [`get_screenshot`](#getscreenshot), [`get_dom_snapshot`](#getdomsnapshot)
- **Actions:** [`click`](#click), [`hover`](#hover), [`check`](#check), [`fill`](#fill), [`type_text`](#typetext), [`press_key`](#presskey), [`select_option`](#selectoption), [`upload_file`](#uploadfile), [`evaluate`](#evaluate)
- **Waiting and assertions:** [`wait_for`](#waitfor), [`assert_page_state`](#assertpagestate)
- **Network:** [`route`](#route), [`unroute`](#unroute), [`list_routes`](#listroutes), [`get_requests`](#getrequests)
- **Tabs and frames:** [`new_tab`](#newtab), [`list_tabs`](#listtabs), [`switch_tab`](#switchtab), [`close_tab`](#closetab), [`list_frames`](#listframes), [`switch_frame`](#switchframe)
- **Saved state:** [`save_storage_state`](#savestoragestate), [`load_storage_state`](#loadstoragestate)
- **Video:** [`start_video`](#startvideo), [`stop_video`](#stopvideo)
- **Diagnostics and reports:** [`get_console_errors`](#getconsoleerrors), [`get_network_failures`](#getnetworkfailures), [`get_test_report`](#gettestreport), [`get_capabilities`](#getcapabilities)
## Navigation
### navigate
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](locators.md). |
| `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](locators.md). |
| `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](assertions.md). |
| `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](locators.md). |
| `expect` | condition | See [Assertions](assertions.md). |
| `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](locators.md). |
| `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](locators.md). |
| `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](locators.md). |
| `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](assertions.md). |
| `target` | target | A string or a locator: see [Targets and locators](locators.md). |
| `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 <select> by value or label and verify the selection.
| Argument | Type | Description |
|---|---|---|
| `target` (required) | target | A string or a locator: see [Targets and locators](locators.md). |
| `option` (required) | string | Option value or visible label. |
| `timeout_ms` | integer | How long to wait, in ms. Default: the session's timeout (10 s; in `swiftbrowse test`, `--expect-timeout-ms`). |
TypeScript: `page.selectOption(target, option, { …options })` · Python: `page.select_option(target, option, **options)`
### upload_file
Select files on an <input type=file> 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](locators.md). |
| `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](assertions.md). |
| `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](assertions.md). |
| `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](locators.md). |
| `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()`