Browser Test Command

<command_purpose>Run end-to-end browser tests on pages affected by a PR or branch changes using agent-browser CLI.</command_purpose>

CRITICAL: Use agent-browser CLI Only

DO NOT use Chrome MCP tools (mcp__claude-in-chrome__*).

This command uses the

agent-browser

CLI exclusively. The agent-browser CLI is a Bash-based tool from Vercel that runs headless Chromium. It is NOT the same as Chrome browser automation via MCP.

If you find yourself calling

mcp__claude-in-chrome__*

tools, STOP. Use

agent-browser

Bash commands instead.

Introduction

<role>QA Engineer specializing in browser-based end-to-end testing</role>

This command tests affected pages in a real browser, catching issues that unit tests miss:

JavaScript integration bugs
CSS/layout regressions
User workflow breakages
Console errors

Prerequisites

<requirements> - Local development server running (e.g., `bin/dev`, `rails server`, `npm run dev`) - agent-browser CLI installed (see Setup below) - Git repository with changes to test </requirements>

Setup

Check installation:

bash

command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"

Install if needed:

bash

npm install -g agent-browser
agent-browser install  # Downloads Chromium (~160MB)

See the

agent-browser

skill for detailed usage.

Main Tasks

0. Verify agent-browser Installation

Before starting ANY browser testing, verify agent-browser is installed:

bash

command -v agent-browser >/dev/null 2>&1 && echo "Ready" || (echo "Installing..." && npm install -g agent-browser && agent-browser install)

If installation fails, inform the user and stop.

1. Ask Browser Mode

<ask_browser_mode>

Before starting tests, ask user if they want to watch the browser:

Use AskUserQuestion with:

Question: "Do you want to watch the browser tests run?"
Options:
1. Headed (watch) - Opens visible browser window so you can see tests run
2. Headless (faster) - Runs in background, faster but invisible

Store the choice and use

--headed

flag when user selects "Headed".

</ask_browser_mode>

2. Determine Test Scope

<test_target> $ARGUMENTS </test_target>

<determine_scope>

If PR number provided:

bash

gh pr view [number] --json files -q '.files[].path'

If 'current' or empty:

bash

git diff --name-only main...HEAD

If branch name provided:

bash

git diff --name-only main...[branch]

</determine_scope>

3. Map Files to Routes

<file_to_route_mapping>

Map changed files to testable routes:

File Pattern	Route(s)
`app/views/users/*`	`/users` , `/users/:id` , `/users/new`
`app/controllers/settings_controller.rb`	`/settings`
`app/javascript/controllers/*_controller.js`	Pages using that Stimulus controller
`app/components/*_component.rb`	Pages rendering that component
`app/views/layouts/*`	All pages (test homepage at minimum)
`app/assets/stylesheets/*`	Visual regression on key pages
`app/helpers/*_helper.rb`	Pages using that helper
`src/app/*` (Next.js)	Corresponding routes
`src/components/*`	Pages using those components

Build a list of URLs to test based on the mapping.

</file_to_route_mapping>

4. Detect Dev Server Port

<detect_port>

Determine the dev server port using this priority order:

Priority 1: Explicit argument If the user passed a port number (e.g.,

/test-browser 5000

/test-browser --port 5000

), use that port directly.

Priority 2: CLAUDE.md / project instructions

bash

# Check CLAUDE.md for port references
grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1

Priority 3: package.json scripts

bash

# Check dev/start scripts for --port flags
grep -Eo '\-\-port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1

Priority 4: Environment files

bash

# Check .env, .env.local, .env.development for PORT=
grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2

Priority 5: Default fallback If none of the above yields a port, default to

Store the result in a

PORT

variable for use in all subsequent steps.

bash

