claude-engineering-plugin/plugins/compound-engineering/commands/test-browser.md

name, description, argument-hint

name	description	argument-hint
test-browser	Run browser tests on pages affected by current PR or branch	[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>

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

- Local development server running (e.g., `bin/dev`, `rails server`) - agent-browser CLI installed - Git repository with changes to test

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

See the agent-browser skill for detailed usage.

Main Tasks

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

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

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

</file_to_route_mapping>

3. Verify Server is Running

<check_server>

Before testing, verify the local server is accessible:

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

If server is not running, inform user:

**Server not running**

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

Then run `/test-browser` again.

</check_server>

4. Test Each Affected Page

<test_pages>

For each affected route:

Step 1: Navigate and capture snapshot

agent-browser open "http://localhost:3000/[route]"
agent-browser snapshot -i

Step 2: Check for errors (use headed mode for console inspection)

agent-browser --headed open "http://localhost:3000/[route]"

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

</test_pages>

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

6. Handle Failures

<failure_handling>

When a test fails:

1. Document the failure:

   • Screenshot the error state: agent-browser screenshot error.png
   • Note the exact reproduction steps

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

3. If "Fix now":

   • Investigate the issue
   • Propose a fix
   • Apply fix
   • Re-run the failing test

4. If "Create todo":

   • Create {id}-pending-p1-browser-test-{description}.md
   • Continue testing

5. If "Skip":

   • Log as skipped
   • Continue testing

</failure_handling>

7. Test Summary

<test_summary>

After all tests complete, present summary:

## 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 Todos: [count]
- `005-pending-p1-browser-test-dashboard-error.md`

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

</test_summary>

Quick Usage Examples

# Test current branch changes
/test-browser

# Test specific PR
/test-browser 847

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

Key agent-browser Commands

agent-browser open <url>           # Navigate
agent-browser snapshot -i          # Interactive elements with refs
agent-browser click @e1            # Click by ref
agent-browser fill @e1 "text"      # Fill input
agent-browser screenshot out.png   # Screenshot
agent-browser --headed open <url>  # Visible browser