Playwright Inspector完全ガイド｜page.pause()とcodegenでテストをデバッグする方法

Playwright Inspectorは、テストの実行中に一時停止し、1ステップずつ動かしながら原因を探せるデバッグツールです。「ロケーターが合っているのに失敗する」「どの操作で画面がおかしくなるのか見えない」といった場面で役に立ちます。この記事では、Python（pytest）での起動方法、ステップ実行の見方、Pick locator、codegen、そして実務で起きやすい失敗例までを整理します。

最大のポイントは「Inspectorは手元で止めて見るための道具で、CIや再現しにくい不具合には向かない」という役割の違いです。Trace Viewerと使い分けると、原因調査が速くなります。

📌 この記事はこんな方におすすめ

テストが失敗したとき、print()やスクリーンショットだけで原因を探しているPlaywright（Python）ユーザー
ロケーターを何度も書き直しながら、実行と確認を繰り返している方
page.pause()やPWDEBUGの存在は知っているが、使い方に自信がない方
Node版の--debugの説明を読んで、Pythonでの書き方がわからない方

✅ この記事を読むと得られること

Inspectorの起動方法と、codegenでテストコードを生成する方法
ステップ実行とPick locatorの基本的な使い方
codegenで雛形を作るときの注意点
Inspector・Trace Viewer・DevToolsの使い分け

👤 この記事を書いた人

QAエンジニア・テスト自動化エンジニアとして15年以上の実務経験を持つ Yoshi が執筆。Playwrightのテスト不具合調査や、デバッグ手順の整備を実務で担当してきました。

📌 結論

Playwright Inspectorは、page.pause()またはPWDEBUG=1で起動し、手元で止めながら原因を確認できる
Inspectorで操作を1つずつ進めると、タイミング起因の不具合は再現しにくくなることがある。通常実行でだけ起きる問題は、Trace Viewerで確認する
page.pause()とPWDEBUGは、コミット前・CI実行前に外れていることを確認する

デバッグ作業では、次のような悩みが出やすいです。

失敗した行は分かるが、その時点で画面がどうなっていたのか分からない
ロケーターを書き直すたびに、テスト全体を最初から実行している
デバッグ用に入れたpage.pause()を消し忘れて、CIが止まった
Inspectorで動かすと通るのに、普通に実行すると落ちる

これらは、Inspectorの得意なことと苦手なことを押さえると整理しやすくなります。

Playwright Inspectorとは
① Playwright Inspectorの起動方法【Python・pytest】
② ステップ実行の見方
③ Pick locatorでロケーターを確認する
④ codegenでテストの雛形を作る
⑤ Playwright InspectorとTrace Viewerの使い分け
実務でよくある失敗パターン
1. 消し忘れ対策：コミット前にチェックする
FAQ
📋 まとめ

Playwright Inspectorとは

Playwright Inspectorは、テストを一時停止し、操作を1つずつ進めながら、その時点のブラウザ画面を確認できるGUIツールです。ステップ実行のほか、ロケーターの検証や、操作の記録（codegen）にも使えます。

ツール	タイミング	メリット	デメリット
Inspector	実行中（リアルタイム）	1ステップずつ止めて、画面とロケーターをその場で確認できる	headedで手元実行が前提。1つずつ進めるため、タイミング起因の不具合は再現しにくくなることがある
Trace Viewer	実行後（振り返り）	CIで失敗した実行も、後から手元で再生して確認できる	実行中に操作したり、その場でロケーターを試したりはできない
DevTools	ブラウザ上（手動）	DOM、Console、Networkを詳しく調べられる	テストの実行位置とは連動しない

💡 補足：Node版（JavaScript）ではnpx playwright test --debugでInspectorを起動します。このコマンドはNode.js版のPlaywright Test向けで、Python環境ではそのまま使えません。Python（pytest-playwright）では、環境変数のPWDEBUGやpage.pause()を使います。Python版の最新の仕様は、使用バージョンの公式ドキュメントで確認してください。

① Playwright Inspectorの起動方法【Python・pytest】

Playwright Inspectorを使ってデバッグする方法と、codegenでテストコードを生成する方法は分けて考えましょう。page.pause()やPWDEBUG=1は実行中のテストを確認するときに使い、playwright codegenはブラウザ操作からテストコードの雛形を作るときに使います。

方法	止まる場所	向いている場面
`page.pause()`	書いた行	怪しい箇所の直前で止めて確認したいとき
`PWDEBUG=1`	最初の操作の前	テストを最初から順に追いたいとき
`playwright codegen`	（記録モード）	デバッグではなく、操作を記録して雛形を作りたいとき

