Playwright Test Agentsの自動修復をレビューする。期待値とskipの確認手順

Playwright Test AgentsのHealerがテストを直したら、成功件数だけでなく、期待値の変更とスキップの増減を確認しよう。Healerの公式指示には、要素の探し方の修正に加え、期待値の変更やtest.fixme()によるスキップも含まれる。修正後のテストが、元の仕様をまだ確かめているかを読む必要がある。1.64.0のHealer定義（英語）

この記事は、すでにPlaywrightでブラウザーテストを動かせる人向けのレビュー手順だ。公式資料と公開された利用者報告を照合したもので、編集部によるエージェント実行や成功率の測定は行っていない。

計画を承認してから、テストを生成する

Playwright Test Agentsには、アプリを調べて計画を書くPlanner、計画をテストコードにするGenerator、失敗を調べて修復するHealerがある。2025年10月の1.56で導入され、確認時の最新リリースは1.64.0だ。公式ガイド（英語）、1.64.0のリリース（英語）

動画：Playwright「Playwright v1.56: From MCP to Playwright Agents」（2025年10月6日、英語）。3役を使う流れの紹介。導入当時の画面なので、コマンドや対応クライアントは現行文書も確認したい。YouTubeで見る

最初に「どの結果が正しいか」を短く書く

例として、カートの商品小計を確認するテストを考える。仕様は「単価500円の商品を2個選ぶと、商品小計は1,000円」。送料や税の計算は今回は対象外とする。これは説明用の架空の仕様だ。

計画には、次の4点を残す。

• 要件ID：REQ-CART-01
• 開始条件：テスト用アカウント、対象商品、数量2
• 期待する結果：商品小計1,000円
• 仕様の根拠：承認済みの要件書や担当者の判断

画面に現在900円と出ていても、それをそのまま正解にしない。実際の画面は操作対象を調べる資料、要件書は正しい結果を決める資料として使う。食い違いが見つかったら、テストを書く前に確認する。

Plannerにはseed、Generatorには承認済みの計画を渡す

対象プロジェクトのターミナルで、利用するクライアントに合った定義を作る。例えばVS Codeなら次のコマンドを使う。

npx playwright init-agents --loop=vscode

現行ガイドにはclaude、codex、opencodeも掲載されている。Playwrightを更新したら、エージェント定義も再生成する。すでに独自の指示を加えている場合は、変更前のファイルを残し、差分を確認してから取り込もう。

画面の文字を拡大して読む

画像の中を縦・横にスクロールできます。

元の画面を別タブで開く →

Plannerには要件とseed.spec.tsを渡す。seed testは、ページを開くための初期化や、既存のテスト用設定を利用する起点になる。ログイン準備やテストデータなど、自分のプロジェクトで必要な状態から調べられるようにする。

Plannerの計画が出たら、操作手順だけでなく期待結果を読む。「数量を変えてページが表示される」だけでは小計を確かめられない。「何を、どの値と比較するか」まで確認し、その計画をGeneratorへ渡す。PlannerとGeneratorの入力・出力（英語）

画面の文字を拡大して読む

画像の中を縦・横にスクロールできます。

元の画面を別タブで開く →

生成後は、計画の文章、保存されたテストファイル、実行結果を別々に確認したい。Alan Schveitzer氏は2025年10月、1.56.1・VS Code 1.105.1・macOSで、計画は作れるものの、Generatorがチャットにコードを出すだけでファイルを保存できないと報告した。開発側の参加者は専用の保存ツールへのアクセス確認を案内している。この報告は後に非活動を理由に終了しており、現行版にも同じ問題があると断定する材料ではない。本人の報告と回答（英語）

Healerへ渡す前に、失敗と期待値を残す

動画：Playwright「[LAB]: How to Heal Failing Playwright Tests Automatically with the Healer Agent」（2025年10月28日、英語）。Healerが失敗を調べる操作例。この記事のカートを検証した動画ではない。YouTubeで見る

元の失敗を、Traceと差分でたどれるようにする

画面の文字を拡大して読む

画像の中を縦・横にスクロールできます。

元の画面を別タブで開く →

修復用の作業ブランチを用意し、失敗したテストを変更前の状態で実行する。対象ファイルがtests/cart.spec.tsなら、例えば次のようにTraceを有効にする。

npx playwright test tests/cart.spec.ts --trace on

Traceは、操作、画面の状態、ログ、通信などを後から調べるための記録だ。実行結果で案内されたtrace.zipを、npx playwright show-trace path/to/trace.zipで開く。path/to/trace.zipは実際の保存先へ置き換える。ErrorsとSourceを見て、どの操作や検証で落ちたのかを確認し、コードの版と実行条件も残す。共有する場合は、記録に含まれるログイン情報や業務データを確認する。Trace Viewerの公式説明（英語）

