A checkout test can turn green after the agent clicks “Continue” even when the order total is wrong. The result looks reassuring until someone asks what the browser displayed, which account was used, or whether the final page ever loaded.
AI browser testing is useful when the run keeps those answers. An agent operates a real browser from a user goal, records what it saw and did, checks the requested outcome, and leaves artifacts that another person can inspect. The artifacts are the evidence trace, the ordered record of what the browser observed and did.
Tangle Browser Agent is Tangle’s browser automation driver for natural-language browser tasks, UI checks, wallet flows, and evidence capture.
Its bad command is the command-line interface (CLI) for one-off browser runs, while its software development kit (SDK) lets an application start a run from code.
This post explains what an evidence trace needs to contain, how to design a case that can be judged, and where the claim stops.
For the lower-level browser loop, read Browser Automation for AI Agents: Evidence and Safe Stops.
A green sentence is too small a result
Suppose a team asks an agent to verify a free-plan signup. The intended claim is specific: a new account reaches the dashboard and the dashboard shows the workspace name that the user entered.
“The agent completed the task” does not establish that claim. The agent might have clicked a similarly named control, accepted a validation error, reached a cached page, or stopped after the dashboard shell loaded without the new workspace.
The test case should state the claim before the browser opens.
Start: the pricing page in a fresh browser profile.
Goal: create a disposable workspace named "Smoke" on the free plan.
Final condition: the dashboard shows "Smoke" as the active workspace.
Allowed actions: navigate, type into signup fields, and submit the free signup form.
Forbidden actions: purchase a plan, invite a real person, or delete existing data.
Evidence: the signup page, the completed form, the dashboard, and the stop reason.This wording gives the agent room to navigate while giving the reviewer a fixed condition to inspect. The final condition belongs to the test case, not the model, so the model cannot redefine success after the run.
What an evidence trace records
A trace is the ordered record of one run. It connects the requested goal to the observations, actions, outcomes, recoveries, and stopping point. It is closer to a flight recorder than to a paragraph written after the flight.
| Trace event | Minimum record | Reviewer question |
|---|---|---|
| goal | goal, start URL (web address), starting state, allowed actions | What was this run allowed to prove? |
| observation | URL, page title, DOM (Document Object Model) or accessibility excerpt, screenshot when relevant | What could the agent see? |
| action | action type, target, input, and timestamp or turn order | What did it attempt? |
| result | changed URL, visible text, enabled state, error, or network outcome | What changed after the action? |
| recovery | failed assumption, bounded alternative, and new observation | Why did the path change? |
| final check | expected condition, observed condition, and result | Did the user-visible goal hold? |
| stop | pass, fail, blocked, or inconclusive plus reason | Why did the run end here? |
The exact storage format can vary. The causal chain cannot. A screenshot without the preceding action is hard to interpret, and an action log without the resulting page state cannot show whether the click mattered.
An illustrative record might look like this:
{
"goal": "Create the disposable Smoke workspace and verify the dashboard name",
"startUrl": "https://example.com/pricing",
"turns": [
{
"turn": 1,
"observation": {
"url": "https://example.com/pricing",
"visibleText": ["Free", "Start free"],
"screenshot": "turn-1.png"
},
"action": {
"type": "click",
"target": "Start free"
},
"result": {
"url": "https://example.com/signup"
}
},
{
"turn": 2,
"observation": {
"visibleText": ["Create your workspace"],
"screenshot": "turn-2.png"
},
"action": {
"type": "fill",
"target": "Workspace name",
"value": "Smoke"
},
"result": {
"visibleText": ["Smoke"]
}
}
],
"finalCheck": {
"expected": "Dashboard shows Smoke as the active workspace",
"observed": "Dashboard shows Smoke as the active workspace",
"status": "pass"
},
"stopReason": "Goal condition observed"
}This is an illustrative evidence shape, not a promise about a particular output file. The useful part is the relationship between each observation and the action that followed it.
Evidence depends on the claim
Browser state has multiple layers. The Document Object Model, or DOM, is the structured tree of elements and attributes that the page exposes to browser code. The accessibility tree is a representation of interactive elements, roles, and names that assistive technology can use. A screenshot shows the rendered page at one viewport and one moment. Network and console records show requests and browser errors that may never appear in the page.
| Evidence | Best question | Important blind spot |
|---|---|---|
| DOM or accessibility tree | Which controls, labels, and states were exposed? | It can miss overlap, clipping, and visual hierarchy. |
| screenshot | What did a person see? | It can hide off-screen content and precise element identity. |
| URL and page state | Which route and form state were active? | It does not prove the business action succeeded. |
| network and console record | Did a request fail or produce a browser error? | A successful request does not prove the user-visible result. |
| wallet prompt capture | What account, chain, or permission did the user approve? | It does not prove the on-chain program behaved correctly. |
Choose evidence from the claim. A visual regression needs screenshots. A form check needs the relevant labels, values, and final page. A wallet test needs the wallet prompt and chain context. A read-only extraction may need only the URL, DOM, and returned values.
The WebDriver specification defines a standard way for another process to control and inspect a browser. Playwright provides a browser automation framework with isolation, assertions, parallel execution, and reports. AI browser testing adds goal interpretation and bounded recovery around those browser controls. It does not remove the need for precise final checks.
Start with a public, read-only browser task
Tangle publishes a machine-readable Browser Agent manifest with the package name, bad binary, safe discovery commands, and SDK exports. The public driver repository documents the same install path and CLI behavior.
npm install -g @tangle-network/browser-agent-driver
npx playwright install chromium
bad --help
bad run --help
bad snapshot --help
bad run \
--goal "Read the page title and confirm the page is public" \
--url https://example.comThe help commands inspect local CLI options without opening a site. The final command is a real browser task and needs a model-provider key in the runner environment. Start with a public, read-only page so a setup mistake cannot change customer data.
The driver also exposes a library surface. The following example follows the public repository’s PlaywrightDriver and BrowserAgent API.
import { chromium } from 'playwright'
import {
BrowserAgent,
PlaywrightDriver,
} from '@tangle-network/browser-agent-driver'
const browser = await chromium.launch()
const page = await browser.newPage()
const driver = new PlaywrightDriver(page)
const agent = new BrowserAgent({
driver,
config: {
model: process.env.BROWSER_AGENT_MODEL ?? 'gpt-5.4',
observationMode: 'hybrid',
plannerEnabled: true,
},
})
try {
const result = await agent.run({
goal: 'Read the page title and confirm that the page is public',
startUrl: 'https://example.com',
})
console.log({ success: result.success, reason: result.reason })
} finally {
await browser.close()
}Here hybrid combines structured page information with a screenshot, while plannerEnabled allows a short plan before actions.
The public driver README is the authority for options exposed by the installed version.
Read a failure without rerunning it
A useful trace lets a team classify a failed run from the saved record.
| Observation | Likely classification | Next action |
|---|---|---|
| signup form rejects a valid test email | product defect or fixture mismatch | inspect validation and starting data |
| dashboard loads without the workspace name | product defect or stale backend state | inspect the create response and refresh behavior |
| browser cannot reach the page | environment or dependency failure | check the URL, network, and service health |
| a consent banner covers the target | recoverable page variation | dismiss it once and record the change |
| login or human-verification challenge blocks progress | blocked | stop and hand the run to an approved session |
| two controls match the goal | agent ambiguity | stop or require a more specific goal |
“Blocked” is a real result. Treating it as a product failure creates noise. Treating it as a pass hides missing coverage. The run should preserve the screenshot and stop reason so the next person can decide whether to change the fixture, the product, or the case.
The public driver README lists automatic detection and attempted handling for reCAPTCHA v2, Cloudflare Turnstile, and Google unusual-traffic pages. A test policy can still classify a challenge as blocked when the required human or account boundary was not safely verified. Record any recovery attempt separately from the final product assertion.
An evaluation is the comparison between the trace and the acceptance condition. The final status comes from that comparison, not from the agent’s prose summary. An evaluation can be deterministic, such as checking visible text, or model-assisted, such as judging whether a screenshot satisfies a visual requirement. When a model helps judge the result, keep the expected condition and the supporting artifact visible to a reviewer.
Package the trace for handoff
A trace becomes part of an engineering workflow when a person can open it without asking the test author to reconstruct the run. Keep a small handoff record beside the screenshots and page observations.
| Handoff field | Example | Why it matters |
|---|---|---|
| case version | workspace-signup-v3 | A changed goal is a new claim. |
| runtime | Chrome version, viewport, locale, network class | The page may behave differently elsewhere. |
| account class | disposable owner account | The reviewer knows which permissions were present. |
| model profile | model, observation mode, turn limit | The action policy is reproducible. |
| artifact index | ordered screenshots, DOM excerpts, and errors | The reviewer can jump to the first divergence. |
| retention rule | redact credentials, keep test identifiers | Evidence should not become a secret store. |
The handoff should point to the first failed condition and the final screenshot. If a form accepted the value but the dashboard never changed, include the request result and the first dashboard observation. If a modal blocked the action, include the screenshot before dismissal and the screenshot after the bounded recovery. If the test stopped at a wallet prompt, include the requested chain and on-chain program context without exposing a private key.
This format also makes reruns more disciplined. The next run can change one variable, such as the fixture or browser version, and keep the original trace as a comparison point. Without the original conditions, a rerun can answer a different question while appearing to confirm the first result.
Keep the service boundary explicit
A local bad run proves what its own browser session observed.
If a team exposes the check as a reusable Tangle service, it should define the inputs, outputs, artifact retention, and execution owner separately from the browser assertion.
A Blueprint is a reusable Tangle service definition, and an operator is the provider that runs a live service instance from that definition.
Those terms describe how a job is packaged and executed.
They do not prove that the tested application reached the requested state or that an on-chain program produced the expected result.
Where the evidence claim stops
AI browser testing proves what the tested browser session observed for the supplied inputs. It does not prove every device, account, locale, network, or browser version behaves the same way. It does not prove a transaction settled on a chain unless the test records confirmation from the system that owns the transaction. It does not prove an on-chain program is safe. It does not make a private credential safe to expose to an agent.
The trace should therefore include the browser version, model or agent profile, observation mode, starting state, URL, test account class, and stop reason. Those fields let a reviewer separate a product defect from a bad fixture, an unavailable dependency, a model mistake, or an untested condition.
What is AI browser testing?
AI browser testing uses an agent to operate a real browser from a user goal, observe page state, take bounded actions, and check a user-visible result.
What is an evidence trace?
An evidence trace is the ordered record of the goal, observations, actions, results, recoveries, final check, and stop reason for one browser run.
How is this different from Playwright?
Playwright supplies deterministic browser control and test tooling. An AI browser driver adds goal interpretation, observation choices, bounded recovery, and a record of the run.
Should an AI browser test run in continuous integration?
It can run in continuous integration when the case has stable fixtures, an explicit final condition, and artifacts that a reviewer can inspect after failure.
What should the first run test?
Use a public or disposable, read-only page. Move to authenticated flows only after the trace, stop policy, and failure classification work on the harmless case.
Choose the smallest honest evidence boundary
Use deterministic browser tests when page queries and outcomes are stable. Use AI browser testing when the user-facing path changes often or requires page interpretation. Use both when flexible navigation needs a fixed assertion at the end.
The first release-blocking run should be the smallest case whose screenshots, page state, actions, and final check let another engineer decide whether the product worked.
For a cross-page journey, continue with AI E2E Testing for Browser Flows, which extends the same evidence boundary across application and service state.