test-browser

Browser Test

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

Positioning (ADR-049, #4834): for structural-UI diffs (nav/rail/dashboard shell), the pre-merge visual check is now the committed, CI-blocking nav-states-*.e2e.ts gate run by /soleur:qa Step 2.6 — not this skill. Running test-browser only after ship is the deferral trap that let the #4810 layout bugs reach prod. Treat this skill as a post-ship smoke (broad page reachability + console-error sweep) that complements, never replaces, the pre-merge /soleur:qa gate.

CRITICAL: Use agent-browser CLI Only

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

This skill 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 calling mcp__claude-in-chrome__* tools, STOP. Use agent-browser Bash commands instead.

• When working in a worktree, always pass absolute paths to Playwright MCP screenshot tools -- relative filenames are resolved from the main repo root (the MCP server's CWD), so screenshots land in the main repo instead of the active worktree.

Introduction

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

This skill 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:

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

Install if needed:

npm install --prefix ~/.local -g agent-browser@0.22.3
agent-browser install  # Downloads Chrome for Testing (~300MB)

On Linux (Ubuntu 23.10+, containers, VMs), export the no-sandbox launch flag before the first command — otherwise Chrome cannot launch and open hangs:

export AGENT_BROWSER_ARGS="--no-sandbox"

See the agent-browser skill for detailed usage and the "Chrome fails to launch / open hangs" troubleshooting entry.

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 --prefix ~/.local -g agent-browser@0.22.3 && agent-browser install)

If installation fails, inform the user and stop.

1. Ask Browser Mode

<ask_browser_mode>

Before starting tests, ask the 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 tests can be observed
• 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. 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 the 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

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

Step 2: For headed mode (visual debugging)

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

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>

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 inbox for the test email and confirm receipt" | | Payments | "Complete a test purchase in sandbox mode" | | SMS | "Verify the SMS code was received" | | 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>

7. Handle Failures

<failure_handling>

When a test fails:

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

1. Ask user how to proceed:

```markdown Test Failed: [route]

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

How to proceed?

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

```

1. If "Fix now":
2. Investigate the issue
3. Propose a fix
4. Apply fix
5. Re-run the failing test

1. If "Create todo":
2. Create {id}-pending-p1-browser-test-{description}.md
3. Continue testing

1. If "Skip":
2. Log as skipped
3. Continue testing

</failure_handling>

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

9. Cleanup

<cleanup>

Pla