Skip to content

t1k:web:testing:agent-browser

FieldValue
Moduletesting
Version1.14.9
Efforthigh
Tools—

Keywords: agent-browser, automation, browser, playwright, testing

/t1k:web:testing:agent-browser
[url or task]

Browser automation CLI designed for AI agents. Uses “snapshot + refs” paradigm for 93% less context than Playwright MCP.

Most of the snapshot → interact → re-snapshot loop needs judgment — which ref to click, whether the resulting state means the workflow succeeded — and stays on a reasoning tier. The one slice that is purely mechanical is a self-verifying session: re-running snapshot on an interval until a named terminal state appears (build finished, element present, video recording stopped), the same “poll until terminal, report per check” shape t1k-ci-watcher already covers (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):

StepAgent
Poll a long-running autonomous session (video recording, Browserbase cloud run) until it reaches a named terminal state, report what firedt1k-ci-watcher

Choosing which @ref to interact with, reading a snapshot to decide the next action, and judging whether the workflow actually succeeded all read the result and form a judgment — keep those on a reasoning tier.

Terminal window
# Install globally
bun add -g agent-browser
# Download Chromium (one-time)
agent-browser install
# Linux: include system deps
agent-browser install --with-deps
# Verify
agent-browser --version

The 4-step pattern for all browser automation:

Terminal window
# 1. Navigate
agent-browser open https://example.com
# 2. Snapshot (get interactive elements with refs)
agent-browser snapshot -i
# Output: button "Sign In" @e1, textbox "Email" @e2, ...
# 3. Interact using refs
agent-browser fill @e2 "user@example.com"
agent-browser click @e1
# 4. Re-snapshot after page changes
agent-browser snapshot -i
Use agent-browserUse chrome-devtools
Long autonomous AI sessionsQuick one-off screenshots
Context-constrained workflowsCustom Puppeteer scripts needed
Video recording for debuggingWebSocket full frame debugging
Cloud browsers (Browserbase)Existing workflow integration
Multi-tab handlingNeed Sharp auto-compression
Self-verifying build loopsSession with auth injection

Token efficiency: ~280 chars/snapshot vs 8K+ for Playwright MCP.

Full command reference (navigate, click, type, screenshot, wait, etc.): see references/command-reference.md.

OptionDescription
--session <name>Named session for parallel testing
--jsonJSON output for parsing
--headedShow browser window
--cdp <port>Connect via Chrome DevTools Protocol
-p <provider>Cloud browser provider
--proxy <url>Proxy server
--headers <json>Custom HTTP headers
--executable-pathCustom browser binary
--extension <path>Load browser extension
VariableDescription
AGENT_BROWSER_SESSIONDefault session name
AGENT_BROWSER_PROVIDERCloud provider (e.g., browserbase)
AGENT_BROWSER_EXECUTABLE_PATHBrowser binary location
AGENT_BROWSER_EXTENSIONSComma-separated extension paths
AGENT_BROWSER_STREAM_PORTWebSocket streaming port
AGENT_BROWSER_HOMECustom installation directory
AGENT_BROWSER_PROFILEBrowser profile directory
BROWSERBASE_API_KEYBrowserbase API key
BROWSERBASE_PROJECT_IDBrowserbase project ID

Full common patterns (form submission, auth flows, SPAs): see references/common-patterns.md.

For CI/CD or environments without local browser:

Terminal window
# Set credentials
export BROWSERBASE_API_KEY="your-api-key"
export BROWSERBASE_PROJECT_ID="your-project-id"
# Use cloud browser
agent-browser -p browserbase open https://example.com

See references/browserbase-cloud-setup.md for detailed setup.

IssueSolution
Command not foundRun bun add -g agent-browser
Chromium missingRun agent-browser install
Linux deps missingRun agent-browser install --with-deps
Session staleClose browser: agent-browser close
Element not foundRe-run snapshot -i after page changes
  • BROWSERBASE_API_KEY exported to env IS a credential leak — wrap in per-instance closure, rotate quarterly.