| name | browser-test |
| description | Run comprehensive Playwright browser tests across desktop, tablet, and mobile viewports. Auto-discovers pages and tests navigation, forms, auth, CRUD, responsive behavior, interactive elements, error states, user flows, and performance metrics. |
| hooks | {"SubagentStart":[{"matcher":".*","hooks":[{"type":"command","command":"echo \"\"\ncase \"$AGENT_TYPE\" in\n \"codebase-explorer\") echo \" 🔍 Discovering application routes and pages...\" ;;\n \"test-writer\") echo \" 🧪 Generating Playwright test scripts...\" ;;\n \"debugger\") echo \" 🐛 Debugging test failures...\" ;;\n *) echo \" 🤖 Running: $AGENT_TYPE\" ;;\nesac\n"}]}],"SubagentStop":[{"hooks":[{"type":"command","command":"echo ' ✓ Complete'"}]}],"Stop":[{"hooks":[{"type":"prompt","prompt":"Verify that /browser-test completed all required phases:\n\n1. Phase 1 (Setup):\n - Was Playwright installed or verified?\n - Was the playwright.config.ts generated?\n\n2. Phase 2 (Discovery):\n - Were application routes/pages discovered?\n - Were testable features identified?\n\n3. Phase 3 (Test Generation):\n - Were test spec files generated?\n\n4. Phase 4 (Execution):\n - Were tests run across all 3 viewports?\n - Were screenshots captured?\n\n5. Phase 5 (Report):\n - Was the test report generated?\n\nContext: $ARGUMENTS\n\nReturn {\"ok\": true} if all phases completed.\nReturn {\"ok\": false, \"reason\": \"specific issue\"} if incomplete.\n","timeout":30}]}]} |
Browser Test Skill
Run comprehensive Playwright browser tests across desktop, tablet, and mobile viewports.
When to Use
Invoke with /browser-test when you need to:
- Test your web application across multiple screen sizes
- Verify responsive behavior and mobile compatibility
- Test user flows and common interactions
- Capture screenshots at different viewports
- Check performance metrics (LCP, CLS, INP)
Usage
/browser-test <port> [target]
Arguments:
port (required) - Port the app is running on (e.g., 3000, 8080)
target (optional) - Specific page (/dashboard), flow type (auth, forms, crud), or all (default)
Examples:
/browser-test 3000
/browser-test 3000 /dashboard
/browser-test 3000 auth
/browser-test 8080 all
Instructions
Phase 1: Setup and Validation
PORT="$1"
TARGET="${2:-all}"
if [ -z "$PORT" ]; then
echo "❌ Error: Port number is required"
echo ""
echo "Usage: /browser-test <port> [page-or-feature|all]"
echo ""
echo "Examples:"
echo " /browser-test 3000"
echo " /browser-test 3000 all"
echo " /browser-test 3000 /dashboard"
echo " /browser-test 3000 auth"
exit 1
fi
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "🎭 Browser Testing with Playwright"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "Target: http://localhost:$PORT"
echo "Scope: $TARGET"
echo "Viewports: Desktop (1920x1080), Tablet (768x1024), Mobile (375x812)"
echo ""
echo "📡 Checking if app is running on port $PORT..."
if command -v curl > /dev/null 2>&1; then
if curl -s -o /dev/null -w "%{http_code}" "http://localhost:$PORT" | grep -q "^[23]"; then
echo "✓ App is reachable at http://localhost:$PORT"
else
echo "⚠️ Warning: Could not reach http://localhost:$PORT"
echo " Make sure your app is running before continuing"
echo ""
fi
else
echo "⚠️ curl not found, skipping reachability check"
echo " Make sure your app is running at http://localhost:$PORT"
echo ""
fi
echo ""
echo "🔍 Checking Playwright installation..."
if npx playwright --version > /dev/null 2>&1; then
PLAYWRIGHT_VERSION=$(npx playwright --version)
echo "✓ Playwright found: $PLAYWRIGHT_VERSION"
else
echo "📦 Playwright not found. Installing..."
if [ ! -f "package.json" ]; then
npm init -y > /dev/null 2>&1
fi
npm install --save-dev @playwright/test
npx playwright install chromium
echo "✓ Playwright installed successfully"
fi
echo ""
echo "📁 Setting up test directory structure..."
mkdir -p browser-tests/tests
mkdir -p browser-tests/screenshots/desktop
mkdir -p browser-tests/screenshots/tablet
mkdir -p browser-tests/screenshots/mobile
mkdir -p browser-tests/reports
echo "✓ Directory structure created"
echo ""
Phase 2: Route and Feature Discovery
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Phase 2: Discovering Routes and Features"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
FRAMEWORK="unknown"
echo "🔍 Detecting framework..."
if [ -d "app" ] && ([ -f "next.config.js" ] || [ -f "next.config.ts" ] || [ -f "next.config.mjs" ]); then
FRAMEWORK="nextjs-app-router"
echo "✓ Detected: Next.js (App Router)"
elif [ -d "pages" ] && ([ -f "next.config.js" ] || [ -f "next.config.ts" ]); then
FRAMEWORK="nextjs-pages-router"
echo "✓ Detected: Next.js (Pages Router)"
elif [ -f "nuxt.config.ts" ] || [ -f "nuxt.config.js" ]; then
FRAMEWORK="nuxt"
echo "✓ Detected: Nuxt"
elif [ -f "vite.config.ts" ] || [ -f "vite.config.js" ]; then
FRAMEWORK="vite-spa"
echo "✓ Detected: Vite SPA"
elif [ -f "angular.json" ]; then
FRAMEWORK="angular"
echo "✓ Detected: Angular"
elif [ -d "src" ] && grep -q "react-router" package.json 2>/dev/null; then
FRAMEWORK="react-router"
echo "✓ Detected: React Router"
elif [ -d "src" ] && grep -q "vue-router" package.json 2>/dev/null; then
FRAMEWORK="vue-router"
echo "✓ Detected: Vue Router"
else
echo "⚠️ Framework not auto-detected, will use runtime crawling"
fi
echo ""
echo "🗺️ Discovering routes and features..."
echo ""
echo ""
Phase 3: Test Generation
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Phase 3: Generating Test Scripts"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "📝 Generating playwright.config.ts..."
cat > browser-tests/playwright.config.ts << 'PLAYWRIGHT_CONFIG_EOF'
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
outputDir: './test-results',
fullyParallel: false, // Sequential for predictable screenshots
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 1,
workers: 1, // Run one test at a time
timeout: 30000,
use: {
baseURL: `http://localhost:${PORT}`,
screenshot: 'only-on-failure',
trace: 'retain-on-failure',
},
projects: [
{
name: 'desktop',
use: {
viewport: { width: 1920, height: 1080 },
...devices['Desktop Chrome'],
},
},
{
name: 'tablet',
use: {
viewport: { width: 768, height: 1024 },
...devices['iPad Mini'],
},
},
{
name: 'mobile',
use: {
viewport: { width: 375, height: 812 },
...devices['iPhone 13'],
},
},
],
reporter: [
['json', { outputFile: './reports/test-results.json' }],
['html', { outputFolder: './reports/html', open: 'never' }],
['list'],
],
});
PLAYWRIGHT_CONFIG_EOF
sed -i "s/\${PORT}/$PORT/g" browser-tests/playwright.config.ts
echo "✓ Config generated"
echo ""
echo "✓ Generated: tests/navigation.spec.ts"
echo "✓ Generated: tests/forms.spec.ts"
echo ""
Phase 4: Test Execution
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Phase 4: Running Tests"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
cd browser-tests
echo "🧪 Running Playwright tests across 3 viewports..."
echo " This may take a few minutes..."
echo ""
npx playwright test
TEST_EXIT_CODE=$?
echo ""
if [ $TEST_EXIT_CODE -eq 0 ]; then
echo "✅ All tests passed!"
else
echo "⚠️ Some tests failed. See report for details."
echo ""
fi
cd ..
echo ""
Phase 5: Report Generation
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Phase 5: Generating Report"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "📊 Generating test report..."
echo "✓ Report generated: browser-tests/reports/test-report.md"
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "✅ Browser Testing Complete"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "📄 View report:"
echo " browser-tests/reports/test-report.md"
echo ""
echo "🖼️ Screenshots:"
echo " browser-tests/screenshots/{desktop,tablet,mobile}/"
echo ""
echo "🔄 Re-run tests:"
echo " cd browser-tests && npx playwright test"
echo ""
echo "🎭 Debug with UI:"
echo " cd browser-tests && npx playwright test --ui"
echo ""
Quick Reference
| Phase | Action | Key Output |
|---|
| 1 | Setup | Playwright installed, directories created |
| 2 | Discovery | Routes and features identified |
| 3 | Generation | Test spec files created |
| 4 | Execution | Tests run across 3 viewports |
| 5 | Report | Markdown report with results and recommendations |
Notes
- Tests run sequentially (not parallel) for predictable screenshots
- Only Chromium is installed (not Firefox/WebKit) for speed
- Tests are saved to the project (not the skill) so users can re-run them
- Screenshots captured at key steps in each test flow
- Performance metrics measured using Web Vitals API
- User flows test end-to-end journeys based on detected features
- Report includes specific recommendations for fixing failures