Playwright Trace Analyzer

Playwright Trace Analyzer

Turn a Playwright trace.zip into a ranked, evidence-backed report of flakes, slow steps, and root causes.

> Index file. Detailed extraction rules, analysis playbooks, and > report templates live under rules/, references/, and templates/. > Load only what the current phase needs — the body of SKILL.md is a > thin orchestrator.

---

Inputs

The user passes one or more of:

| Input | Detection signal | | ------------------------------------ | ---------------------------------------------------------------------- | | GitHub Actions run URL | Matches https://github.com///actions/runs/ — fetch artifacts via gh run download | | trace.zip archive | Magic bytes 50 4b 03 04; entries include trace.trace, trace.network, *.png, resources/ | | Unpacked trace directory | Contains trace.trace + trace.network (NDJSON) and a resources/ subdir | | Single trace.trace JSONL stream | NDJSON; each line has type, callId, startTime, params (e.g. before, action, after) | | Single trace.network JSONL stream | NDJSON; entries with type: "resource-snapshot" or requestEvent / responseEvent | | report.json (Playwright reporter) | Top-level config, suites, stats; complementary, never authoritative for timing |

If the user passes a report.json plus a trace.zip, treat the report as a high-level test status map and the trace as the source of truth for timing and network data.

If a test-results/ directory is passed, scan for the most recent trace.zip per failed test and process them in order of failure recency.

See [rules/input-detection.md](./rules/input-detection.md) for the precise detection logic and unpack recipe.

---

Workflow

Six phases. Do not skip a gate.

| Phase | Name | Rule file | Gate | | ----- | ------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | | 0 | Intake | [rules/input-detection.md](./rules/input-detection.md) | Format detected, archive unpacked, trace.trace + trace.network parseable | | 1 | Measurement frame | [rules/measurement-methodology.md](./rules/measurement-methodology.md) | Failure mode named (timeout, assertion, error, slow-but-passing) and primary metric chosen (action ms, total wall-clock, request count) | | 2 | Hotspot extraction | [rules/action-timing.md](./rules/action-timing.md), [rules/network-analysis.md](./rules/network-analysis.md), [rules/console-and-errors.md](./rules/console-and-errors.md) | Top-N slow actions, top-N slow requests, error/console list — all with concrete numbers | | 3 | Root-cause | [rules/flake-diagnosis.md](./rules/flake-diagnosis.md) | Each hotspot mapped to a code-level cause (selector, locator, network call, app event) with file path or line where possible | | 4 | Confidence gate | [rules/confidence-loop.md](./rules/confidence-loop.md) | /confidence analysis ≥ 90% — else iterate (max 2 deep-dives) | | 5 | Fix plan | [templates/analysis-report.md](./templates/analysis-report.md) | Report written with ranked fixes, expected impact, and verification plan |

---

Required reading by phase

Load on demand — do not preload.

| Phase | Files | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | [rules/input-detection.md](./rules/input-detection.md) — also points to [scripts/trace-extract.mjs](./scripts/trace-extract.mjs) | | 1 | [rules/measurement-methodology.md](./rules/measurement-methodology.md) | | 2 | [rules/action-timing.md](./rules/action-timing.md), [rules/network-analysis.md](./rules/network-analysis.md), [rules/console-and-errors.md](./rules/console-and-errors.md) — backed by [scripts/trace-summary.mjs](./scripts/trace-summary.mjs) | | 3 | [rules/flake-diagnosis.md](./rules/flake-diagnosis.md), [references/flake-patterns.md](./references/flake-patterns.md), [references/performance-patterns.md](./references/performance-patterns.md) | | 4 | [rules/confidence-loop.md](./rules/confidence-loop.md) | | 5 | [templates/analysis-report.md](./templates/analysis-report.md) |

Pass-vs-fail comparison (when given two traces of the same test): [scripts/trace-diff.mjs](./scripts/trace-diff.mjs).

---

Confidence-gated iteration

After the first pass at root-cause analysis, invoke the confidence skill in analysis mode:

Skill(skill="confidence", args="analysis")

Apply this gate:

| Score | Action | | ------------ | --------------------------------------------------------------------------------------------------- | | ≥ 90% | Proceed to Phase 5 (fix plan). | | 70–89% | Run one deeper pass: re-read the trace, expand the action's before/after snapshots, correlate with network. | | **/scripts/fetch-gh-run.mjs https://github.com///actions/runs/ [--out ]

The script uses the `gh` CLI (`gh run download`) to fetch every artifact
whose name matches Playwright conventions (`playwright-report*`,
`playwright-traces*`, `test-results*`, `*-traces`, `*-trace`), unpacks
nested ZIPs, and writes a manifest of all `trace.zip` files discovered,
grouped by failed test where possible. Then continue with the unpacked
flow below.
If `gh` is not installed or unauthenticated, ask the user to download the trace artifact manually from the Actions run page and provide the local path — the `trace.zip` flow below is unaffected.

### Input is a `trace.zip`

1. **Unpack and index.**
   ```bash
   node /scripts/trace-extract.mjs  [--out ]
   ```
   Writes a normalised `trace.trace.jsonl`, `trace.network.jsonl`, and a
   manifest of resources/snapshots into `` (defaults to a sibling
   `.unpacked/`).

2. **Run the summary.**
   ```bash
   node /scripts/trace-summary.mjs 
   ```
   Prints: total wall-clock, top-N slow actions, top-N slow requests,
   console errors, page errors, and the failing-action stack trace if
   present.

3. **(Optional) Diff a passing trace against a failing trace.**
   ```bash
   node /scripts/trace-diff.mjs  
   ```
   Surfaces actions that diverge in duration, requests present in one but
   not the other, and the first action where the two timelines fork.

4. **Map suspects to source.** Use
   [`rules/flake-diagnosis.md`](./rules/flake-diagnosis.md) Phases 3–4 to
   go from action callId → test file/line (Playwright trace events embed
   `location: { file, line, column }`).

The full extraction methodology (capture protocol, how to interpret the
network log, common flake shapes) is in
[`rules/flake-diagnosis.md`](./rules/flake-diagnosis.md). Don't preload
it — only when an input is detected.

## Definition of Done

- [ ] Input format detected and stated (zip / dir / single JSONL).
- [ ] Failure mode named — timeout, assertion, error, or slow-passing
      (Phase 1).
- [ ] Top-N slow actions listed with measured `dur` (ms).
- [ ] Top-N slow requests listed with `responseEnd - requestStart` (ms)
      and status.
- [ ] Console / page errors captured verbatim.
- [ ] Each hotspot mapped to a test file + line (from `location` in the
      trace event), or to an app file when the cause is in product code.
- [ ] `/confidence analysis` reached ≥ 90% (or two deep-dives
      recorded with the remaining uncertainty surfaced to the user).
- [ ] Fix plan written using
      [`templates/analysis-report.md`](./templates/analysis-report.md),
      with ranked fixes, expected ms saved, and a re-run verification
      step.
- [ ] User has the next concrete action (apply fix N, re-run with
      `--trace=on`, compare).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mthines](https://github.com/mthines)
- **Source:** [mthines/agent-skills](https://github.com/mthines/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.