# Browser tools

> Look up every Browser Harness tool the browser check agent can call, with its arguments and limits.

The tools the agent calls during a [browser check](/reference/glossary/#browser-check). They come from the [Browser Harness](/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](/harness/library/).

## Tool arguments

`Target` is a locator (see [Target forms](#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

| 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](/reference/runner/#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

| 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`".