zebbern/claude-code-guide / skills/playwright/playwright-cli
playwright-cli
UnverifiedAutomates browser interactions for web testing, form filling, screenshots, and data extraction using playwright-cli. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, extract information from web pages, mock network requests, manage browser sessions, or generate test code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.3 KB |
| advanced-workflows.md | markdown | 18.3 KB |
| core-commands.md | markdown | 10.6 KB |
| device-emulation.md | markdown | 13.1 KB |
| request-mocking.md | markdown | 10.4 KB |
| running-custom-code.md | markdown | 14.8 KB |
| screenshots-and-media.md | markdown | 10.3 KB |
| session-management.md | markdown | 9.5 KB |
| storage-and-auth.md | markdown | 11.2 KB |
| test-generation.md | markdown | 11.1 KB |
| tracing-and-debugging.md | markdown | 12.1 KB |
tracing-and-debugging.md
View on GitHub# Tracing and Debugging
> **When to use**: Debugging failing actions, analyzing performance bottlenecks, capturing execution evidence, understanding why an interaction didn't work, or inspecting network and console activity during automation.
> **Prerequisites**: [core-commands.md](core-commands.md) for basic CLI usage
## Quick Reference
```bash
# Trace a session
playwright-cli tracing-start
playwright-cli open https://example.com
playwright-cli click e4
playwright-cli fill e7 "test"
playwright-cli tracing-stop
# View console messages
playwright-cli console # All levels
playwright-cli console error # Errors only
playwright-cli console warning # Warnings only
# View network activity
playwright-cli network
```
## Tracing
Traces capture **everything** — DOM snapshots, screenshots, network activity, console logs, and timing — for every action during a session.
### Basic Usage
```bash
# Start recording before the flow you want to debug
playwright-cli tracing-start
# Perform actions
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli click e4
playwright-cli fill e7 "test data"
playwright-cli click e9
# Stop and save the trace
playwright-cli tracing-stop
```
### What Traces Capture
| Category | Details |
| ----------------- | ------------------------------------------------------------------ |
| **Actions** | Every click, fill, hover, keyboard input, navigation — with timing |
| **DOM Snapshots** | Full DOM state before and after each action |
| **Screenshots** | Visual state at each step |
| **Network** | All HTTP requests, responses, headers, bodies, timing |
| **Console** | All `console.log`, `console.warn`, `console.error` messages |
| **Timing** | Precise duration for each operation |
| **Source** | Which command triggered each action |
### Trace Output Files
When tracing is active, Playwright creates a `traces/` directory:
**`trace-{timestamp}.trace`** — Main trace file containing:
- Action log with DOM snapshots
- Screenshots at each step
- Timing information
- Console messages
**`trace-{timestamp}.network`** — Network activity:
- All HTTP requests and responses
- Request/response headers and bodies
- DNS, connect, TLS, TTFB, download timing
- Resource sizes and failed requests
**`resources/`** — Cached assets for trace replay:
- Images, fonts, stylesheets, scripts
- Response bodies for offline replay
### Viewing Traces
Open traces in Playwright's Trace Viewer — a rich GUI for step-by-step debugging:
```bash
# Open trace in the Trace Viewer web app
npx playwright show-trace traces/trace-123456.trace
# Or use the online Trace Viewer
# Upload trace file to: https://trace.playwright.dev
```
The Trace Viewer shows:
- **Timeline**: Step-by-step actions with screenshots
- **DOM Snapshot**: Inspect elements at each step (like DevTools)
- **Network**: Waterfall view of all requests
- **Console**: Log messages with timestamps
- **Source**: The code that triggered each action
## Console Monitoring
View JavaScript console output from the page — essential for catching errors:
```bash
# Show all console messages
playwright-cli console
# Filter by severity level
playwright-cli console error # Only errors
playwright-cli console warning # Only warnings
playwright-cli console info # Only info messages
playwright-cli console log # Only log messages
```
### Common Debugging Pattern
```bash
playwright-cli open https://app.example.com
playwright-cli snapshot
playwright-cli click e5 # Something unexpected happens
# Check if there were JavaScript errors
playwright-cli console error
# Output might show:
# [error] TypeError: Cannot read properties of undefined (reading 'map')
# [error] Uncaught ReferenceError: processData is not defined
```
### Watch Console During Interaction
Use `run-code` to set up continuous console monitoring:
```bash
playwright-cli run-code "async page => {
page.on('console', msg => {
if (msg.type() === 'error' || msg.type() === 'warning') {
console.log(\`[\${msg.type()}] \${msg.text()}\`);
}
});
}"
# Now interact — errors and warnings will print as they occur
playwright-cli click e5
playwright-cli fill e3 "test"
```
### Capture Uncaught Exceptions
```bash
playwright-cli run-code "async page => {
page.on('pageerror', error => {
console.log('Uncaught exception:', error.message);
});
}"
```
## Network Monitoring
View all network requests made by the page:
```bash
playwright-cli network
```
### Watch Network in Real-Time
```bash
playwright-cli run-code "async page => {
page.on('request', request => {
console.log(\`>> \${request.method()} \${request.url()}\`);
});
page.on('response', response => {
console.log(\`<< \${response.status()} \${response.url()}\`);
});
}"
# Now interact — requests will print as they happen
playwright-cli click e5
```
### Monitor Failed Requests
```bash
playwright-cli run-code "async page => {
page.on('requestfailed', request => {
console.log(\`FAILED: \${request.method()} \${request.url()} - \${request.failure()?.errorText}\`);
});
}"
```
### Inspect a Specific Response
```bash
playwright-cli run-code "async page => {
const response = await page.waitForResponse('**/api/users');
return {
status: response.status(),
statusText: response.statusText(),
headers: response.headers(),
body: await response.json()
};
}"
```
## Debugging Strategies
### Strategy 1: Snapshot Before and After
The simplest debugging approach — see what changed:
```bash
playwright-cli snapshot --filename=before.yaml
playwright-cli click e5
playwright-cli snapshot --filename=after.yaml
# Compare the two snapshots to understand what changed
```
### Strategy 2: Trace the Failing Flow
Start tracing before the step that fails:
```bash
playwright-cli tracing-start
# Reproduce the issue
playwright-cli goto https://app.example.com/checkout
playwright-cli fill e1 "Jane Doe"
playwright-cli click e5 # This step fails
playwright-cli tracing-stop
# Open trace to see DOM state when the click was attempted
```
### Strategy 3: Check Element State
When an interaction fails, check what state the element is actually in:
```bash
# Is the element visible?
playwright-cli eval "el => window.getComputedStyle(el).display" e5
playwright-cli eval "el => window.getComputedStyle(el).visibility" e5
playwright-cli eval "el => el.getBoundingClientRect()" e5
# Is it covered by another element?
playwright-cli eval "el => {
const rect = el.getBoundingClientRect();
const topEl = document.elementFromPoint(rect.x + rect.width/2, rect.y + rect.height/2);
return topEl === el ? 'Element is on top' : 'Covered by: ' + topEl?.tagName + '.' + topEl?.className;
}" e5
# Is it disabled?
playwright-cli eval "el => el.disabled" e5
playwright-cli eval "el => el.getAttribute('aria-disabled')" e5
```
### Strategy 4: Console + Network Combined
```bash
# Set up monitoring for both console and network
playwright-cli run-code "async page => {
page.on('console', msg => {
if (msg.type() === 'error') console.log('[CONSOLE]', msg.text());
});
page.on('requestfailed', req => {
console.log('[NETWORK]', req.method(), req.url(), req.failure()?.errorText);
});
page.on('response', resp => {
if (resp.status() >= 400) {
console.log('[HTTP ERROR]', resp.status(), resp.url());
}
});
}"
# Now interact and watch for errors
playwright-cli click e5
playwright-cli fill e3 "test"
```
### Strategy 5: Wait and Retry
If actions fail due to timing, add explicit waits:
```bash
# Wait for element to be actionable
playwright-cli run-code "async page => {
await page.locator('#dynamic-button').waitFor({ state: 'visible', timeout: 10000 });
}"
playwright-cli snapshot
playwright-cli click e5
# Wait for page to settle
playwright-cli run-code "async page => {
await page.waitForLoadState('networkidle');
}"
playwright-cli snapshot
```
## Performance Analysis
### Measure Page Load Time
```bash
playwright-cli run-code "async page => {
const timing = await page.evaluate(() => {
const t = performance.timing;
return {
dns: t.domainLookupEnd - t.domainLookupStart,
tcp: t.connectEnd - t.connectStart,
ttfb: t.responseStart - t.requestStart,
download: t.responseEnd - t.responseStart,
domParsing: t.domInteractive - t.domLoading,
domComplete: t.domComplete - t.domLoading,
total: t.loadEventEnd - t.navigationStart
};
});
return timing;
}"
```
### Analyze with Navigation Timing API
```bash
playwright-cli run-code "async page => {
const entries = await page.evaluate(() => {
return performance.getEntriesByType('navigation').map(e => ({
type: e.type,
redirectTime: e.redirectEnd - e.redirectStart,
dnsTime: e.domainLookupEnd - e.domainLookupStart,
connectTime: e.connectEnd - e.connectStart,
tlsTime: e.secureConnectionStart > 0 ? e.connectEnd - e.secureConnectionStart : 0,
requestTime: e.responseStart - e.requestStart,
responseTime: e.responseEnd - e.responseStart,
domProcessing: e.domComplete - e.domInteractive,
loadTime: e.loadEventEnd - e.loadEventStart,
totalTime: e.loadEventEnd - e.startTime
}));
});
return entries;
}"
```
### List Slow Resources
```bash
playwright-cli run-code "async page => {
const resources = await page.evaluate(() => {
return performance.getEntriesByType('resource')
.map(r => ({ name: r.name.split('/').pop(), duration: Math.round(r.duration), size: r.transferSize }))
.sort((a, b) => b.duration - a.duration)
.slice(0, 10);
});
return resources;
}"
```
## Trace vs Video vs Screenshot
Choose the right capture method:
| Feature | Trace | Video | Screenshot |
| ----------------------- | ------------- | -------------------- | ------------- |
| **Format** | `.trace` file | `.webm` video | `.png` image |
| **DOM inspection** | Yes | No | No |
| **Network details** | Yes | No | No |
| **Step-by-step replay** | Yes | Continuous | Single frame |
| **Console logs** | Yes | No | No |
| **File size** | Medium | Large | Small |
| **Best for** | Debugging | Demos, documentation | Quick capture |
### Decision Guide
- **Something failed and you don't know why** → Trace
- **Need to show a flow to someone** → Video
- **Need to verify visual state** → Screenshot
- **Need to analyze performance** → Trace (has network waterfall)
- **CI artifact for failed test** → Trace + Screenshot
## Best Practices
### 1. Start Tracing BEFORE the Problem
Trace the entire flow leading up to the failure, not just the failing step:
```bash
playwright-cli tracing-start
# Reproduce the full flow from the beginning
playwright-cli open https://app.example.com
playwright-cli fill e1 "user@example.com"
playwright-cli click e3
# ... all steps leading to the failure ...
playwright-cli tracing-stop
```
### 2. Use Console Monitoring Proactively
Start console monitoring at the beginning of any debugging session:
```bash
playwright-cli run-code "async page => {
page.on('console', msg => console.log(\`[\${msg.type()}] \${msg.text()}\`));
page.on('pageerror', err => console.log('[EXCEPTION]', err.message));
}"
```
### 3. Clean Up Old Traces
Traces consume significant disk space:
```bash
# Remove traces older than 7 days
find .playwright-cli/traces -mtime +7 -delete
```
### 4. Combine Techniques
The most effective debugging combines multiple approaches:
```bash
playwright-cli tracing-start # Capture everything
playwright-cli console error # Watch for JS errors
playwright-cli network # Watch for failed requests
playwright-cli snapshot # See current state
# ... interact and debug ...
playwright-cli tracing-stop # Save trace for detailed analysis
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |