analyze-playwright-traces

name	analyze-playwright-traces
description	Analyze Playwright reports and traces using the playwright-traces-reader CLI, including searching a local playwright-reports hub for runs like UAT EU before performing selective trace digestion, single-test summaries, network traffic, DOM snapshots, screenshots, and timelines.

Analyze Playwright Traces

Use this skill when the user asks to analyze Playwright reports or traces, including when the report first needs to be found through a local playwright-reports hub.

Rules

• Use only supported npx playwright-traces-reader ... CLI commands.
• Do not generate temporary .mjs, .js, or .ts analysis scripts.
• Do not import parser methods directly when a CLI command covers the workflow.
• JSON is the default output mode. Use --format text only when a human-readable terminal summary is preferable.
• Use screenshots only for human visual inspection. For agent-readable UI state, prefer dom and summary.
• If the user does not specify a report by path, reportRef, metadata, date, or recency hint, default to the local playwright-report/ directory.
• If the report path is not already known, use the hub-assisted search-reports and prepare-report commands first.

Output Handling

• When working with a digested trace folder (either provided directly or generated via the digest command), read the folder's digest.json and its companion files directly; use other commands only when you need additional detail.
• For potentially larger commands such as network, dom, or timeline, narrowing output is acceptable when needed.

Prerequisites

Install the package locally in the repository:

npm install @andrii_kremlovskyi/playwright-traces-reader

If the workflow needs report discovery through playwright-reports, the local hub should be running and reachable, by default at http://127.0.0.1:9333.

Supported local inputs:

• a Playwright report root containing index.html and data/
• a playwright-report/data/ directory
• a single extracted trace directory
• a single trace zip

Placeholder meanings used in this skill:

• <sha1> means one specific trace entry inside playwright-report/data/
• <tracePath> means a concrete path to one extracted trace directory or one trace zip
• <requestId> means the numeric id returned by network for one request inside that trace
• <attachmentId> means the numeric id returned by attachments for one attachment inside that trace
• <callId> means a Playwright action identifier such as call@123 used for correlation filters like --near

Important scope rule:

• requestId and attachmentId are local to one trace, not global across the whole report
• example values like 12 or 1 in this skill are placeholders only, not fixed required values

Command Selection

Report discovery through playwright-reports

If the user gave no report identifier at all, do not start with hub discovery. Locate the trace path directly within the local default playwright-report/ directory first.

Use search-reports when the user describes a report by metadata or recency instead of giving a filesystem path.

npx playwright-traces-reader search-reports "UAT EU" --limit 1

This returns report references plus local report paths when available.

Discovery flag meanings:

• --base-url <url> points to the local playwright-reports hub. Default: http://127.0.0.1:9333.
• --limit <count> limits how many matching reports are returned.
• --range-start <YYYY-MM-DD> filters reports created on or after that date.
• --range-end <YYYY-MM-DD> filters reports created on or before that date.
• --selected-dates <YYYY-MM-DD,YYYY-MM-DD> filters to one or more exact calendar dates.

If the default hub URL is not correct, either pass --base-url or set PLAYWRIGHT_REPORTS_BASE_URL in the caller environment.

If the hub is unreachable, search-reports and prepare-report fail with a direct message that the report hub is not reachable at the requested URL.

Useful examples:

npx playwright-traces-reader search-reports "UAT EU" --limit 1
npx playwright-traces-reader search-reports "UAT EU" --range-start 2026-04-01 --range-end 2026-04-03
npx playwright-traces-reader search-reports "checkout" --selected-dates 2026-04-02,2026-04-03
npx playwright-traces-reader search-reports "smoke" --base-url http://127.0.0.1:9333

Use prepare-report to resolve one returned reportRef into a local analysis-ready path before running parser commands.

npx playwright-traces-reader prepare-report <reportRef>

After preparation, run the traditional parser commands with the returned reportRootPath or reportDataPath.

Use prepare-report when the question changes from "which report matches?" to "where is that report on disk so parsing can start?"

Example handoff flow:

npx playwright-traces-reader search-reports "UAT EU" --limit 1
npx playwright-traces-reader prepare-report <reportRef>
npx playwright-traces-reader find-traces <reportRootPath> "login"
npx playwright-traces-reader digest <tracePath> ./tmp/digest-analysis --report <reportRootPath>

Vault analysis files

Reports may have an associated markdown analysis file stored in the dashboard vault. When search-reports or prepare-report returns a report descriptor, the analysisFile field indicates whether a vault .md file exists for that report. If analysisFile is null, no analysis file is available.

Use vault-read to retrieve the content of an analysis file by name:

npx playwright-traces-reader vault-read <analysisFile>

• --base-url <url> points to the local playwright-reports hub. Default: http://127.0.0.1:9333.
• -f, --format <format> controls output format: json or text (default: text).
• -o, --out <path> writes content to a file instead of stdout. Use this when the analysis file may be large or when you need to read it with read_file afterwards.

Text format outputs the raw markdown content directly. JSON format wraps it in an envelope:

{ "schemaVersion": 1, "command": "vault-read", "filename": "...", "content": "...", "savedPath": null }

Typical flow: discover a report, then read its analysis file if one exists.

npx playwright-traces-reader search-reports "UAT EU" --limit 1
# → check analysisFile field in the response
npx playwright-traces-reader vault-read <analysisFile>

For large analysis files, save to a workspace file first, then read with read_file:

npx playwright-traces-reader vault-read <analysisFile> --out ./tmp/analysis.md

The agent cannot access vault files directly with read_file because they are stored outside the workspace. Always use vault-read through the terminal to retrieve vault content, or use --out to save it into the workspace first.

Single-test trace digestion (First Priority)

If the user needs to analyze a specific test trace (either passed, failed, or flaky) and a digested folder has not already been provided directly (e.g., from the dashboard or by the user), use the digest command as your first-priority tool.

Digesting a single trace produces a comprehensive, chronological step and event tree pre-correlated with DOM snapshots, console logs, and network NDJSON files, which is far more token-efficient than running individual parser commands (like steps or network).

npx playwright-traces-reader digest <tracePath> /path/to/output --report /path/to/playwright-report

What it does:

• Creates a self-contained output directory containing digest.json (the entry point step tree), network.ndjson, console.ndjson, and a dom/ directory with self-contained Action-phase HTML snapshots.
• Every step in digest.json links the sequence IDs of all network calls within its execution window.
• Response bodies over 32 KB are spilled to network-bodies.ndjson with a bodyRef so you only load them if needed.

Guidelines:

• Workspace Cleanup: Choose any temporary output directory of your choice inside the workspace (e.g., ./tmp/digest-analysis), perform your analysis by reading digest.json and its companion files directly, and then delete the output directory once you are done to keep the workspace clean. Make sure you do not delete any other files
• Pre-digested Folders: If the user has already run the digest command or used the playwright-reports dashboard to digest the trace, they may provide the path to the pre-digested folder. In this case, bypass running the digest command and inspect digest.json in that folder directly.

Finding traces for any test

Use find-traces when the user wants to locate trace paths for a specific test — including passed tests — by name.

npx playwright-traces-reader find-traces /path/to/playwright-report "test name pattern"

The <grep> argument is a case-insensitive substring matched against the full test title (file path + describe blocks + test name). Special characters in test names (brackets, quotes, parentheses, non-Latin scripts) are handled safely — paste any fragment directly.

Use --outcome to filter by test outcome:

npx playwright-traces-reader find-traces /path/to/playwright-report "checkout" --outcome expected
npx playwright-traces-reader find-traces /path/to/playwright-report "checkout" --outcome flaky

Outcome values: expected (passed), unexpected (failed), flaky, skipped.

What it returns:

• all matching tests with their trace paths, including all retries
• test-level outcome from report.json
• trace SHA1 and absolute trace path for direct use with summary <tracePath>

Typical follow-up:

npx playwright-traces-reader find-traces /path/to/playwright-report "login" --outcome expected
npx playwright-traces-reader summary <tracePath> --report /path/to/playwright-report

Single-trace summary

Use summary when the user wants one complete summary for a specific trace.

npx playwright-traces-reader summary /path/to/playwright-report/data/<sha1>

If report metadata should be loaded explicitly, pass --report:

npx playwright-traces-reader summary /path/to/playwright-report/data/<sha1> --report /path/to/playwright-report

Important behavior:

• summary works for both passed and failed traces
• summary includes issues and aggregated related-action diagnostics
• failed traces include failureDomSnapshot — a lightweight metadata reference (callId, phases, frameUrl), NOT the full HTML
• to retrieve full DOM HTML, use dom --near <callId> --output ./tmp/dom.json
• passed traces return status: "passed" and failureDomSnapshot: null

Slow steps

Use slow-steps to inspect the slowest steps in one trace.

npx playwright-traces-reader slow-steps /path/to/playwright-report/data/<sha1> --limit 5

Step tree

Use steps to inspect the reconstructed test step hierarchy.

npx playwright-traces-reader steps /path/to/playwright-report/data/<sha1>

Network traffic

Use network to inspect API and browser traffic for one trace.

npx playwright-traces-reader network /path/to/playwright-report/data/<sha1> --source all

Source filters:

• all
• api
• browser

Useful filters:

• --grep <pattern>
• --method <method>
• --status <code>
• --failed
• --near <callId>
• --limit <count>

Use request when one network entry needs full headers, bodies, and correlation details.

How to get <requestId>:

• first run network <tracePath>
• read the id field from the returned network entries
• then pass that numeric id into request <tracePath> <requestId>

Example discovery flow:

npx playwright-traces-reader network /path/to/playwright-report/data/<sha1>
npx playwright-traces-reader request /path/to/playwright-report/data/<sha1> 12

In the second command, 12 means "the request whose id was 12 in the network output for this same trace".

npx playwright-traces-reader request /path/to/playwright-report/data/<sha1> 12

Console and errors

Use console when the user needs browser console output, page errors, or stdio from one trace.

npx playwright-traces-reader console /path/to/playwright-report/data/<sha1>

Use errors when the user needs failed steps, page errors, and trace-level issues in one place.

npx playwright-traces-reader errors /path/to/playwright-report/data/<sha1>

DOM snapshots

Output is always written to a file (--output is required).

npx playwright-traces-reader dom /path/to/playwright-report/data/<sha1> --output ./tmp/dom.json --near last --limit 3

Write to a path inside the workspace (e.g. ./tmp/dom.json) so you can open it afterward with read_file. The DOM HTML is the point of this command — saving to /tmp outside the workspace makes it harder to read back.

There is no separate .html file. The HTML is stored as a string in the snapshots[].<phase>.html field (where <phase> is before, action, or after) inside the JSON file. Open the JSON with read_file and read that field.

Each snapshot's html is self-contained: child <iframe>/<frame> content is inlined recursively as srcdoc (no /snapshot/<frameId> placeholders), so you can read embedded vendor/app flows and update locators directly. Targets inside child frames are resolved into targetElement.

Useful filters:

• --near last
• --near <callId> (use the callId from failureDomSnapshot in the summary)
• --phase before|action|after
• --limit <count>

Timeline

Use timeline to build a merged chronological trace narrative.

npx playwright-traces-reader timeline /path/to/playwright-report/data/<sha1>

Attachments

Use attachments to list captured artifacts for a trace, then attachment to extract one by its ID.

How to get <attachmentId>:

• first run attachments <tracePath>
• read the id field from the returned attachment entries
• then pass that numeric id into attachment <tracePath> <attachmentId>

Example discovery flow:

npx playwright-traces-reader attachments /path/to/playwright-report/data/<sha1>
npx playwright-traces-reader attachment /path/to/playwright-report/data/<sha1> 1 --output ./artifact.txt

In the second command, 1 means "the attachment whose id was 1 in the attachments output for this same trace".

npx playwright-traces-reader attachments /path/to/playwright-report/data/<sha1>
npx playwright-traces-reader attachment /path/to/playwright-report/data/<sha1> 1 --output ./artifact.txt

Screenshots

Use screenshots only when a human needs extracted image files.

npx playwright-traces-reader screenshots /path/to/playwright-report/data/<sha1> --out-dir /tmp/pw-screenshots

Skill scaffold

Use init-skills to install this skill into another repository.

npx playwright-traces-reader init-skills

Recommended Workflow

1. If the user gave no report identifier at all, start with the local playwright-report/ directory.
2. If the report path is unknown but the user did provide metadata, date, or recency hints, use search-reports and then prepare-report first.
3. Identify whether the task is report-level or single-trace.
4. If the user wants to analyze a specific test by name (including passed tests), use find-traces to locate its trace path first.
5. Choose the narrowest parser command that answers the question.
6. Use the default JSON output for agent reasoning or follow-up processing.
7. Use --format text when the user wants a direct terminal-style summary.
8. Do not fall back to library APIs unless the requested workflow is not covered by a supported command.

Output Guidance

• All CLI JSON outputs use versioned envelopes.
• For screenshots, the JSON output contains file metadata, not image understanding.

Example Prompts This Skill Covers

• Find the trace for a failed test in the local report and digest it.
• Find the UAT EU report, locate the failing test "checkout", and digest its trace.
• Find checkout reports from 2026-04-01 through 2026-04-03 and prepare the newest one.
• Resolve this reportRef and summarize the trace.
• Use the reports hub at http://127.0.0.1:9333 to find the most recent smoke run.
• Find the trace for my passed "login" test and digest it.
• Show me traces for all flaky tests matching "checkout".