diff --git a/packages/playwright-core/src/tools/cli-client/skill/references/tracing.md b/packages/playwright-core/src/tools/cli-client/skill/references/tracing.md index 7ce7babbdf17c..cc79dd37c49db 100644 --- a/packages/playwright-core/src/tools/cli-client/skill/references/tracing.md +++ b/packages/playwright-core/src/tools/cli-client/skill/references/tracing.md @@ -2,7 +2,7 @@ Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs. -## Basic Usage +## Recording a Trace from playwright-cli ```bash # Start trace recording @@ -100,6 +100,190 @@ playwright-cli tracing-stop # Trace shows exact sequence of events ``` +## Analyzing a Trace from Playwright Test + +When you run Playwright Test with tracing enabled, it generates a trace file for each test. You can analyze these traces to understand what happened during the test execution. + +You can open a trace file with `npx playwright trace path/to/trace.zip`. + +1. Start with `trace open ` to extract the trace and see its metadata. +2. Use `trace actions` to see all actions with their action IDs. +3. Use `trace action ` to drill into a specific action — see parameters, logs, source location, and available snapshots. +4. Use `trace requests`, `trace console`, or `trace errors` for cross-cutting views. +5. Use `trace snapshot ` to get the DOM snapshot, or run a browser command against it. +6. Use `trace close` to remove the extracted trace data when done. + +All commands after `open` operate on the currently opened trace — no need to pass the trace file again. Opening a new trace replaces the previous one. + +`npx playwright trace` does not currently support opening traces created by `playwright-cli tracing-start` — only traces generated by Playwright Test. + +### Commands + +#### Open a trace + +```bash +# Extract trace and show metadata: browser, viewport, duration, action/error counts +npx playwright trace open +``` + +#### Close a trace + +```bash +# Remove extracted trace data +npx playwright trace close +``` + +#### Actions + +```bash +# List all actions as a tree with action IDs and timing +npx playwright trace actions + +# Filter by action title (regex, case-insensitive) +npx playwright trace actions --grep "click" + +# Only failed actions +npx playwright trace actions --errors-only +``` + +#### Action details + +```bash +# Show full details for one action: params, result, logs, source, snapshots +npx playwright trace action +``` + +The `action` command displays available snapshot phases (before, input, after) and the exact command to extract them. + +#### Requests + +```bash +# All network requests: method, status, URL, duration, size +npx playwright trace requests + +# Filter by URL pattern +npx playwright trace requests --grep "api" + +# Filter by HTTP method +npx playwright trace requests --method POST + +# Only failed requests (status >= 400) +npx playwright trace requests --failed +``` + +#### Request details + +```bash +# Show full details for one request: headers, body, security +npx playwright trace request +``` + +#### Console + +```bash +# All console messages and stdout/stderr +npx playwright trace console + +# Only errors +npx playwright trace console --errors-only + +# Only browser console (no stdout/stderr) +npx playwright trace console --browser + +# Only stdout/stderr (no browser console) +npx playwright trace console --stdio +``` + +#### Errors + +```bash +# All errors with stack traces and associated actions +npx playwright trace errors +``` + +#### Snapshots + +The `snapshot` command loads the DOM snapshot for an action into a headless browser and runs a single browser command against it. Without a browser command, it returns the accessibility snapshot. + +```bash +# Get the accessibility snapshot (default) +npx playwright trace snapshot + +# Use a specific phase +npx playwright trace snapshot --name before + +# Run eval to query the DOM +npx playwright trace snapshot -- eval "document.title" +npx playwright trace snapshot -- eval "document.querySelector('#error').textContent" + +# Eval on a specific element ref (from the snapshot) +npx playwright trace snapshot -- eval "el => el.getAttribute('data-testid')" e5 + +# Take a screenshot of the snapshot +npx playwright trace snapshot -- screenshot + +# Redirect output to a file +npx playwright trace snapshot -- eval "document.body.outerHTML" --filename=page.html +npx playwright trace snapshot -- screenshot --filename=screenshot.png +``` + +Only three browser commands are useful on a frozen snapshot: `snapshot`, `eval`, and `screenshot`. + +#### Attachments + +```bash +# List all trace attachments +npx playwright trace attachments + +# Extract an attachment by its number +npx playwright trace attachment 1 +npx playwright trace attachment 1 -o out.png +``` + +### Typical investigation + +```bash +# 1. Open the trace and see what's inside +npx playwright trace open test-results/my-test/trace.zip + +# 2. What actions ran? +npx playwright trace actions + +# 3. Which action failed? +npx playwright trace actions --errors-only + +# 4. What went wrong? +npx playwright trace action 12 + +# 5. What did the page look like at that moment? +npx playwright trace snapshot 12 + +# 6. Query the DOM for more detail +npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent" + +# 7. Any relevant network failures? +npx playwright trace requests --failed + +# 8. Any console errors? +npx playwright trace console --errors-only +``` + +### Download a Trace from CI + +```bash +# Download the HTML report artifact from CI +gh run download -n playwright-report + +# Serve the report locally and open it to find trace paths +npx playwright show-report & +playwright-cli open http://localhost:9323 +playwright-cli snapshot +# Find the faulty run, note the trace zip URL, e.g. http://localhost:9323/data/.zip +playwright-cli close + +npx playwright trace open playwright-report/data/.zip +``` + ## Trace vs Video vs Screenshot | Feature | Trace | Video | Screenshot | diff --git a/packages/playwright-core/src/tools/trace/SKILL.md b/packages/playwright-core/src/tools/trace/SKILL.md deleted file mode 100644 index 6cf0af85ab8a2..0000000000000 --- a/packages/playwright-core/src/tools/trace/SKILL.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -name: playwright-trace -description: Inspect Playwright trace files from the command line — list actions, view requests, console, errors, snapshots and screenshots. -allowed-tools: Bash(npx:*) ---- - -# Playwright Trace CLI - -Inspect `.zip` trace files produced by Playwright tests without opening a browser. - -## Workflow - -1. Start with `trace open ` to extract the trace and see its metadata. -2. Use `trace actions` to see all actions with their action IDs. -3. Use `trace action ` to drill into a specific action — see parameters, logs, source location, and available snapshots. -4. Use `trace requests`, `trace console`, or `trace errors` for cross-cutting views. -5. Use `trace snapshot ` to get the DOM snapshot, or run a browser command against it. -6. Use `trace close` to remove the extracted trace data when done. - -All commands after `open` operate on the currently opened trace — no need to pass the trace file again. Opening a new trace replaces the previous one. - -## Commands - -### Open a trace - -```bash -# Extract trace and show metadata: browser, viewport, duration, action/error counts -npx playwright trace open -``` - -### Close a trace - -```bash -# Remove extracted trace data -npx playwright trace close -``` - -### Actions - -```bash -# List all actions as a tree with action IDs and timing -npx playwright trace actions - -# Filter by action title (regex, case-insensitive) -npx playwright trace actions --grep "click" - -# Only failed actions -npx playwright trace actions --errors-only -``` - -### Action details - -```bash -# Show full details for one action: params, result, logs, source, snapshots -npx playwright trace action -``` - -The `action` command displays available snapshot phases (before, input, after) and the exact command to extract them. - -### Requests - -```bash -# All network requests: method, status, URL, duration, size -npx playwright trace requests - -# Filter by URL pattern -npx playwright trace requests --grep "api" - -# Filter by HTTP method -npx playwright trace requests --method POST - -# Only failed requests (status >= 400) -npx playwright trace requests --failed -``` - -### Request details - -```bash -# Show full details for one request: headers, body, security -npx playwright trace request -``` - -### Console - -```bash -# All console messages and stdout/stderr -npx playwright trace console - -# Only errors -npx playwright trace console --errors-only - -# Only browser console (no stdout/stderr) -npx playwright trace console --browser - -# Only stdout/stderr (no browser console) -npx playwright trace console --stdio -``` - -### Errors - -```bash -# All errors with stack traces and associated actions -npx playwright trace errors -``` - -### Snapshots - -The `snapshot` command loads the DOM snapshot for an action into a headless browser and runs a single browser command against it. Without a browser command, it returns the accessibility snapshot. - -```bash -# Get the accessibility snapshot (default) -npx playwright trace snapshot - -# Use a specific phase -npx playwright trace snapshot --name before - -# Run eval to query the DOM -npx playwright trace snapshot -- eval "document.title" -npx playwright trace snapshot -- eval "document.querySelector('#error').textContent" - -# Eval on a specific element ref (from the snapshot) -npx playwright trace snapshot -- eval "el => el.getAttribute('data-testid')" e5 - -# Take a screenshot of the snapshot -npx playwright trace snapshot -- screenshot - -# Redirect output to a file -npx playwright trace snapshot -- eval "document.body.outerHTML" > page.html -npx playwright trace snapshot -- screenshot > screenshot.png -``` - -Only three browser commands are useful on a frozen snapshot: `snapshot`, `eval`, and `screenshot`. - -### Attachments - -```bash -# List all trace attachments -npx playwright trace attachments - -# Extract an attachment by its number -npx playwright trace attachment 1 -npx playwright trace attachment 1 -o out.png -``` - -## Typical investigation - -```bash -# 1. Open the trace and see what's inside -npx playwright trace open test-results/my-test/trace.zip - -# 2. What actions ran? -npx playwright trace actions - -# 3. Which action failed? -npx playwright trace actions --errors-only - -# 4. What went wrong? -npx playwright trace action 12 - -# 5. What did the page look like at that moment? -npx playwright trace snapshot 12 - -# 6. Query the DOM for more detail -npx playwright trace snapshot 12 -- eval "document.querySelector('.error-message').textContent" - -# 7. Any relevant network failures? -npx playwright trace requests --failed - -# 8. Any console errors? -npx playwright trace console --errors-only -``` diff --git a/packages/playwright-core/src/tools/trace/installSkill.ts b/packages/playwright-core/src/tools/trace/installSkill.ts deleted file mode 100644 index 4194a639f67f5..0000000000000 --- a/packages/playwright-core/src/tools/trace/installSkill.ts +++ /dev/null @@ -1,30 +0,0 @@ -/** - * Copyright (c) Microsoft Corporation. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/* eslint-disable no-console */ - -import fs from 'fs'; -import path from 'path'; - -export async function installSkill() { - const cwd = process.cwd(); - const skillSource = path.join(__dirname, 'SKILL.md'); - const destDir = path.join(cwd, '.claude', 'playwright-trace'); - await fs.promises.mkdir(destDir, { recursive: true }); - const destFile = path.join(destDir, 'SKILL.md'); - await fs.promises.copyFile(skillSource, destFile); - console.log(`✅ Skill installed to \`${path.relative(cwd, destFile)}\`.`); -} diff --git a/packages/playwright-core/src/tools/trace/traceCli.ts b/packages/playwright-core/src/tools/trace/traceCli.ts index 5bb76135c2fc0..5f45f5b837571 100644 --- a/packages/playwright-core/src/tools/trace/traceCli.ts +++ b/packages/playwright-core/src/tools/trace/traceCli.ts @@ -138,12 +138,4 @@ export function addTraceCommands(program: Command, logErrorAndExit: (e: Error) = const { traceAttachment } = await import('./traceAttachments'); traceAttachment(attachmentId, options).catch(logErrorAndExit); }); - - traceCommand - .command('install-skill') - .description('install SKILL.md for LLM integration') - .action(async () => { - const { installSkill } = await import('./installSkill'); - installSkill().catch(logErrorAndExit); - }); }