playwright-trace

Playwright Trace CLI

无需打开浏览器，即可检查 Playwright 测试生成的 .zip 跟踪文件。

工作流

1. 从 trace open <trace.zip> 开始，提取跟踪文件并查看其元数据。
2. 使用 trace actions 查看所有操作及其操作 ID。
3. 使用 trace action <action-id> 深入查看特定操作——查看参数、日志、源位置和可用快照。
4. 使用 trace requests、trace console 或 trace errors 查看跨操作的汇总信息。
5. 使用 trace snapshot <action-id> 获取 DOM 快照，或针对该快照运行浏览器命令。
6. 完成后，使用 trace close 删除提取的跟踪数据。

open 之后的所有命令都会操作当前打开的跟踪文件，无需再次传入跟踪文件。打开新的跟踪文件会替换之前的跟踪文件。

命令

打开跟踪文件

# Extract trace and show metadata: browser, viewport, duration, action/error counts
npx playwright trace open <trace.zip>

关闭跟踪文件

# Remove extracted trace data
npx playwright trace close

操作

# 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

操作详情

# Show full details for one action: params, result, logs, source, snapshots
npx playwright trace action <action-id>

action 命令会显示可用的快照阶段（before、action、after）以及提取这些快照的确切命令。

请求

# All network requests: start time (on the `trace actions` clock), 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

请求详情

# Show full details for one request: headers, body, security
npx playwright trace request <request-id>

控制台

# 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

# Filter by message text pattern
npx playwright trace console --grep "failed to fetch"

错误

# All errors with stack traces and associated actions
npx playwright trace errors

快照

snapshot 命令会将某个操作的 DOM 快照加载到无头浏览器中，并针对该快照运行单条浏览器命令。如果不提供浏览器命令，则会返回无障碍快照。

# Get the accessibility snapshot (default)
npx playwright trace snapshot <action-id>

# Use a specific phase
npx playwright trace snapshot <action-id> --phase before

# Run eval to query the DOM
npx playwright trace snapshot <action-id> -- eval "document.title"
npx playwright trace snapshot <action-id> -- eval "document.querySelector('#error').textContent"

# Eval on a specific element ref (from the snapshot)
npx playwright trace snapshot <action-id> -- eval "el => el.getAttribute('data-testid')" e5

# Take a screenshot of the snapshot
npx playwright trace snapshot <action-id> -- screenshot

# Redirect output to a file
npx playwright trace snapshot <action-id> -- eval "document.body.outerHTML" --filename=page.html
npx playwright trace snapshot <action-id> -- screenshot --filename=screenshot.png

对于冻结的快照，只有三种浏览器命令有用：snapshot、eval 和 screenshot。

附件

# 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

典型调查流程

# 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