pw-trace-analyzer v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/9f44e86fba2312b7.

---
name: pw-trace-analyzer
description: >-
  Analyzes a Playwright trace.zip or test failure to pinpoint the root cause. Use
  when an SDET says "read this trace", "why did this test fail", "analyze the
  trace.zip", "my CI run failed — what broke", or pastes an error + trace. Reads
  the timeline, isolates the failing action/assertion, and recommends the fix — a
  diagnosis the engineer confirms by re-running.
license: MIT
metadata:
  author: TheTestingAcademy
  pack: playwright
  version: 1.0.0
---

# PW Trace Analyzer

You turn a trace or failure into a **root-cause diagnosis the engineer must
confirm by re-running** — a trace shows what happened, not always why it's wrong.

## When to use
- A `trace.zip` or Playwright error/stack is available and needs interpreting.
- A CI failure needs triage before anyone re-runs blindly.
- Someone says "read/analyze this trace", "why did this fail".

## Workflow
1. **Open the trace** — recommend `npx playwright show-trace trace.zip` (or the CI
   report's trace link). If only an error string is provided, work from that and
   ask for the trace to go deeper.
2. **Locate the failing step** on the timeline — the last action/assertion before
   the error, its call log, and the DOM snapshot at that moment.
3. **Read the snapshot + call log** to classify the cause: element not found /
   not visible, strict-mode multi-match, navigation not settled, wrong assertion,
   backend error (check the Network tab), or a race with an animation/async render.
4. **Correlate signals** — console errors, failed requests, and the before/after
   snapshots — to separate a test bug from a genuine product bug.
5. **Authorize reproduction before rerunning.** Confirm an approved non-production
   target, synthetic owned data, allowed side effects, cleanup/reset behavior, finite
   sample size, concurrency, and abort limits. If any item is unknown, provide a draft
   command but do not recommend executing it.
6. **Recommend the fix** with confidence level and the exact, approved reproduce command.

## Output shape
```
Trace analysis
  Failing step : expect(getByTestId('total')).toHaveText('$120') @ 00:07.3
  Snapshot     : element shows '$0' — cart total not yet updated
  Network      : PATCH /api/cart → 200 fired AFTER the assertion (race)
  Root cause   : assertion ran before the cart-update response settled
  Fix          : await the response, then assert (web-first already retries text)
  Authorization: approved non-production cart, synthetic data, cleanup, 10 serial runs
  Reproduce    : npx playwright test cart.spec.ts --trace on --repeat-each=10
```
```typescript
// await the signal the UI depends on, then let the web-first assertion retry
await Promise.all([
  page.waitForResponse((r) => r.url().includes('/api/cart') && r.ok()),
  page.getByRole('button', { name: 'Add' }).click(),
]);
await expect(page.getByTestId('total')).toHaveText('$120');
```

## Guardrails
- The diagnosis is a **hypothesis the engineer must confirm by re-running** — never
  declare it solved without a trace-backed reproduce step.
- Read the trace evidence; **never fabricate** timeline steps, snapshots, or network
  calls you weren't shown. If the trace wasn't provided, say what you'd need.
- Distinguish test bug vs. product bug — don't "fix" a real regression by loosening
  the test. Never recommend `waitForTimeout` as the remedy.
- Never repeat a state-changing test without approved target, data ownership, side effects,
  cleanup, finite sample size, concurrency, and abort limits. Stop on unexpected effects.
- Treat traces as potentially sensitive because they can contain DOM, request, and response
  data; keep them local unless redaction, audience, access, and retention are approved.