test-browser

Browser Test Skill

Run end-to-end browser tests on pages affected by a PR or branch changes using the agent-browser CLI.

Use `agent-browser` Only For Browser Automation

This workflow uses the agent-browser CLI exclusively. Do not use any alternative browser automation system, browser MCP integration, or built-in browser-control tool. If the platform offers multiple ways to control a browser, always choose agent-browser.

Use agent-browser for: opening pages, clicking elements, filling forms, taking screenshots, and scraping rendered content.

Platform-specific hints:

In Codex, do not use Chrome MCP tools (mcp__claude-in-chrome__*).
In Codex, do not substitute unrelated browsing tools.

Prerequisites

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

Setup

Check whether agent-browser is installed:

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

If not installed, inform the user: "agent-browser is not installed. Run /ce-setup to install required dependencies." Then stop — this skill cannot function without agent-browser.

Workflow

1. Verify Installation

Before starting, verify agent-browser is available:

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

If not installed, inform the user and stop.

2. Ask Browser Mode

Ask the user whether to run headed or headless:

Do you want to watch the browser tests run?

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 the --headed flag when the user selects option 1.

3. Determine Test 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]

4. Map Files to Routes

Map changed files to testable routes:

File Pattern	Route(s)
`src/app/*` (Next.js)	Corresponding routes
`src/components/*`	Pages using those components
`src/features/*`	Feature-related pages
`src/views/*`	Corresponding routes

5. Detect Dev Server Port

Determine the dev server port using this priority:

Explicit argument — if the user passed --port 5000, use that directly
Project instructions — check AGENTS.md for port references
package.json — check dev/start scripts for --port flags
Environment files — check .env, .env.local, .env.development for PORT=
Default — fall back to 3000

6. Verify Server is Running

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

7. Test Each Affected Page

For each affected route:

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

Verify key elements:

Page title/heading present
Primary content rendered
No error messages visible

8. Handle Failures

Screenshot errors and ask the user how to proceed (fix now, create todo, or skip).

9. Test Summary

Present a markdown summary of pages tested, failures, and result (PASS/FAIL/PARTIAL).

agent-browser CLI Reference

agent-browser open <url>           # Navigate to URL
agent-browser snapshot -i          # Interactive elements with refs
agent-browser click @e1            # Click element
agent-browser fill @e1 "text"      # Fill input
agent-browser screenshot out.png   # Screenshot
agent-browser --headed open <url>  # Headed mode