agent-browser

name	agent-browser
description	Automate browser interactions for UI testing and debugging — navigate pages, fill forms, take screenshots, upload files, verify elements. Use when the user wants to test or interact with a web app from the CLI.
version	1.0.0

Agent Browser Skill

Automate browser interactions for UI testing, debugging, and development iteration using Claude Code's agent-browser automation tool.

Overview

This skill enables interactive browser automation directly from Claude Code, allowing you to:

• Launch browsers and navigate to URLs
• Inspect and interact with page elements
• Verify UI state and extract information
• Test workflows like form submissions and file uploads
• Take screenshots for visual verification

When This Skill Applies

This skill activates when you need to:

• Test UI components - Verify buttons, forms, dropdowns work correctly
• Inspect page structure - Examine DOM elements and their properties
• Automate workflows - Click, fill, and submit forms programmatically
• Upload files - Test file inputs and upload flows
• Verify visual state - Take screenshots at different stages
• Debug page issues - Check element visibility, attributes, content

Agent-Browser CLI Reference

agent-browser - fast browser automation CLI for AI agents

Usage: agent-browser <command> [args] [options]

Core Commands:
  open <url>                 Navigate to URL
  click <sel>                Click element (or @ref)
  dblclick <sel>             Double-click element
  type <sel> <text>          Type into element
  fill <sel> <text>          Clear and fill
  press <key>                Press key (Enter, Tab, Control+a)
  hover <sel>                Hover element
  focus <sel>                Focus element
  check <sel>                Check checkbox
  uncheck <sel>              Uncheck checkbox
  select <sel> <val...>      Select dropdown option
  drag <src> <dst>           Drag and drop
  upload <sel> <files...>    Upload files
  scroll <dir> [px]          Scroll (up/down/left/right)
  scrollintoview <sel>       Scroll element into view
  wait <sel|ms>              Wait for element or time
  screenshot [path]          Take screenshot
  pdf <path>                 Save as PDF
  snapshot                   Accessibility tree with refs (for AI)
  eval <js>                  Run JavaScript
  connect <port>             Connect to browser via CDP
  close                      Close browser

Navigation:
  back                       Go back
  forward                    Go forward
  reload                     Reload page

Get Info:  agent-browser get <what> [selector]
  text, html, value, attr <name>, title, url, count, box, styles

Check State:  agent-browser is <what> <selector>
  visible, enabled, checked

Find Elements:  agent-browser find <locator> <value> <action> [text]
  role, text, label, placeholder, alt, title, testid, first, last, nth

Mouse:  agent-browser mouse <action> [args]
  move <x> <y>, down [btn], up [btn], wheel <dy> [dx]

Browser Settings:  agent-browser set <setting> [value]
  viewport <w> <h>, device <name>, geo <lat> <lng>
  offline [on|off], headers <json>, credentials <user> <pass>
  media [dark|light] [reduced-motion]

Network:  agent-browser network <action>
  route <url> [--abort|--body <json>]
  unroute [url]
  requests [--clear] [--filter <pattern>]

Storage:
  cookies [get|set|clear]    Manage cookies
  storage <local|session>    Manage web storage

Tabs:
  tab [new|list|close|<n>]   Manage tabs

Debug:
  trace start|stop [path]    Record trace
  record start <path> [url]  Start video recording
  record stop                Stop and save video
  console [--clear]          View console logs
  errors [--clear]           View page errors
  highlight <sel>            Highlight element

Sessions:
  session                    Show current session name
  session list               List active sessions

Snapshot Options:
  -i, --interactive          Only interactive elements
  -c, --compact              Remove empty structural elements
  -d, --depth <n>            Limit tree depth
  -s, --selector <sel>       Scope to CSS selector

Options:
  --session <name>           Isolated session
  --headers <json>           HTTP headers for auth
  --executable-path <path>   Custom browser executable
  --json                     JSON output
  --full, -f                 Full page screenshot
  --headed                   Show browser window
  --debug                    Debug output