ここで、失敗を大まかに分ける。

• ボタン名などが変わり、対象を見つけられない
• 読み込みやテストデータの準備が終わっていない
• 実際の挙動が仕様と違う
• 仕様が正式に変わり、テスト側が古くなった

最後の二つを、ボタンの探し方の修正と一緒に扱わないことが大切だ。仕様が変わったなら、その根拠を確認して期待値を更新する。アプリ側の不具合なら、テストの期待値を変える前に、アプリの不具合として追跡する。

Healerの修正範囲は、差分でも確認する

1.64.0のHealer定義には、セレクター、待機、データだけでなくassertionとexpected valuesの修正も含まれる。assertionは、値や画面の状態が期待どおりかを検査する部分だ。テストが正しいと高い確信を持ったまま問題が続く場合は、コメントを付けてtest.fixme()にする指示もある。

test.fixme()は、そのテストを実行しないための指定だ。成功した検証とは数えず、未解決の項目として残す。test.fail()は実行して失敗することを期待する別の機能なので、名前が似ていても一括で置き換えない。Annotationsの仕様（英語）

自分の運用では、例えば次のように依頼できる。

REQ-CART-01と承認済みの計画を基準にしてください。まず失敗を再現し、原因を分類してください。要素の探し方、待機、テストデータの修正案を出してください。期待値、検証内容、比較用の基準画像、skipやfixmeを変える必要がある場合は、変更を適用せず、要件・理由・差分案を示して止めてください。

既定のHealer定義には、利用者へ質問せず修復を続ける指示もある。この依頼だけで変更を防げるとは考えず、実際のエージェント定義と、編集されたファイルを確認する。少なくとも、assertionの削除、比較値の変更、条件付きの回避、skip・fixme・onlyの追加、比較用の基準画像の更新はレビュー対象にしたい。onlyが残ると、他のテストが実行対象から外れる。

意図した不具合を、本当に検出できるか確かめる

前のカートの例なら、「小計の欄が見える」だけでは金額の間違いを検出できない。テストの検証部分は、例えば次のようになる。要素のIDと表示形式は説明用で、自分のアプリに合わせて置き換える。

await expect(page.getByTestId('cart-subtotal')).toHaveText('1,000円');

Playwrightのこの形式の検証は、条件が満たされるまで指定時間内で確認を繰り返す。逆に、固定時間待ってから見た目だけを確認するコードへ変わっていないかも読みたい。待機付きassertion（英語）

数字だけを変えた、別の検証を行う

使い捨てのローカル環境で、テストの期待値は1,000円のまま、アプリに渡す小計データだけを900円に変えて実行する。通信の応答を差し替える場合は、Playwrightのpage.route()とroute.fulfill()が使える。応答の差し替えは、画面遷移や数量変更など対象の通信が発生する操作より前に登録する。通信先、応答の構造、変更する項目を事前に確認し、本番や共有データを書き換えない。公式のAPIモック手順（英語）

画面の文字を拡大して読む

画像の中を縦・横にスクロールできます。

元の画面を別タブで開く →

見るべきなのは、テストが落ちた場所だ。

• 小計が「900円」なので「1,000円」との比較で落ちた：今回確認したい違いを検出できている
• ログインや初期表示で止まった：小計の検証まで到達していない
• テストが通った：金額を検証しているか、差し替えが対象の画面へ反映されたかを調べる

単に通信を切ってタイムアウトしただけでは、金額の間違いを検出した証拠にはならない。確認が終わったら応答差し替えを外し、通常の条件で再びテストを実行する。これは編集部が提案する確認方法で、公式Healerの自動機能ではない。

成功数と一緒に、実行数・スキップ数を見る

修復後は、変更差分とレポートを並べて確認する。画像比較の基準ファイルが更新されていたら、現在の画面を承認する変更になっていないか、画像そのものを見比べる。画像比較と正解画像の更新（英語）

採用前には、次をそろえる。

1. 元の要件と、今回のテストが確認する期待結果
2. 修復前の失敗箇所とTrace
3. 何を変更したか、期待値は維持されたか
4. 通常条件での再実行結果と、意図した不具合を検出した記録
5. 実行対象とスキップの増減、未解決の理由と追跡先

fixmeを使って一時的に止める判断が必要なこともある。その場合も、担当者と追跡用Issueを残しておけば、未解決のまま忘れることを防ぎやすい。「失敗が消えた」から一歩進み、「元の要件を確かめるテストとして使える」まで見届けたい。

調査方法

確認日：2026年10月12日JST。Playwright 1.64.0のエージェント定義、現行公式ガイド、公式動画、利用者本人のGitHub報告を照合した。カートの仕様、依頼文、検証の例は説明用で、実プロジェクトで試した成果ではない。モデルやクライアントが異なる環境での修復精度、時間、費用は比較していない。