kivo360/agent-browser

agent-browser

CLI browser automation optimized for AI. Use refs from snapshots for reliable element selection. 93% less context than Playwright MCP, 95% first-try success rate.

Core Workflow

agent-browser open <url>           # Navigate
agent-browser snapshot -i          # Get interactive elements with refs
agent-browser click @e2            # Click by ref
agent-browser fill @e3 "text"      # Fill by ref
agent-browser snapshot -i          # Re-snapshot after changes
agent-browser close                # Close browser

Snapshot (Most Important)

Get accessibility tree with element refs for deterministic selection:

agent-browser snapshot              # Full tree
agent-browser snapshot -i           # Interactive only (buttons, inputs, links)
agent-browser snapshot -c           # Compact (no empty elements)
agent-browser snapshot -d 3         # Limit depth
agent-browser snapshot -i -c --json # Combine for AI parsing

Output example:

- heading "Example Domain" [ref=e1]
- button "Submit" [ref=e2]
- textbox "Email" [ref=e3]

Use refs with @ prefix: agent-browser click @e2

Essential Commands

Navigation

agent-browser open <url>            # Go to URL
agent-browser back                  # Go back
agent-browser forward               # Go forward
agent-browser reload                # Reload page

Interaction

agent-browser click @ref            # Click element
agent-browser fill @ref "text"      # Clear and fill input
agent-browser type @ref "text"      # Type into element
agent-browser press Enter           # Press key
agent-browser select @ref "value"   # Select dropdown option
agent-browser check @ref            # Check checkbox
agent-browser hover @ref            # Hover element
agent-browser scroll down 500       # Scroll (up/down/left/right)

Get Info

agent-browser get text @ref         # Get text content
agent-browser get value @ref        # Get input value
agent-browser get title             # Page title
agent-browser get url               # Current URL

Check State

agent-browser is visible @ref       # Check visibility
agent-browser is enabled @ref       # Check if enabled
agent-browser is checked @ref       # Check if checked

Wait

agent-browser wait @ref             # Wait for element visible
agent-browser wait 2000             # Wait milliseconds
agent-browser wait --text "Welcome" # Wait for text
agent-browser wait --load networkidle  # Wait for network idle

Screenshot/Output

agent-browser screenshot            # Base64 to stdout
agent-browser screenshot page.png   # Save to file
agent-browser screenshot --full     # Full page
agent-browser pdf output.pdf        # Save as PDF

Testing Patterns

Login Flow Test

agent-browser open https://app.example.com/login
agent-browser snapshot -i
# Identify: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Sign In" [ref=e3]
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser snapshot -i  # Verify dashboard loaded
agent-browser get text @e1  # Verify welcome message

Form Submission Test

agent-browser open https://app.example.com/contact
agent-browser snapshot -i
agent-browser fill @e1 "John Doe"          # Name field
agent-browser fill @e2 "[email protected]"  # Email field
agent-browser fill @e3 "Hello world"       # Message field
agent-browser click @e4                     # Submit button
agent-browser wait --text "Thank you"       # Verify success message
agent-browser snapshot -i                   # Confirm state

Authentication State (Reuse Login)

# Save auth after login
agent-browser open https://app.example.com/login
agent-browser snapshot -i && agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password" && agent-browser click @e3
agent-browser wait --load networkidle
agent-browser state save auth.json          # Save cookies/storage

# Reuse in later tests
agent-browser state load auth.json          # Load saved state
agent-browser open https://app.example.com/dashboard  # Already logged in

E2E Workflow Test

# Test complete user journey
agent-browser open https://shop.example.com
agent-browser snapshot -i

# Search for product
agent-browser fill @e1 "laptop"  # Search box
agent-browser click @e2          # Search button
agent-browser wait --load networkidle
agent-browser snapshot -i

# Add to cart
agent-browser click @e5          # First product
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser click @e3          # Add to cart button
agent-browser wait --text "Added to cart"

# Checkout
agent-browser click @e4          # Cart icon
agent-browser snapshot -i
agent-browser click @e2          # Checkout button
agent-browser wait --url "**/checkout"

Visual Regression

agent-browser open https://app.example.com/component
agent-browser wait --load networkidle
agent-browser screenshot baseline.png --full
# Make changes, then compare
agent-browser screenshot current.png --full

Error State Testing

agent-browser open https://app.example.com/form
agent-browser snapshot -i
agent-browser click @e5  # Submit without filling required fields
agent-browser wait 500
agent-browser snapshot -i  # Capture error states
agent-browser get text @e1  # Verify error message text

Parallel Testing with Sessions

# Run tests in isolated sessions
agent-browser --session test1 open https://app.example.com/feature-a
agent-browser --session test2 open https://app.example.com/feature-b

# Each session has separate cookies/storage
agent-browser --session test1 snapshot -i
agent-browser --session test2 snapshot -i

# List active sessions
agent-browser session list

Debugging Tests

agent-browser open url --headed     # See browser window
agent-browser console               # View console messages
agent-browser errors                # View page errors
agent-browser highlight @e3         # Highlight element visually
agent-browser trace start           # Record trace
# ... run test steps ...
agent-browser trace stop trace.zip  # Save for analysis

CSS/Text Selectors (Alternative)

When refs aren't available:

agent-browser click "#submit"
agent-browser click ".btn-primary"
agent-browser click "text=Sign In"
agent-browser find role button click --name "Submit"

Options

| Flag | Description | |------|-------------| | --session <name> | Use isolated session | | --json | JSON output (for parsing) | | --headed | Show browser window | | --full | Full page screenshot |

Best Practices for Testing

1. Always snapshot first - Get refs before interacting
2. Use wait after actions - Ensure page state settles
3. Re-snapshot after navigation - Refs change between pages
4. Use --json for assertions - Parse structured output
5. Save auth state - Avoid repeated login flows
6. Use sessions for parallel tests - Isolated browser instances
7. Use --headed for debugging - See what's happening