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 の3つだけです。

添付ファイル

# 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