# Combined detection (run this)
PORT="${EXPLICIT_PORT:-}"
if [ -z "$PORT" ]; then
  PORT=$(grep -Eio '(port\s*[:=]\s*|localhost:)([0-9]{4,5})' CLAUDE.md 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
fi
if [ -z "$PORT" ]; then
  PORT=$(grep -Eo '\-\-port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
fi
if [ -z "$PORT" ]; then
  PORT=$(grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2)
fi
PORT="${PORT:-3000}"
echo "Using dev server port: $PORT"

</detect_port>

5. Verify Server is Running

<check_server>

Before testing, verify the local server is accessible using the detected port:

bash

agent-browser open http://localhost:${PORT}
agent-browser snapshot -i

If server is not running, inform user:

markdown

**Server not running on port ${PORT}**

Please start your development server:
- Rails: `bin/dev` or `rails server`
- Node/Next.js: `npm run dev`
- Custom port: `/test-browser --port <your-port>`

Then run `/test-browser` again.

</check_server>

6. Test Each Affected Page

<test_pages>

For each affected route, use agent-browser CLI commands (NOT Chrome MCP):

Step 1: Navigate and capture snapshot

bash

agent-browser open "http://localhost:${PORT}/[route]"
agent-browser snapshot -i

Step 2: For headed mode (visual debugging)

bash

agent-browser --headed open "http://localhost:${PORT}/[route]"
agent-browser --headed snapshot -i

Step 3: Verify key elements

Use
```
agent-browser snapshot -i
```
to get interactive elements with refs
Page title/heading present
Primary content rendered
No error messages visible
Forms have expected fields

Step 4: Test critical interactions

bash

agent-browser click @e1  # Use ref from snapshot
agent-browser snapshot -i

Step 5: Take screenshots

bash

agent-browser screenshot page-name.png
agent-browser screenshot --full page-name-full.png  # Full page

</test_pages>

7. Human Verification (When Required)

<human_verification>

Pause for human input when testing touches:

Flow Type	What to Ask
OAuth	"Please sign in with [provider] and confirm it works"
Email	"Check your inbox for the test email and confirm receipt"
Payments	"Complete a test purchase in sandbox mode"
SMS	"Verify you received the SMS code"
External APIs	"Confirm the [service] integration is working"

Use AskUserQuestion:

markdown

**Human Verification Needed**

This test touches the [flow type]. Please:
1. [Action to take]
2. [What to verify]

Did it work correctly?
1. Yes - continue testing
2. No - describe the issue

</human_verification>

8. Handle Failures

<failure_handling>

When a test fails:

Document the failure:
- Screenshot the error state:
```
agent-browser screenshot error.png
```
- Note the exact reproduction steps

Ask user how to proceed:

markdown

**Test Failed: [route]**

Issue: [description]
Console errors: [if any]

How to proceed?
1. Fix now - I'll help debug and fix
2. Create todo - Add to todos/ for later
3. Skip - Continue testing other pages

If "Fix now":
- Investigate the issue
- Propose a fix
- Apply fix
- Re-run the failing test

If "Create todo":

Create

{id}-pending-p1-browser-test-{description}.md

Continue testing

If "Skip":
- Log as skipped
- Continue testing

</failure_handling>

9. Test Summary

<test_summary>

After all tests complete, present summary:

markdown

## Browser Test Results

**Test Scope:** PR #[number] / [branch name]
**Server:** http://localhost:${PORT}

### Pages Tested: [count]

| Route | Status | Notes |
|-------|--------|-------|
| `/users` | Pass | |
| `/settings` | Pass | |
| `/dashboard` | Fail | Console error: [msg] |
| `/checkout` | Skip | Requires payment credentials |

### Console Errors: [count]
- [List any errors found]

### Human Verifications: [count]
- OAuth flow: Confirmed
- Email delivery: Confirmed

### Failures: [count]
- `/dashboard` - [issue description]

### Created Todos: [count]
- `005-pending-p1-browser-test-dashboard-error.md`

### Result: [PASS / FAIL / PARTIAL]

</test_summary>

Quick Usage Examples

bash

# Test current branch changes (auto-detects port)
/test-browser

# Test specific PR
/test-browser 847

# Test specific branch
/test-browser feature/new-dashboard

# Test on a specific port
/test-browser --port 5000

agent-browser CLI Reference

ALWAYS use these Bash commands. NEVER use mcp__claude-in-chrome__ tools.*

bash

# Navigation
agent-browser open <url>           # Navigate to URL
agent-browser back                 # Go back
agent-browser close                # Close browser

# Snapshots (get element refs)
agent-browser snapshot -i          # Interactive elements with refs (@e1, @e2, etc.)
agent-browser snapshot -i --json   # JSON output

# Interactions (use refs from snapshot)
agent-browser click @e1            # Click element
agent-browser fill @e1 "text"      # Fill input
agent-browser type @e1 "text"      # Type without clearing
agent-browser press Enter          # Press key

# Screenshots
agent-browser screenshot out.png       # Viewport screenshot
agent-browser screenshot --full out.png # Full page screenshot

# Headed mode (visible browser)
agent-browser --headed open <url>      # Open with visible browser
agent-browser --headed click @e1       # Click in visible browser

# Wait
agent-browser wait @e1             # Wait for element
agent-browser wait 2000            # Wait milliseconds

test-browser

NPX Install

Tags

SKILL.md Content

Browser Test Command

CRITICAL: Use agent-browser CLI Only

Introduction

Prerequisites

Setup

Main Tasks

0. Verify agent-browser Installation

1. Ask Browser Mode

2. Determine Test Scope

3. Map Files to Routes

4. Detect Dev Server Port

5. Verify Server is Running

6. Test Each Affected Page

7. Human Verification (When Required)

8. Handle Failures

9. Test Summary

Quick Usage Examples

agent-browser CLI Reference