| name | playwright-trace |
| description | Analyze Playwright/E2E test trace files (.zip) to debug failures. INVOKE PROACTIVELY whenever an E2E or Playwright test run fails and a trace is available — locally at test-results/*/trace.zip or linked from CI output — before attempting any fix. Use to identify the exact failure point, inspect screenshots at each step, check network requests, and determine root cause. |
Playwright Trace Analysis
Analyze Playwright test trace files (.zip) to debug test failures and understand test behavior.
When to Use
- A Playwright test has failed and you need to understand why
- You want to review what a test did step-by-step
- You need to inspect network requests made during a test
- You want to extract screenshots from a test run
Commands
Summary
Get a high-level overview of a trace:
playwright-trace-cli summary <trace.zip>
Actions
List all test actions (clicks, navigations, assertions, etc.):
playwright-trace-cli actions <trace.zip>
Errors
Show only failed actions with detailed error messages and call logs:
playwright-trace-cli errors <trace.zip>
Network
Inspect network requests:
playwright-trace-cli network <trace.zip>
playwright-trace-cli network <trace.zip> --failed
playwright-trace-cli network <trace.zip> --step 3
Screenshot
Extract a screenshot closest to a specific action:
playwright-trace-cli screenshot <trace.zip> --step 3
JSON Output
All commands support --json for structured output:
playwright-trace-cli summary <trace.zip> --json
playwright-trace-cli actions <trace.zip> --json
Debugging Workflow
- Start with
summary to get an overview and see if the test passed or failed
- If failed, use
errors to see what went wrong — note the step number (#N) of the failure
- Use
actions to see the full sequence of test steps and understand context around the failure
- Check network activity: use
network --step N to see what API calls happened during the failing step, and network --failed to find any failed requests. This reveals server-side issues, missing data, or unexpected responses
- Inspect the page visually: use
screenshot --step N to see exactly what the page looked like at the failing step. This reveals missing elements, loading states, or unexpected UI
Trace File Location
Playwright traces are typically found at:
test-results/<test-name>/trace.zip (after running tests with --trace on)- Custom paths configured in
playwright.config.ts under use.trace