from playwright.sync_api import Page, expect

def test_login(page: Page) -> None:
    page.goto("https://example.com/login")  # 実際のURLに置き換える
    page.get_by_label("メールアドレス").fill("user@example.com")

    page.pause()  # ここで一時停止し、Inspectorが開く（デバッグ後は削除する）

    page.get_by_role("button", name="ログイン").click()

    # 実際の画面仕様に合わせて検証条件を設定する
    expect(page.get_by_role("heading", name="マイページ")).to_be_visible()

💡 補足：example.comと見出し名は説明用です。実際のテスト対象に合わせて変更してください。page.goto("/login")のように相対URLで書く場合は、pytest --base-url https://example.comのようにbase_urlの設定が必要です。

# page.pause() は headed モードで実行する
pytest tests/test_login.py --headed

# 最初からステップ実行したい場合（macOS / Linux）
PWDEBUG=1 pytest tests/test_login.py -s

# Windows（PowerShell）の場合
$env:PWDEBUG=1; pytest tests/test_login.py -s

# デバッグが終わったら、環境変数を解除する（PowerShell）
Remove-Item Env:PWDEBUG

⚠️ 注意：page.pause()は、headedモードで実行しないと一時停止しません。headlessで実行すると素通りするため、「止まらない」と感じたら--headedの有無を確認してください。

② ステップ実行の見方

Inspectorが開いたら、次の流れで確認します。画面の表記はバージョンで変わることがあるため、大まかな使い方として捉えてください。

操作	できること
Resume	一時停止を解除して、テストを再開する。次の停止条件（別の`page.pause()`など）がなければ、そのまま処理を続ける
Step over	操作を1つだけ実行して、また止まる
アクションのログ	実行された操作と、対象要素・待機の状況を確認する

✅ ポイント：1ステップ進めるたびに、ブラウザ側で「どの要素が強調表示されたか」を見ます。意図と違う要素が光っていたら、ロケーターが別の要素に当たっているサインです。

③ Pick locatorでロケーターを確認する

Inspectorの「Pick locator」を押してブラウザ上の要素をクリックすると、その要素を指すLocatorの候補が表示されます。表示されたLocatorは編集して、画面上で何個の要素に一致するかをその場で確認できます。

一致する要素が1個であることを確認する（複数ならstrict modeのエラーになりやすい）
候補がnth()や長いCSSセレクターになっていたら、get_by_role()やfilter()で書き直せないか考える
確定したLocatorは、テストコードに貼ってから実行して確かめる

🔍 実務あるある：Pick locatorは、ロール・テキスト・テストIDなどを優先しつつ、その時点の画面で一意になるようにLocatorの候補を示します。ただし、将来の画面変更にも強いとは限りません。候補をそのまま採用せず、意図が読み取れる形に整えておくと保守が楽になります。

④ codegenでテストの雛形を作る

# 操作を記録し、pytest形式のコードを出力する
playwright codegen --target python-pytest -o tests/test_recorded.py https://example.com

# ログイン状態を保存しておく（storage_state 用）
playwright codegen --save-storage=auth.json https://example.com/login

# 保存した認証状態を読み込んで、ログイン後の画面から操作を記録する
playwright codegen --load-storage=auth.json https://example.com

# 保存した auth.json は .gitignore に追加する
# echo "auth.json" >> .gitignore

⚠️ 注意：ログイン操作を記録すると、入力したパスワードが生成コードに含まれる場合があります。テスト専用アカウントを使い、認証情報は環境変数（.envなど）から読み込む形に変更してからコミットしましょう。

また、--save-storageで生成するauth.jsonには、ログイン状態を復元できる情報（Cookieやローカルストレージなど）が含まれる場合があります。パスワードが書かれていなくても機密情報として扱い、Git管理対象から除外してください。すでにGit管理されている場合は、.gitignoreに追加するだけでは除外されないため、追跡対象から外す必要があります。誤って公開した場合は、必要に応じてセッションの無効化や認証情報の変更も検討します。

💡 実務Tip：codegenは、ブラウザで行った操作をもとにテストコードを生成します。Inspectorのアサーション機能を使えば、要素の表示状態・テキスト・値などの検証コードも追加できます。ただし、業務上重要な結果や境界値まで自動で網羅できるわけではありません。生成したコードを確認し、必要なアサーションを追加しましょう。

⑤ Playwright InspectorとTrace Viewerの使い分け

