Playwright デバッグツール
この章では、Playwright の3大デバッグツールである UI Mode、Trace Viewer、コマンドライン Debug モードを紹介します。
UI Mode 完全ガイド
UI Mode は Playwright に組み込まれたグラフィカルなテストインターフェースで、テストの探索、実行、デバッグのワンストップ体験を提供します。
UI Mode を起動する
npx playwright test --ui
テスト一覧の表示
起動すると、左側のサイドバーにすべてのテストファイルが表示されます。
各ファイルとdescribeブロックを展開し、各テストを個別に実行、表示、Watch、またはデバッグできます。
Watch Mode
Watch ボタンをクリックすると、Playwright はファイルの変更を監視し、テストコードまたはソースコードが更新されると、影響を受けるテストを自動的に再実行します。
タイムライン表示(Timeline)
テスト実行後、上部にタイムラインが表示され、ナビゲーションと操作が異なる色でマークされます。
ホバーして各ステップのスナップショットを表示したり、ダブルクリックで時間帯を選択して、その時間帯の詳細なログを確認できます。
DOM Snapshot
タイムライン内のステップをクリックすると、右側にその時点の DOM スナップショットが表示されます。
操作前後のページの実際の状態を確認でき、問題を素早く特定できます。
テストのフィルタリング
UI Mode は複数のフィルタリング方法をサポートしています:
- テスト名で検索
- 按
@tag
フィルタリング - プロジェクト(Project)でフィルタリング
- ステータスでフィルタリング:成功(passed)、失敗(failed)、スキップ(skipped)
Trace Viewer での高度なデバッグ
Trace Viewer は Playwright の記録・再生ツールであり、録画をデバッグするようにテストの各ステップを確認できます。。
Trace 収集の設定
例
export default defineConfig({
use: {
// 失敗時のリトライ時のみ Trace を収集
trace: 'on-first-retry',
// 設定可能な値:
// 'off' —— 収集しない
// 'on' —— 毎回収集する
// 'on-first-retry' —— 最初のリトライ時のみ収集(推奨)
// 'retain-on-failure' —— 失敗時のみ Trace を保持
},
});
Trace を開く
# 本地打开 npx playwright show-trace path/to/trace.zip
また、アップロードしてtrace.playwright.devオンラインで表示することもできます。
Trace に含まれる情報
| 内容 | 説明 |
|---|---|
| DOM スナップショット | 各ステップ実行前後の完全なページ DOM スナップショット |
| ネットワークリクエスト | すべての HTTP リクエストとレスポンス(URL、ステータスコード、Header、Body) |
| コンソールログ | ブラウザコンソールに出力されたすべてのメッセージ |
| スクリーンショット | 各ステップのページスクリーンショット |
| 操作記録 | すべての Playwright 操作の呼び出しパラメータと実行時間 |
| ソースコード | 各操作に対応するテストソースコードの位置 |
Trace を使用した失敗の特定
Trace Viewer のタイムラインで失敗したステップを見つけ、そのステップ前後のページの DOM 状態とネットワークリクエストを確認して、失敗の原因を特定します。
Trace は最も強力なデバッグツールです。CI でテストが失敗したがローカルで再現できない場合は、CI が生成した Trace ファイルをダウンロードして、オフラインで失敗の原因を分析できます。
--debug モードと page.pause()
--debug コマンドラインモード
npx playwright test --debug
機能:
- Playwright Inspector ウィンドウを自動的に開く
- 操作ごとにステップ実行
- ブラウザの DevTools でデバッグ
- を使用して
F10
(Step Over)とF11
(Step Into)で実行を制御します
page.pause() による実行の一時停止
例
test('デバッグ用テスト', async ({ page }) => {
await page.goto('https://www.example.com/');
// 実行を一時停止し、Inspector を開く
await page.pause();
// Inspector で後続の操作をステップ実行できます
await page.getByText('サンプル チュートリアル').click();
});
を使用してpage.pause()テストを実行すると、Playwright が自動的に Inspector ウィンドウを開き、ステップごとにページの状態を確認できます。
3つのデバッグ方法の選択
| 方法 | 適用シーン |
|---|---|
| UI Mode | 日常開発、テスト一覧の閲覧、テストステータスの素早い確認 |
| Trace Viewer | CI の失敗の特定、複雑なテストの各ステップの分析 |
| --debug / page.pause() | 新しいテストの開発、特定のステップの詳細なデバッグ |