IMPORTANT - Headed mode on Linux:
  agent-browser's --headed flag does NOT produce a visible window on Linux.
  The daemon launches chrome with --no-startup-window regardless of the flag.
  To open a real visible browser window, launch the system Chromium directly:
    DISPLAY=:1 chromium <url> &
  Determine the correct DISPLAY value first: run `echo $DISPLAY` in the shell.
  Use this whenever the user needs to log in or manually interact before
  handing back control to agent-browser in headless mode.

Examples:
  agent-browser open example.com
  agent-browser snapshot -i              # Interactive elements
  agent-browser click @e2                # Click by ref
  agent-browser fill @e3 "[e-mail]"
  agent-browser screenshot --full

Quick Examples

Open a page and take screenshot:

agent-browser open http://localhost:3000/instructions
agent-browser screenshot

Click an element:

agent-browser click "button[data-testid='submit']"

Fill an input field:

agent-browser fill "input[name='email']" "[e-mail]"

Select from dropdown:

agent-browser select "select[name='biller']" "XPO Logistics"

Take a snapshot (for AI):

agent-browser snapshot --interactive

Wait for element:

agent-browser wait "div.success-message"

Upload a file:

agent-browser upload "input[type='file']" "~/Downloads/invoice.pdf"

Real Use Cases from Development

1. Testing 3PL Selector in PDF Upload Dialog

When developing the 3PL instructions feature for PDF invoice extraction, agent-browser verified that:

• The dropdown selector appears with correct label: "3PL / Biller (Optional)"
• All billers from instruction sets populate in dropdown options
• Selection state persists when uploading files
• Selected biller name is passed to the extraction API

Why it mattered: Confirmed frontend integration with backend instructions data without manual browser testing.

2. Verifying Page Navigation and Loading

Used to test that specific routes load correctly:

• http://localhost:3000/instructions - Instructions management page
• http://localhost:3000/summary-charges/add-charges?brand=TCT - PDF upload dialog

Why it mattered: Quick verification that pages are accessible and rendering, catching routing errors early.

3. Capturing Screenshots for Documentation

Took snapshots at each test phase to document:

• Initial page state before interactions
• Dialog open with selector visible
• Form filled with test data
• Success states after submission

Why it mattered: Visual evidence that UI changes work as expected, useful for PRs and bug reports.

4. Inspecting Element Structure

Used snapshot command to:

• Verify SearchableSelect component rendered with correct props
• Check HTML hierarchy of dialogs and form elements
• Understand page layout before interacting

Why it mattered: Understanding page structure before writing selectors for clicks/fills.

5. Testing Form Workflows

Tested complete user journeys:

• Click "Import from PDF" button
• Select instruction set from dropdown
• Upload PDF file through file input
• Trigger extraction
• Wait for success toast

Why it mattered: Caught form submission issues, timing problems, and missing UI elements.

Common Workflows

Testing a PDF Upload Dialog

# 1. Navigate to the page
/browser open http://localhost:3000/summary-charges/add-charges?brand=TCT

# 2. Click "Import from PDF" button
/browser click "button:has-text('Import from PDF')"

# 3. Select instruction set from dropdown
/browser select "select.instruction-select" "Standard Warehouse Format"

# 4. Upload PDF file
/browser upload "input[type='file']" "~/Downloads/misen.pdf"

# 5. Click extract button
/browser click "button:has-text('Extract Charges')"

# 6. Wait for completion and verify
/browser wait ".success-toast" --timeout 30000
/browser screenshot
/browser inspect "table[data-testid='extracted-charges']"

Testing Instructions Management

# Navigate to instructions page
/browser open http://localhost:3000/instructions

# Click "New Instruction Set"
/browser click "button:has-text('New Instruction Set')"

# Fill form fields
/browser fill "input[name='name']" "Test Warehouse Format"
/browser fill "textarea[name='instructions']" "## Invoice Structure\n- Invoice number: Top-right"

# Add biller tag
/browser click "button:has-text('Add Biller')"
/browser fill ".tag-input" "XPO Logistics"
/browser click "button:has-text('Add Tag')"

# Submit form
/browser click "button[type='submit']"

