Browser acceptance tests for AI coding agents

Your coding agent said it’s done. Make the browser prove it.

Cairntrace turns what a feature should do into a YAML spec, replays it in a real browser, and hands your agent a failure report it can fix. Heal the path, never the promise.

Run your first spec See a real failing run

Works with Claude Code · Cursor · Codex · OpenCode

Free
MIT
No account
Runs locally

Install

brew install abdul-hamid-achik/tap/cairntrace

Check the environmentcairn doctor

Needs Bun 1.3+ (Homebrew installs it) · browser: agent-browser or Playwright

Open source · MIT licensed · View on GitHub · Build from source

examples/flows/01-dashboard-nav.ymlexample spec

version: 1
name: dashboard_nav
intent: from the home page, follow "Open dashboard" and land on a working dashboard

outcomes:
  - id: url_is_dashboard
    verify:
      url: { endsWith: /dashboard.html }
  - id: dashboard_heading_visible
    verify:
      text: { contains: Dashboard }
  - id: no_console_errors
    verify:
      console: { errorsMax: 0 }

steps:
  - id: open_home
    open: http://localhost:8787/
  - id: click_open_dashboard
    click: { by: role, role: link, name: Open dashboard }
  - id: wait_for_dashboard
    wait: { text: Dashboard, timeoutMs: 5000 }

cairn run examples/flows/01-dashboard-nav.yml --cold-start

passed3 outcomes · 3 steps

report.html · agent_context.md · outcomes/

Intent stays fixedSteps can be repairedEvidence stays local

Local-firstYour browser state and run evidence stay on your machine.

Agent-neutralOne CLI, MCP surface, and artifact shape for every harness.

Real browsersUse agent-browser by default or switch to Playwright.

Typed outcomesAssert UI, URL, network, console, files, JSON, and more.

The missing acceptance layer

A green build is not proof the user journey works.

Coding agents can change the code, run unit tests, and still miss a broken checkout, an empty dashboard, or a button that no longer responds. Cairntrace moves the final check into the browser and makes its result legible to the next agent.

Read the contract-first authoring guide

Behavior contract

intent + outcomes define what success means.

fixed

Repairable path

steps are executable hints, not the contract itself.

editable

Evidence pack

Reports, snapshots, console, network, and outcome files.

portable

One behavioral promise, replayed and explained end to end.

A tighter agent loop

Specify. Replay. Repair.

Cairntrace gives the agent a deterministic route from product intent to browser evidence without coupling the spec to one model or one test runner.

01
Declare the outcome
Write the intent and typed observables before scripting the clicks.
cairn spec verify flows/checkout.yml --stamp
02
Replay from a clean browser
Use a login action, checkpoint, or deterministic precondition for cold-start replay.
cairn run flows/checkout.yml --cold-start --json
03
Hand the failure back
Read the focused agent context, inspect the evidence, and repair only the path.
cairn context latest

Connect your agent

Register one MCP server and your agent gets the browser as a tool.

Cairntrace runs as a stdio MCP server started with cairn mcp. Register it once in your harness, then have the agent call cairn_doctor to verify the setup, then cairn_explain once to read the tool surface.

Full MCP reference

run in your terminal

claude mcp add cairntrace -- cairn mcp

Let the agent write the spec

Record the journey once, then promote the draft.

An agent can open the page, record each step, and export a draft spec. The draft is linted and run from a cold browser. It is promoted only after it passes.

Read the author-flow guide Discovery sessions

01
Discover
cairn_discover_open opens the page and returns a snapshot and locator inventory.
02
Interact
cairn_discover_interact records each click, fill, or assert as a step.
03
Export
cairn_discover_export writes the draft from the session journal, even after the browser closed.
04
Finish
cairn spec finish lints the draft, runs it cold, and stamps the contract when green.
05
Promote
cairn spec promote moves it into the suite, rebases its paths, and stamps the contract.

Built for work that survives the demo

A browser spec your whole toolchain can understand.

Human-readable contracts at authoring time. Stable machine-readable output at run time. Rich evidence when the browser disagrees.

Contract safety

Change the route without moving the finish line.

A contract hash covers intent + outcomes. Healing can rewrite drifted steps, but it cannot silently weaken what the spec promises.

contractHashsha256:98b7…4a21verified

Backend choice

Agent workflow now. Playwright when you need it.

agent-browserdefault
Playwrighttraces · video · CI
Mockfast offline tests

Repair-ready evidence

Start with the answer, then drill into the trace.

run/checkout-2026…├─ agent_context.md├─ report.html├─ outcomes/├─ snapshots/└─ network/ + console/

Stable agent interface

No Claude branch. No Codex shim. No vendor lock-in.

CLI commands support JSON, YAML, and Markdown. MCP tools mirror the same surface, so any capable coding agent can author, run, and read the same spec.

