Browser tools
The tools the agent calls during a browser check. They come from the Browser Harness; you never call them in a spec, but knowing them helps you write goals the agent can act on. There is no eval, script injection or shell tool. To build the tool set yourself, see the TypeScript API.
Tool arguments
Section titled “Tool arguments”Target is a locator (see Target forms). ? marks an optional argument.
| Tool | Arguments | Does |
|---|---|---|
browser_goto | url | Navigate; relative paths resolve against baseUrl |
browser_get_url | None | Current URL |
browser_expect_url, browser_wait_for_url | url, exact?, timeoutMs? | Assert or wait for a URL |
browser_wait_for_network_idle | timeoutMs?, idleMs? | Wait until no requests are in flight for idleMs (default 500, at most 5000) |
browser_reload, browser_go_back, browser_go_forward | None | History navigation |
browser_snapshot | target?, maxElements?, includeAria?, maxAriaChars? | URL, title, up to 4,000 characters of visible text and controls with ref IDs |
browser_screenshot | name?, checkpoint?, reason?, target?, fullPage?, maxDimension? | Save a screenshot (default at most 2,000 px a side) |
browser_set_viewport | width, height | Resize the viewport |
browser_get_viewport | None | Current { width, height } |
browser_list_pages | None | Open pages and popups with index, URL and title |
browser_select_page, browser_close_page | index | Switch to or close a page from browser_list_pages |
browser_click, browser_double_click, browser_right_click, browser_hover | target, timeoutMs? | Mouse actions |
browser_click_at | x, y, button?, clicks?, reason | Click viewport coordinates, for canvases and controls without a usable target |
browser_drag_and_drop | source, target, timeoutMs? | Drag one element onto another |
browser_type | target, text, submit? | Fill a field; submit presses Enter |
browser_press | key, target? | Press a Playwright key such as Enter or Control+A |
browser_tab | shift? | Move focus forward or back |
browser_focus, browser_clear | target | Focus or clear a field |
browser_blur | None | Remove focus |
browser_check, browser_uncheck | target | Set a checkbox or radio |
browser_select_option | target, values | Choose one or more options |
browser_upload_file | target, paths | Attach files |
browser_expect_text | text, target?, timeoutMs? | Text is visible on the page or in target |
browser_wait_for_text | text, timeoutMs? | Wait for text |
browser_wait_for_selector | selector, timeoutMs? | Wait for a selector |
browser_expect_visible, browser_expect_hidden, browser_expect_enabled, browser_expect_disabled, browser_expect_focused | target, timeoutMs? | Element state |
browser_expect_value | target, value, timeoutMs? | Field value |
browser_expect_checked | target, checked?, timeoutMs? | Checkbox or radio state |
browser_expect_count | target, count, comparison?, timeoutMs? | Match count; equal, at_least or at_most |
browser_expect_attribute | target, attribute, value?, contains?, timeoutMs? | Attribute present, equal or containing a value |
browser_get_text | target? | Text of an element or the page |
browser_get_attribute | target, attribute | One attribute value |
browser_extract | target, fields?, limit? | Records from every match; fields are text (default), value, html or attribute:<name>; limit default 30, at most 100 |
browser_console_logs | level?, limit? | Console errors, page errors and failed requests; level: "all" adds other messages |
browser_run_steps | steps ({ tool, input? }[]) | Run up to 20 steps in one turn; stops at the first failure |
record_critical_point | id, description, status, evidence?, screenshot? | Track a requirement as pending, passed or failed |
finish_test | status, reason | End the check as passed or failed |
Tool behaviour
Section titled “Tool behaviour”| Rule | Detail |
|---|---|
| Assertions retry | Every browser_expect_* retries until it holds or timeoutMs (default 5000) runs out; a failure includes the URL, title and an ARIA excerpt |
| Batches | Each step in browser_run_steps is still recorded as its own action; finish_test and nested batches are not allowed in it |
| Finishing | A check that never calls finish_test is recorded as error. finish_test cannot pass while a critical point is pending or failed. |
| Recording | Every call becomes a BlopAction in results.json; see Result fields |
browser_console_logs tags each failed request [first-party] (same origin as the page: cite it as an app bug) or [third-party], and returns metadata.thirdPartyFailures. With internet egress, a third-party failure is a real configuration problem; without egress it is a test-environment limit and does not fail the site by itself. Containerized runs probe egress once per container (a HEAD request to https://1.1.1.1/); host-browser runs assume the host’s access.
Target forms
Section titled “Target forms”| Form | Example | Use |
|---|---|---|
| Reference | { ref: "e1" } | From the latest browser_snapshot; required for controls inside frames |
| Role and name | { role: "button", name: "Submit" } | Most reliable |
| Label | { label: "Email" } | Form fields |
| Placeholder | { placeholder: "Search" } | Fields without a label |
| Text | { text: "Sign in" } | Visible text |
| Test ID or ID | { testId: "cta" }, { id: "cta" } | Stable app attributes |
| Selector | { selector: ".cta" } | CSS or XPath; last resort |
| String | "Submit" | Detected automatically |
Objects also accept exact and first. If a step keeps failing, name the locator in the goal, such as “click the button named Submit”.