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 収集の設定

例

// ファイルパス:playwright.config.ts
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 ViewerCI の失敗の特定、複雑なテストの各ステップの分析
--debug / page.pause()新しいテストの開発、特定のステップの詳細なデバッグ
その他の拡張