feat: Replace Playwright MCP with agent-browser CLI
- Remove Playwright MCP server from plugin - Add new agent-browser skill for CLI-based browser automation - Rename /playwright-test to /test-browser command - Update all commands and agents to use agent-browser CLI - Update README and plugin.json agent-browser is Vercel's headless browser CLI designed for AI agents. It uses ref-based selection (@e1, @e2) from accessibility snapshots and provides a simpler CLI interface compared to MCP tools. Key benefits: - No MCP server required - Simpler Bash-based workflow - Same ref-based element selection - Better for quick automation tasks 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
274
plugins/compound-engineering/commands/test-browser.md
Normal file
274
plugins/compound-engineering/commands/test-browser.md
Normal file
@@ -0,0 +1,274 @@
|
||||
---
|
||||
name: test-browser
|
||||
description: Run browser tests on pages affected by current PR or branch
|
||||
argument-hint: "[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
|
||||
|
||||
<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`)
|
||||
- agent-browser CLI installed
|
||||
- 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
|
||||
```
|
||||
|
||||
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:**
|
||||
```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>
|
||||
|
||||
### 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:
|
||||
|
||||
```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: `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**
|
||||
```bash
|
||||
agent-browser open "http://localhost:3000/[route]"
|
||||
agent-browser snapshot -i
|
||||
```
|
||||
|
||||
**Step 2: Check for errors** (use headed mode for console inspection)
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
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:
|
||||
```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>
|
||||
|
||||
### 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:**
|
||||
```markdown
|
||||
**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:
|
||||
|
||||
```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 Todos: [count]
|
||||
- `005-pending-p1-browser-test-dashboard-error.md`
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## Key agent-browser Commands
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user