# Verify success
/browser wait ".success-toast"
/browser screenshot

Debugging Page State

# Open page with issues
/browser open http://localhost:3000/summary-charges

# Inspect critical elements
/browser inspect "dialog"
/browser inspect "select"
/browser inspect "button[type='submit']"

# Take screenshots
/browser screenshot

# Verify form state
/browser inspect "form[data-testid='pdf-upload-form']"

Element Selectors

The skill supports multiple selector formats:

• CSS selectors: button.primary, input[data-testid='email']
• Text matching: button:has-text('Submit'), div:has-text('Error')
• Data attributes: [data-testid='submit'], [data-id='123']
• XPath (when needed): Complex element queries

Command Details

navigate

Move to a new URL in the current session

/browser navigate http://localhost:3000/new-page

click

Click an element and capture the result

/browser click ".submit-button"

fill

Enter text into an input field

/browser fill "input[name='username']" "testuser"
/browser fill ".search-box" "query text"

select

Choose an option from a dropdown

/browser select "select[name='option']" "Option Value"

wait

Poll for element appearance with optional timeout (default 5000ms)

/browser wait ".modal-content" --timeout 10000

inspect

Extract element structure and content information

/browser inspect ".data-table"

upload

Submit a file through a file input

/browser upload "input[type='file']" "~/path/to/file.pdf"

Tips & Best Practices

1. Always start with open - Initialize the browser session before other commands
2. Use specific selectors - Prefer data-testid attributes over generic selectors
3. Check screenshots between steps - Verify page state after interactions
4. Increase timeout for slow operations - PDF extraction may need 30-60 seconds
5. Use inspect to understand page structure - Before clicking/filling, inspect the element
6. Handle async operations - Use wait for dynamically loaded content
7. Use text matching for buttons - button:has-text('Submit') is often more reliable

Example: Complete Feature Test

# Phase 1: Setup
/browser open http://localhost:3000/summary-charges/add-charges?brand=TCT

# Phase 2: Verify UI loaded
/browser inspect ".dialog-header"
/browser screenshot

# Phase 3: Test 3PL selector
/browser click "button:has-text('Import from PDF')"
/browser screenshot

# Phase 4: Select instruction set
/browser select ".instruction-select" "XPO Warehouse"
/browser screenshot

# Phase 5: Upload PDF
/browser upload "input[type='file']" "~/Downloads/test.pdf"
/browser screenshot

# Phase 6: Trigger extraction
/browser click "button:has-text('Extract Charges')"

# Phase 7: Wait and verify
/browser wait ".extracted-charges-table" --timeout 30000
/browser screenshot
/browser inspect "table"

Login / Auth Flows

When a page requires authentication before automation can proceed:

1. Find the correct display: echo $DISPLAY
2. Open system Chromium visibly: DISPLAY=:1 chromium http://localhost:3000 &
3. Wait for the user to log in — ask them to confirm when done.
4. Resume headless automation with agent-browser open <url> — the session is independent, so if the app uses cookies you may need to pass them via --headers or agent-browser cookies set.

Do NOT use agent-browser open --headed for this — it does not produce a visible window on Linux.

Troubleshooting

Element not found:

• Check the selector syntax
• Use inspect to understand the page structure
• Try text matching instead of specific selectors

Click/fill not working:

• Ensure element is visible and clickable
• Check if element requires scrolling into view
• Verify element is not disabled or hidden

Timeout waiting for element:

• Increase the timeout value
• Check console for JavaScript errors
• Use screenshot to see current page state

File upload fails:

• Verify file path exists (use absolute or ~/ paths)
• Check file input accepts the file type
• Ensure upload input is visible and accessible

Integration with Development

This skill works best when:

• You have a dev server running (e.g., pnpm run dev)
• You know the URLs to test (localhost ports documented in project)
• You have test files available (PDFs, images, etc.)
• You're iterating on UI features and need quick verification

Use this skill in Claude Code workflows to:

1. Verify UI changes work as expected
2. Debug form interactions
3. Test file upload functionality
4. Screenshot progress for documentation
5. Validate workflow sequences