PWDEBUG=1で実行すると、ブラウザがheadedモードで起動し、デフォルトのタイムアウトが無効になります。一方、page.pause()を--headedで使う方法では、通常のタイムアウト設定が維持されます。デバッグ中は操作を1つずつ進めるため、タイミング起因の不具合は再現しにくくなることがあります。通常実行でだけ発生する問題は、Trace Viewerで失敗時の画面状態やNetworkログを確認する方法も有効です。

症状	まず使うツール
ロケーターが意図した要素に当たっているか確かめたい	Inspector（Pick locator）
処理の途中の画面状態を1つずつ見たい	Inspector（Step over）
CIでだけ落ちる、たまに落ちる	Trace Viewer
APIの応答内容やステータスを確認したい	Trace ViewerのNetwork、またはDevTools

実務でよくある失敗パターン

① page.pause()を消し忘れてコミットし、CIが止まる

headlessなら素通りしますが、xvfbなどでheadedのままCIを回している環境では、一時停止したまま進まなくなります。コミット前の確認と、CIでの機械的なチェック（後述）を組み合わせると安心です。

② PWDEBUG=1を環境に残したままCIで実行する

PWDEBUG=1ではブラウザがheadedで起動し、デフォルトのタイムアウトが無効になります。「無限に待つ」という意味ではありませんが、通常のタイムアウトで失敗しなくなるため、終わらない処理があるとジョブが長時間止まることがあります。CIの環境変数に、デバッグ用の値が混ざっていないか確認します。

③ codegenの出力に、パスワードがそのまま残る

記録したログイン情報をそのままリポジトリに入れてしまう失敗です。テスト専用アカウントを使い、認証情報を.envなどに移してからコミットします。auth.jsonも機密情報として.gitignoreに入れます。

④ Inspectorでは通るのに、通常実行では落ちる

操作を1つずつ進めると、タイミング起因の不具合が再現しにくくなることがあります。Trace Viewerで失敗した実行を確認し、必要に応じてexpect_response()などの明示的な待機を足します。

⑤ Pick locatorの候補を、確認せずに採用する

その時点の画面でしか一意にならない候補を採用すると、あとで複数一致のエラーになります。意図が分かる形に書き直してから使います。

消し忘れ対策：コミット前にチェックする

# tests/ 配下に page.pause() が残っていたら失敗させる（CIやpre-commitで実行）
if grep -rn "page.pause()" tests/; then
  echo "page.pause() が残っています。削除してください。"
  exit 1
fi

🔍 チェックの限界：このスクリプトはpage.pause()という文字列を探すだけです。コメントに書かれた文字列にも反応し、表記揺れやPWDEBUGの設定は検出できません。コードレビューやCIの環境変数の確認と組み合わせて使ってください。

📖 関連記事

FAQ

Q. InspectorとTrace Viewerは、どう使い分けますか？

Inspectorは「実行中に止めて確認する」ツールで、手元で原因を探るときに向いています。Trace Viewerは「実行後に振り返る」ツールで、CIで失敗した実行を確認するときに向いています。

Q. CIでInspectorを使えますか？

基本的には、手元の開発環境で使うものです。CIでの原因調査には、Trace Viewerやスクリーンショット・動画のほうが向いています。

Q. headlessモードでもInspectorは使えますか？

page.pause()は、headedモードでの実行が前提です。PWDEBUG=1で起動した場合はheadedで実行されますが、詳細な挙動は使用バージョンの公式ドキュメントで確認してください。

Q. Node版の–debugと同じものですか？

目的は同じで、どちらもInspectorを起動します。ただしPython（pytest）では--debugオプションではなく、PWDEBUG環境変数やpage.pause()で起動します。

Q. codegenの出力は、そのままテストに使えますか？

動作確認の起点としては便利ですが、そのまま使うことはおすすめしません。必要な検証が足りない場合があり、認証情報が含まれることもあるため、確認と整理をしてから取り込みます。

📋 まとめ

Playwright Inspectorはpage.pause()またはPWDEBUG=1で起動し、実行中に止めて確認する
page.pause()はheadedモードで実行する
Pick locatorの候補は、意図が読み取れる形に整えてから採用する
codegenの出力はパスワードやauth.jsonの扱いに注意し、たたき台として使う
タイミング起因の不具合は、Trace Viewerで確認する
page.pause()とPWDEBUGは、コミット前・CI実行前に外す

まずは、いま手元で失敗しているテストの怪しい行の前にpage.pause()を1行足して、--headedで実行してみてください。画面を見ながらLocatorを確かめるだけで、原因に近づけることが多いです。