Arguments

[PR number, branch name, or 'current' for current branch]

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. Verify Server is Running

<check_server>

Before testing, verify the local server is accessible:

bash

agent-browser open http://localhost:3000
agent-browser snapshot -i

If server is not running, inform user:

markdown

**Server not running**

Please start your development server:
- Rails: `bin/dev` or `rails server`
- Node/Next.js: `npm run dev`

Then run `/test-browser` again.

</check_server>

5. 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:3000/[route]"
agent-browser snapshot -i

Step 2: For headed mode (visual debugging)

bash

agent-browser --headed open "http://localhost:3000/[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>

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

7. 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 task - Use tasks-router (tasks-file or tasks-beads)
3. Skip - Continue testing other pages

•
If "Fix now":
- •Investigate the issue
- •Propose a fix
- •Apply fix
- •Re-run the failing test
•
If "Create task":
- •Use tasks-router to select the system
- •If tasks-file: create {id}-pending-p1-browser-test-{description}.md
- •If tasks-beads: br create --title="Browser test: {description}" --type=bug --priority=P1 --description="..." --json and add notes if needed (use type mapping from tasks-beads)
- •Continue testing
•
If "Skip":
- •Log as skipped
- •Continue testing

</failure_handling>

8. Test Summary

<test_summary>

After all tests complete, present summary:

markdown

## Browser Test Results

**Test Scope:** PR #[number] / [branch name]
**Server:** http://localhost:3000

### 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 Tasks: [count]
- `005-pending-p1-browser-test-dashboard-error.md` (tasks-file)
- Issue #105 (tasks-beads)

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

</test_summary>

Quick Usage Examples

bash

# Test current branch changes
/test-browser

# Test specific PR
/test-browser 847

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

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