Test it like a user before it ships: agent-browser for coding agents

Here's a failure every developer has shipped: the tests pass, the types check, the build is green, and the page is broken. A button sits under a cookie banner. A form submits but shows nothing. A script throws on mobile only.

Agents make this more common, not less, because an agent will happily report "done" based on the code it wrote. The fix is the same for both: before it ships, someone has to use it. Test, test, test, in a real browser.

What agent-browser is

agent-browser is a browser automation CLI built for AI agents, from Vercel Labs (Apache-2.0). It's a native Rust CLI that talks to Chrome directly over the DevTools protocol, with no Playwright or Puppeteer dependency. A small background daemon keeps the browser open between commands, so each step is fast.

The idea that makes it work well for agents is the snapshot. Instead of dumping raw HTML, agent-browser snapshot returns the page's accessibility tree with short references for each element:

- heading "Join the waitlist" [ref=e1]
- textbox "Email address" [ref=e3]
- button "Join the waitlist" [ref=e5]

The agent then acts on those refs (click @e5), and takes a new snapshot after the page changes. The project's docs say this lets agents interact with a page "in ~200-400 tokens instead of parsing raw HTML."

Install

npm install -g agent-browser && agent-browser install   # second step downloads Chrome
npx skills add vercel-labs/agent-browser                 # teach your agent to use it

Homebrew (brew install agent-browser) works too, and on Linux agent-browser install --with-deps adds the system libraries Chrome needs. The skill comes from skills.sh, where it's one of the most-installed skills.

One nice design choice: the installed SKILL.md is a small stub that tells the agent to load the real instructions from the CLI itself (agent-browser skills get core). The instructions always match the installed version, so they never go stale.

The test loop

The core loop is short: open, snapshot, act, check, repeat.

agent-browser open http://localhost:4321
agent-browser wait --load domcontentloaded
agent-browser snapshot -i          # interactive elements only

agent-browser fill @e3 "test@example.com"
agent-browser click @e5
agent-browser wait --text "You're on the list"

agent-browser errors                # uncaught page errors
agent-browser console               # console output
agent-browser a11y --json           # built-in axe accessibility scan
agent-browser screenshot --annotate # a picture, with element labels

agent-browser diff screenshot --baseline before.png
agent-browser diff snapshot

Waiting on something specific (wait --text, wait --url, wait @ref) is more reliable than waiting for the network to go quiet. And for parallel work, give each task its own named session so agents don't share a browser:

export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix task)"

What to ask your agent

You don't have to write these commands yourself. With the skill installed, a prompt like this is enough:

The signup form on the home page is done. Before you tell me it works, use agent-browser to test it on http://localhost:4321:
- submit an invalid email, then a valid one
- confirm the success message appears and there are no console errors
- run an accessibility check and fix anything serious
- do the same at a 390px-wide mobile viewport
Report what you checked, with a screenshot of the final state.

That last line matters. Asking for evidence (what was checked, plus a screenshot) turns "it works" from a claim into something you can verify in ten seconds. It's the same idea as asking what would show the result is right.

For a broader pass, the project also ships a dogfood skill for exploratory QA. It works through six steps (initialize, authenticate, orient, explore, document, wrap up) and writes a report with screenshots, repro steps and videos for every issue it finds.

Where it fits with your tests

agent-browser doesn't replace a test suite.

• Unit and integration tests catch regressions on every commit. Keep writing them.
• End-to-end suites (Playwright, Cypress) lock important flows down permanently in CI.
• An agent driving a browser is the exploratory pass before shipping: does the new thing actually work, on a real page, at a real size, for a real user? It's also great at turning what it finds into a proper end-to-end test.

Every change on this site goes through that last step before it's deployed: a headless browser clicks through the feature on desktop, touch and reduced-motion settings, and checks for errors and layout overflow. It catches things the build never will.

Tests prove the code does what you wrote. A browser proves it does what you meant. Run both before anything goes live.