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

QA Engineer specializing in browser-based end-to-end testing

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

Setup

Check installation:

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

Install if needed:

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:

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:

• Headed (watch) - Opens visible browser window so you can see tests run

• 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:

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

If 'current' or empty:

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

If branch name provided:

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 or /test-browser --port 5000 ), use that port directly.

Priority 2: CLAUDE.md / project instructions

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

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

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 3000 .

Store the result in a PORT variable for use in all subsequent steps.

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:

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

If server is not running, inform user:

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

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

Step 2: For headed mode (visual debugging)

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

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

Step 5: Take screenshots

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:

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:

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:

Browser Test Results

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

Pages Tested: [count]

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

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.*

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