Playwright CLI expert for E2E testing and browser automation. Use when users need to record tests, debug issues, generate reports, or test across multiple browsers and devices.
/plugin marketplace add leobrival/topographic-plugins-official/plugin install dev@topographic-plugins-officialThis skill inherits all available tools. When active, it can use any tool Claude has access to.
reference/commands-reference.mdreference/common-patterns.mdreference/troubleshooting.mdPlaywright is a testing framework for automating browser interactions across multiple browsers (Chrome, Firefox, WebKit) and devices. This guide provides essential workflows and quick references for test execution, debugging, and debugging.
# Install Playwright
npm install -D @playwright/test
# Install browsers
npx playwright install
# Run your first tests
npx playwright test
# Run with visible browser
npx playwright test --headed
# Debug with Inspector UI
npx playwright test --debug
# View test report
npx playwright show-report
# Record interaction with website
npx playwright codegen https://example.com -o tests/recorded.spec.ts
# Run the recorded test
npx playwright test tests/recorded.spec.ts
# Run with browser visible
npx playwright test tests/recorded.spec.ts --headed
# Update and verify
npx playwright test tests/recorded.spec.ts --debug
# Run failing test with browser visible
npx playwright test -g "test name" --headed
# Open debugger Inspector
npx playwright test -g "test name" --debug
# Capture screenshot for inspection
npx playwright test --screenshot=on
# Record trace for detailed analysis
npx playwright test --trace on
npx playwright show-trace trace.zip
# Run on all configured browsers
npx playwright test
# Run on specific browser
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit
# Run on mobile devices
npx playwright test --project="iPhone 12"
npx playwright test --project="Pixel 5"
# Run tests with multiple reports
npx playwright test --reporter=html --reporter=json --reporter=verbose
# View HTML report
npx playwright show-report
# Generate CI-compatible reports
npx playwright test --reporter=github --reporter=json --retries=2
# Run sequentially for consistent timing
npx playwright test --workers=1
# With extended timeout
npx playwright test --workers=1 --timeout=30000
# Record traces for analysis
npx playwright test --workers=1 --trace on
# View performance insights
npx playwright show-trace trace.zip
When to use which command:
npx playwright codegen URLnpx playwright test (all) or npx playwright test -g "pattern" (specific)npx playwright test --debug (Inspector) or --headed (visible browser)--project=chromium, --project=firefox, or --project=webkit--screenshot=on or --video=on--trace on or --reporter=html--retries=3 or run with --workers=1# Run on specific browser
npx playwright test --project=chromium
# Run on multiple browsers
npx playwright test --project=chromium --project=firefox
# Run on mobile
npx playwright test --project="iPhone 12" --project="Pixel 5"
# Override base URL for environment
npx playwright test --base-url=https://staging.example.com
# Visual debugging with browser visible
npx playwright test --headed --workers=1
# Interactive debugging with Inspector
npx playwright test --debug
# Detailed trace recording
npx playwright test --trace on
npx playwright show-trace trace.zip
# Full debugging output
npx playwright test --reporter=verbose --headed --debug
# Screenshots on failure
npx playwright test --screenshot=only-on-failure
# Always record videos
npx playwright test --video=on
# Multiple report formats
npx playwright test --reporter=html --reporter=json --reporter=junit
# View HTML report
npx playwright show-report
# Parallel execution (faster)
npx playwright test --workers=4
# Sequential execution (deterministic)
npx playwright test --workers=1
# Retry flaky tests
npx playwright test --retries=2
# Extended timeout for slow networks
npx playwright test --timeout=30000
Common Issues:
Browser won't start
npx playwright install --with-depsTests time out
npx playwright test --timeout=30000Tests are flaky
npx playwright test --retries=3 or --workers=1Page won't load
Element not found
getByRole() or getByTestId()For detailed troubleshooting steps, see the Troubleshooting Guide.
Load as needed for detailed information:
Commands Reference - Complete CLI command documentation with all flags and options. Use when you need exact syntax, flag combinations, or comprehensive command information.
Common Patterns - Real-world patterns and workflows for development, cross-browser testing, mobile devices, visual testing, CI/CD, performance testing, and debugging. Use for implementing specific workflows or integrations.
Troubleshooting Guide - Detailed error messages, diagnosis steps, and resolution strategies for installation, browser issues, test failures, selectors, reports, CI/CD, and debugging techniques. Use when encountering errors or unexpected behavior.
When to use each reference:
npx playwright codegennpx playwright test --debugThis skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.