pw-trace-analyzer

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

// 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.