CLIMCPJSONYAMLMD

Beyond the click

Check the data, the setup, and the suite too.

Outcomes can read the backend, not only the page. Fixtures, services, suites, and runners are declared in cairntrace.config.yml, next to your specs.

How it differs

Three ways to check a browser feature.

Ad-hoc agent browsing is fast to start. Hand-written Playwright is mature. Cairntrace keeps the check as a spec the agent can run and repair.

Criterion	Ad-hoc agent + browser MCP	Hand-written Playwright	Cairntrace
Survives the session	No. Steps live in the chat.	Yes. Test files in the repo.	Yes. YAML spec in the repo.
Fixed definition of done	Whatever the agent decides it is.	Yes. The assertions you wrote.	Yes. Intent and outcomes, covered by a contract hash.
Agent-readable failure evidence	Screenshots and logs the agent has to interpret.	Traces and reports built for people.	Start with `agent_context.md`, then outcomes, snapshots, and console.
Drift repair	Re-explore the page each time.	Edit the test by hand.	Heal proposes step changes. The contract hash blocks changes to outcomes.
Exports to Playwright	No.	Native.	`cairn export playwright`, with `--verify`.

Playwright wins on ecosystem, maturity, and CI adoption. Cairntrace can use Playwright as its browser backend, and it can export to Playwright when a conventional test is the better home. Full comparison

From agent loop to CI

The same suite the agent ran, in CI.

--cold-start clears the browser profile first, so a pass does not depend on leftover state. --junit writes a report your CI can read. Exit codes tell the job what happened.

CI recipe Exit codes

# cairn is installed earlier in the job (see /ci)
- name: Browser acceptance
  run: cairn run --suite <name> --cold-start --junit cairn-junit.xml

Use it where confidence is expensive

Give every feature task a real browser definition of done.

Cairntrace fits the moment between “the code compiles” and “ship it.” Keep the spec beside the feature, let the agent run it while working, and preserve the evidence for review or CI.

01
Agent-built features
Verify the user-visible outcome before the task is called complete.
02
High-value workflows
Cover login, checkout, imports, dashboards, and multi-step operations.
03
Regression repair
Compare the browser state and patch locator drift without rewriting intent.
04
Human review
Open a self-contained report instead of reconstructing the run from raw logs.

Questions, answered

What teams ask before the first run.

Still evaluating the fit? The docs stay concrete and the repository is public.

Inspect the source on GitHub

What is Cairntrace?

Cairntrace is a local-first behavioral browser-spec layer for coding agents. A YAML spec defines the product intent, the observable outcomes, and a repairable sequence of browser steps.

Is Cairntrace a replacement for Playwright?

No. Cairntrace adds a contract and agent-readable evidence layer. It can use Playwright as a backend and export stable specs to Playwright when conventional CI tests are the better destination.

Which coding agents can use it?

Any agent that can call a CLI or MCP server can use the same Cairntrace surface. There are no product-specific branches for Codex, Claude Code, Cursor, or OpenCode.

Does it need Bun?

Yes, Bun 1.3.0 or newer (engines.bun in package.json). Homebrew installs it as a dependency. npm and bun installs need Bun on your PATH.

Does it run in CI?

Yes. --cold-start is on by default in CI, --junit writes JUnit XML, and cairn run exits with documented codes. The CI recipe is on /ci.

Is the MCP server safe to register?

It runs over stdio. Shell hooks and service starts (docker, seed, tmux) are refused until you opt in with --allow-hooks or --allow-services, or the matching CAIRN_MCP_ALLOW_* environment variable.

How is it different from Playwright MCP?

Playwright MCP gives the agent a browser to drive. Cairntrace is a spec format and a runner on top of a browser (agent-browser by default, or Playwright). Use a browser MCP to explore. Use Cairntrace to keep the check and its evidence.

Which operating systems are supported?

The install docs cover macOS and Linux (Homebrew, npm, bun, and the curl installer). Windows is not documented as supported.

Does it send telemetry? Does run data leave my machine?

The CLI does not import an analytics SDK or send usage data. Runs write browser state and artifacts locally. Network calls come from what you configure or invoke, such as your app, datasources, or cairn publish. This website uses Vercel Analytics for page views and CTA clicks.

What license is it under, and do I need an account?

MIT. There is no Cairntrace account. Local runs use your files and your browser. Checkpoints that hold app logins are created by you with cairn login.

The browser gets the final word

Turn “looks done” into evidence.

Install Cairntrace, run cairn doctor, and give your next coding task a browser contract.

brew install abdul-hamid-achik/tap/cairntrace

Start the quickstart Connect an agent

Your coding agent said it’s done. Make the browser prove it.

A green build is not proof the user journey works.

Specify. Replay. Repair.

Declare the outcome

Replay from a clean browser

Hand the failure back