SKILL ARTICLE / playwright-trace-failure-triage
失敗したブラウザーテストを、証拠から切り分ける
失敗画面だけで決めつけず、前後の証拠から次の一手を選ぶ。
Playwright Trace Viewerで確認できる操作、DOM、エラー、通信、ソース位置を、確認済みの事実と原因仮説に分け、最小の再実行範囲まで整理するSkill案です。
この記事で紹介するSkill案は、参考資料を読んだうえで私が考えたものです。参照先が提供・評価・推奨しているものではありません。
OVERVIEW → CAN DO → BUILD
知ったことをSkillづくりに活かす
失敗時の操作、DOM、エラー、通信、ソース位置を同じ時系列で見られると、最後の画面だけに引っ張られず原因候補を絞れる。
画面、ログ、通信、ソースを根拠に、直す前に確かめる原因候補と再実行範囲を決められる。
赤いエラー位置は原因そのものとは限りません。操作、DOM、Console、Network、ソース位置から確認できた内容と、そこから考えた原因候補を分け、仮説ごとに支持する証拠と反証条件を残します。
01 / OVERVIEW
資料の概要
MicrosoftのPlaywright公式リポジトリにある「Trace viewer」は、テスト実行後のトレースを調べるGUIツールを説明した資料です。この記事では、2026年5月11日公開のPlaywright v1.60.0、Node.js版の公式資料を確認しました。対象環境として、公式のSystem requirementsにはNode.js 20.x、22.x、24.xと、対応OSが示されています。
資料では、操作ごとのlocatorと所要時間、操作前後のDOM snapshot、ソース位置、エラー、Console、Network、Metadata、Attachmentsを確認できます。CIでは最初のretryで記録する `on-first-retry` が案内され、毎回記録する `on` は負荷が大きいため推奨されていません。retryを使わない場合は、失敗した実行のtraceを残す `retain-on-failure` も選べます。
これはPlaywrightのデバッグ機能を説明する公式資料であり、失敗原因を自動判定するSkillの提供、評価、推奨ではありません。以下は、公式機能から自分たちで考えたSkill案です。
02 / CAN DO
できるようになること
Trace Viewerが見せる情報を、ただ眺めて終わらせず、失敗直前の操作、期待と異なるDOM、エラー、Console、Network、該当ソースを同じ時系列で整理します。出力は「確認できた事実」「原因の仮説」「まだ不足している証拠」「次に再実行する最小範囲」に分けます。
たとえばボタン操作後の失敗でも、画面だけからlocatorの問題だと決めつけません。操作ログ、対象DOM、関連する通信状態、エラー位置を並べ、どの仮説がどの証拠で支持されるかを示します。修正や再実行は人が選び、Skillは根拠のない自動変更やテスト全体の再実行を行いません。
活かしやすい場面
- CIでPlaywrightテストが失敗し、traceを保存しているチーム
- スクリーンショットだけでは原因を絞れないE2Eテスト
- flakyな失敗の試行条件と証拠を揃えたい場面
使う前に確認したい場面
- traceが保存されていない失敗の原因確定
- Playwright以外のテスト結果を同じ手順で解析する作業
- 証拠を確認せず自動でコードを修正・公開する運用
03 / BUILD
自分たちのSkill作成に活かせること
文章やコードをそのまままねるのではなく、自分たちのSkillに取り入れたい判断基準や工程の分け方を整理しました。
事実と原因仮説を別欄にする
赤いエラー位置は原因そのものとは限りません。操作、DOM、Console、Network、ソース位置から確認できた内容と、そこから考えた原因候補を分け、仮説ごとに支持する証拠と反証条件を残します。
失敗した試行を取り違えない
`on-first-retry` で残るのは最初のretryのtraceです。初回失敗とretryで現象が変わる可能性があるため、実行番号、project、browser、時刻、retry設定を入力に含め、どの試行を調べたかを明示します。
再実行を最小の確認手段にする
原因候補を並べるだけでなく、対象test、project、必要なtrace設定、期待する観測結果を一つの再実行案にします。対象が絞れない場合は、推測で修正せず不足資料を返します。
04 / WORKFLOW
Skillにするときの流れ
- 01
試行を特定
trace、test名、project、browser、retry番号、実行時刻を対応付ける。
- 02
証拠を時系列化
失敗直前のAction、DOM、Errors、Console、Network、ソース位置を並べる。
- 03
最小再実行を提案
事実と仮説を分け、対象testと確認したい観測結果を一つに絞る。
05 / TRY
試すときに使える依頼文
これは完成したSkillではありません。先に依頼文として試し、期待する結果が返ってくるかを確かめるための試作プロンプトです。
このPlaywrightテストの失敗を調べてください。まずtrace.zip、test名、project、browser、retry番号、実行時刻を対応付け、失敗直前のAction、DOM、Errors、Console、Network、ソース位置を確認してください。結果は、確認済みの事実、原因仮説、仮説を支持する証拠、不足証拠、次に行う最小の再実行案に分けてください。コード変更や再実行はまだ行わず、trace内の秘密情報や個人情報を出力しないでください。06 / BUILD BRIEF
試作するときの設計メモ
これは配布済みのSkillではありません。対象を小さく絞り、停止条件と評価ケースを足しながら確かめるための出発点です。
Playwrightの失敗traceを根拠付きの調査票へ変換するSkillを作る。
入力はtrace、test名、project、browser、retry番号、実行時刻、対象ソースとする。
Action、DOM、Errors、Console、Network、ソース位置を失敗前後の時間帯で照合し、事実と仮説を分ける。
出力は「事実・仮説・支持証拠・反証条件・不足証拠・最小再実行」に固定する。
機密情報を伏せ、コード変更や外部送信、再実行は明示的な承認後だけにする。07 / WATCHOUTS
人が確認するところ
- traceにはDOM、ソース、Console、通信のheaderやbodyが含まれ得ます。外部共有前に秘密情報、個人情報、顧客データを確認し、組織の保管規則に従います。
- 公式資料ではtrace.playwright.devはtraceをブラウザー内で処理し外部送信しないと説明されていますが、機密traceは組織方針を優先し、ローカルの `show-trace` を選びます。
- Skillは失敗調査だけを行い、コード変更、外部送信、全テスト再実行を無確認で実施しません。