「CIでだけテストが失敗するけど、ログだけでは原因がわからない」——Playwrightにはそんな悩みを解決する強力な機能、Trace Viewerがあります。テスト実行時の操作・スクリーンショット・ネットワーク通信・コンソールログを1つのファイルに記録し、後からtrace.zipをブラウザ上で”再生”して確認できます。この記事では、Trace Viewerの記録設定から画面の見方、実践的なデバッグの流れまでを解説します。
テストが失敗したとき、「もう一度実行して再現するか祈る」状態から抜け出せるのがTrace Viewerです。一度使い方を覚えると、原因調査にかかる時間が大きく変わります。
📌 この記事はこんな方におすすめ
- Playwrightでテストが失敗したとき、ログだけで原因を推測するのに苦労している方
- Trace Viewerという機能の名前は知っているが、使い方がよくわからない方
- CI環境で失敗したテストの原因を、手元の環境で再現できずに困っている方
- Trace Viewerの画面の各パネルが何を示しているのか整理したい方
✅ この記事を読むと得られること
- Traceを記録するための設定方法と、それぞれの選択肢の違いがわかる
- Trace Viewerの画面構成（Actions・Timeline・Snapshots等）の見方がわかる
- 実際にテストが失敗したときの調査の進め方が具体的にイメージできる
👤 この記事を書いた人
QAエンジニア・テスト自動化エンジニアとして15年以上の実務経験を持つ Yoshi が執筆。Playwrightを使ったテスト基盤の構築・運用の中で、Trace Viewerを日常的な原因調査ツールとして活用しています。
📌 結論
- Trace Viewerは、テスト実行中の操作・スクリーンショット・ネットワーク・コンソールを1ファイルに記録し、後から詳細に確認できる機能
- 記録設定（on/off/retain-on-failure等）を目的に応じて選ぶことで、必要な情報だけを効率的に残せる
- trace.playwright.devを使えば、インストールなしでブラウザ上からtrace.zipを開いて確認できる
Playwrightのテストが失敗したとき、多くの場合こんな状況に陥ります。
- エラーメッセージだけでは、実際に画面がどんな状態だったのか分からない
- ローカルでは再現せず、CI環境でだけ発生する
- スクリーンショットは撮れているが、失敗直前の一連の操作の流れが見えない
Trace Viewerは、これらの状況を解決するためにPlaywrightに組み込まれた機能です。この記事では、設定方法から実際の使い方までを順番に見ていきます。
Trace Viewerとは何か
Trace Viewerは、Playwrightのテスト実行中に発生する以下の情報を、1つのZIPファイル（trace.zip）にまとめて記録する機能です。
- 実行された各アクション（click・fill・gotoなど）の一覧
- 各アクションの前後のDOMスナップショット（画面の見た目を再現できる）
- ネットワークリクエスト・レスポンスのログ
- コンソールログ（JSエラーなど）
- 各アクションが呼び出されたテストコードの行
これらを記録しておくことで、テスト実行後にブラウザ上で「何が起きたか」を時系列に沿って詳細に確認できます。
① Traceを記録する：設定方法の選択肢
Traceは常に記録されるわけではなく、明示的に設定する必要があります。pytest-playwrightを使っている場合、--tracingオプションで挙動を指定します。
# 失敗したテストのみTraceを保存する（最も一般的な使い方）
pytest --tracing retain-on-failure
# 全テストで常にTraceを保存する
pytest --tracing on
# Traceを保存しない（デフォルト）
pytest --tracing off| 設定 | 動作 | 向いている場面 |
|---|---|---|
off | 記録しない（デフォルト） | 通常の実行・CI高速化を優先したい場合 |
retain-on-failure | 失敗したテストのみ保存し、成功したテストの記録は破棄 | CI環境での標準的な運用（おすすめ） |
on | 成功・失敗を問わず全テストを記録 | 新しいテストを作成中で、動作を細かく確認したいとき |
pip install pytest-playwright）を使用している場合の例です。標準のpytestコマンドには--tracingオプションはありません。指定できる値やオプション名はプラグインのバージョンによって変わる場合があるため、最新の情報は公式ドキュメントを確認することをおすすめします。--tracing onを常時CI設定に入れっぱなしにしていると、テストが増えるにつれてTraceファイルの保存容量が膨らみ、CIのアーティファクト容量を圧迫することがあります。特別な理由がなければ、CI環境ではretain-on-failureを基本設定にしておくのが無難です。② Trace Viewerを開く方法
記録されたtrace.zipを開く方法は、大きく2通りあります。
方法1：コマンドラインから開く
playwright show-trace trace.zipこのコマンドを実行すると、ローカルでビューアが起動し、ブラウザでTrace Viewerの画面が開きます。
方法2：trace.playwright.dev にドラッグ＆ドロップする
trace.playwright.dev は、Playwright公式が提供しているオンラインのTrace Viewerです。trace.zipファイルをブラウザにドラッグ＆ドロップするだけで、インストールなしに中身を確認できます。
③ 画面の見方
Trace Viewerの画面は、いくつかのパネルに分かれています。それぞれが示す情報を理解しておくと、調査がスムーズになります。
| パネル | 確認できる内容 |
|---|---|
| Actions（左側の一覧） | 実行された操作（click・fill・gotoなど）が時系列で並ぶ一覧。クリックするとその時点の状態にジャンプできる |
| Timeline（上部） | テスト全体の流れを視覚的なタイムラインで表示。特定の区間をクリックしてその時点にジャンプできる |
| Snapshots（Before/Action/After） | 選択したアクションの「実行前」「実行中」「実行後」の画面状態をそれぞれ確認できる |
| Network | 発生したネットワークリクエストとレスポンスの一覧・詳細 |
| Console | ブラウザのコンソールに出力されたログ・エラー |
| Source | 選択したアクションに対応するテストコードの該当行 |
| Call | 選択したアクションに渡された具体的なパラメータや実行結果 |
④ 実践的なデバッグの流れ
実際にテストが失敗したとき、どのようにTrace Viewerを使って調査を進めるか、具体的な手順の一例です。
- Actions一覧の一番下（赤く表示されている失敗箇所）を確認する——どのアクションで失敗したかを特定する
- 失敗したアクションのSnapshots（Before/After）を見る——期待していた要素が本当に存在しなかったのか、それとも別の理由か確認する
- Networkタブで直前のAPI通信を確認する——想定より応答が遅い、エラーレスポンスが返っている、といった非同期処理の問題がないか見る
- Consoleタブを確認する——JSエラーが操作を妨げていないか確認する
- Sourceタブで該当のテストコードを確認する——ロケーターや待機条件がそもそも適切だったか見直す
⑤ CI環境でのTrace活用
CI環境では、テストが失敗してもその場でTrace Viewerを開くことはできません。Traceファイルをアーティファクトとして保存し、後からダウンロードして確認する運用が基本になります。
GitHub Actionsでの設定例
- name: Run Playwright tests
run: pytest --tracing retain-on-failure
- name: Upload trace
if: failure()
uses: actions/upload-artifact@v4
with:
name: playwright-traces
path: test-resultstest-results は pytest-playwright のデフォルトの保存先です。プロジェクト側で出力先を変更している場合は、実際に使用しているディレクトリを指定してください。ここが一致していないと、テストは失敗しているのにArtifactsが空、という状態になってしまいます。この設定により、テストが失敗した場合のみTraceがGitHub Actionsのアーティファクトとして保存されます。ダウンロード後は、次のいずれかの方法で確認できます。
- ローカルにダウンロードして
playwright show-trace trace.zipで開く - trace.playwright.dev にドラッグ＆ドロップして開く（インストール不要）
実務でよくある失敗パターン
① Trace設定を忘れて、失敗しても何も記録されていない
せっかくCIでテストが失敗しても、--tracingオプションを設定し忘れていると調査材料が何も残りません。CI設定の初期段階でretain-on-failureを組み込んでおくことをおすすめします。
② Actionsの一覧だけ見て、Network・Consoleタブを見ずに終わる
画面の見た目だけで判断すると、非同期処理の遅延やJSエラーが原因のケースを見逃しがちです。原因が分からないときほど、Network・Consoleタブまで一通り確認する習慣をつけましょう。
③ CI環境で --tracing on を使い続け、アーティファクト容量を圧迫する
開発初期の検証目的で on を使っていたのをそのまま本運用に持ち込んでしまうケースです。Traceはスクリーンショットやスナップショットを含むため容量が大きくなりがちで、CIのアーティファクト保存容量やコストに影響することがあります。運用が安定したら retain-on-failure に切り替えることをおすすめします。
④ ローカルで再現しないからとTrace調査を後回しにする
「ローカルで再現しないから、また今度でいいか」とCI失敗を放置してしまうと、原因が積み重なっていきます。Traceがあればローカルで再現できなくても実際に起きた状況を確認できるので、後回しにせずその場で調査する習慣をつけると、原因の特定が早くなります。
📖 関連記事
FAQ
Q. Traceファイルはどのくらいの容量になりますか？
テストの長さやページの複雑さによって大きく異なります。スクリーンショットやDOMスナップショットを多数含むため、数MBから数十MB程度になることもあります。容量が気になる場合は、retain-on-failureを使って失敗時のみ保存する運用にすることで抑えられます。
Q. Trace ViewerとPlaywright Inspector（デバッグモード）は何が違いますか？
Playwright Inspectorはテスト実行中にリアルタイムでステップ実行しながらデバッグするためのツールです。一方Trace Viewerは、すでに完了したテスト実行の記録を後から振り返って確認するためのツールという違いがあります。目的に応じて使い分けます。
Q. 成功したテストのTraceも見る意味はありますか？
あります。新しいテストを作成しているときに、想定通りの操作が行われているかを確認する用途で有効です。ただし常時記録すると容量が増えるため、テスト作成中はon、安定運用後はretain-on-failureのように使い分けるとよいでしょう。
Q. trace.playwright.dev にアップロードしたファイルは外部に送信されますか？
trace.playwright.devは、ブラウザ内でファイルを処理する仕組みを採用しています。ただし機密性の高いデータを扱う場合は、念のため公式ドキュメントで具体的な処理方式を確認し、必要であればローカルのplaywright show-traceコマンドを使う方が安心です。
Q. retain-on-failure と retain-on-first-failure は何が違いますか？
retain-on-failureは、リトライを含めて最終的に失敗したテストのTraceを保存します。一方retain-on-first-failureは、リトライ設定がある場合に「最初の失敗時点」のTraceのみを保存する挙動です。リトライ後に成功したテストでも、最初になぜ失敗したのかを確認したい場合に使い分けます。具体的な挙動はバージョンによって変わる可能性があるため、使用前に公式ドキュメントで確認することをおすすめします。
Q. SeleniumにもTrace Viewerのような機能はありますか？
SeleniumにはPlaywrightのTrace Viewerに相当する標準機能はありません。Seleniumでの原因調査は、スクリーンショットの手動取得やブラウザログの確認、外部ツールとの組み合わせが中心になります。この違いも、PlaywrightとSeleniumを比較する際によく挙げられるポイントの一つです。
📋 まとめ
- Trace Viewerは操作・スクリーンショット・ネットワーク・コンソールを1ファイルに記録し、後から詳細に確認できる機能
- CI環境ではretain-on-failureを基本にし、失敗時のみ記録することで容量とのバランスを取る
- 調査の基本はActions一覧で失敗箇所を特定→前後のSnapshotsを比較→Network/Consoleも確認という流れ
- trace.playwright.devを使えば、インストールなしでチームメンバーとも手軽に共有・確認できる
Trace Viewerは、一度使い方を覚えてしまえば「テストが落ちた理由が分からない」という状況にかかる時間を大きく減らしてくれるツールです。まずはCI設定に--tracing retain-on-failureを追加するところから始めてみてください。
