Browser tools

Blop hands the agent a curated set of tools from @blopai/browser-harness. You don’t call these directly in a Blop test. The agent decides which tool to use for your goal, but knowing what’s available helps you write goals it can act on.

For the full type signature of every tool, see API reference → Browser tools.

Tool families

Navigation

browser_goto, browser_get_url, browser_expect_url, browser_wait_for_url, browser_reload, browser_go_back, browser_go_forward.

The agent navigates and asserts URL changes. Use absolute URLs for external hosts; relative paths resolve against baseUrl.

Page inspection

browser_snapshot (URL + title + body excerpt), browser_screenshot, browser_set_viewport, browser_get_viewport.

The agent calls browser_snapshot whenever it needs to “see” the page. Screenshots land in .blop/screenshots/ and are referenced from results.json.

Mouse

browser_click, browser_double_click, browser_right_click, browser_hover, browser_drag_and_drop.

Keyboard

browser_type, browser_press, browser_tab, browser_focus, browser_blur, browser_clear.

browser_press accepts standard Playwright key names: Enter, Tab, Escape, ArrowDown, Control+A, etc.

Forms

browser_check, browser_uncheck, browser_select_option, browser_upload_file.

Assertions

browser_expect_text, browser_wait_for_text, browser_wait_for_selector, browser_get_text, browser_expect_visible, browser_expect_hidden, browser_expect_value, browser_expect_checked, browser_expect_enabled, browser_expect_disabled, browser_expect_count, browser_expect_attribute, browser_expect_focused, browser_get_attribute.

These are the agent’s primary way to verify outcomes. Goals like “verify the heading reads Welcome” map naturally to browser_expect_text; “verify the email field shows test@example.com” to browser_expect_value; “verify the cart lists 3 items” to browser_expect_count.

Every browser_expect_* assertion auto-retries until it holds or its timeoutMs elapses (default 5000 ms), so async UI — network requests, animations, hydration — doesn’t produce flaky failures. When an assertion fails, the error carries the current URL, title, and a trimmed ARIA snapshot so the agent can correct course instead of guessing.

Data extraction and diagnostics

browser_extract, browser_console_logs.

browser_extract reads text, values, or attributes from every element a target matches in one call. The agent uses it to ground claims about lists, rankings, sorts, and counts in actual page data — “the cheapest item” is proven by extracting every price, not by eyeballing a screenshot.

browser_console_logs surfaces console errors, uncaught page exceptions, and failed network requests to the agent, so a blank page or dead button can be tied to the underlying app error in the failure reason.

Batched execution

browser_run_steps runs up to 20 tool steps in one agent turn once a flow is predictable — fill, click, assert — cutting model round-trips on long flows. It stops at the first failing step and reports which step failed. Each inner step is still recorded as its own action, so reports and live progress are unchanged.

Lifecycle

record_critical_point(id, description, status, evidence?), finish_test(status, reason).

Required. Every test must end with finish_test. The agent calls it with status: "passed" after verifying success, or status: "failed" when the product behavior didn’t match the goal. If the agent never calls it, Blop records the test as error. finish_test refuses to pass while any recorded critical point is still pending or failed.

Target locators

Most tools that act on an element accept a target argument. The agent picks the most specific form available:

Form	Example	When to use
Role + name	{ role: "button", name: "Submit" }	Most reliable; works against accessibility tree
Label	{ label: "Email" }	Form fields
Text	{ text: "Sign in" }	Visible text content
CSS / XPath	{ selector: ".cta" } or "//button[1]"	Last resort
String shorthand	"Submit"	Auto-detected

When you write a goal, you don’t have to pre-pick the locator — the agent will. But if a tool repeatedly fails, suggesting a locator in the goal often helps:

“Click the button labeled Submit (role=button, name=‘Submit’).”

Recording

Every tool call is recorded as a BlopAction on the test result:

{
  name: "browser_click",
  input: { target: { role: "button", name: "Submit" } },
  output: "clicked",
  timestamp: "2026-05-09T12:00:01.234Z",
}

Combined with events.jsonl, this gives you a complete replay of what the agent did. See Reporters & output.

Why no eval or shell tool

Blop deliberately doesn’t expose page.evaluate, page.addScriptTag, or any shell escape. Controlled native tools are the safety boundary between an LLM and your browser. If you need a capability the catalog doesn’t cover today, open an issue describing the user-facing scenario rather than reaching for a generic eval.