pw-test-audit

プロジェクトのルールに照らして、Playwright の最新のテスト変更を監査してください。新しいエージェントセッションで実行しています。独立した視点で確認してください。前のエージェントの判断が正しかったと決めつけないでください。

このスキルでは、自律的に作業するよう指示されていても、AskUserQuestion の手順を決して省略しないでください。

手順

1. 最新の変更を特定する

未コミットの変更を確認します。これが監査対象のすべてです。

git status --short
git diff HEAD

差分が空（未コミットの変更がない）の場合は、直ちに終了して、次のようにユーザーに伝えてください。

未コミットの変更はありません。レビュー対象となる新しいテストコードはありません。このスキルは最新の追加分のみを監査します。すでにコミット済みの場合は、変更を再度表示して（例：git reset --soft HEAD~1）、このスキルをもう一度実行してください。

過去のコミットにさかのぼったり、別の対象を選んで監査したりしないでください。問題なく終了してください。

差分があるものの、Playwright 関連ファイル（spec ファイル、ページオブジェクト、フィクスチャ、プロジェクトの E2E テストツリー配下のヘルパー）が含まれていない場合は、差分にレビュー対象の Playwright 変更がないことをユーザーに伝えて終了してください。

監査対象は、表示された差分のハンクに限定してください。変更されていないテスト、手を加えていないページオブジェクト、無関係なファイルはレビューしないでください。

2. プロジェクトのコンテキストを把握する

プロジェクトの Playwright ルールをすべて読んでください。プロジェクトで文書化されているルールの場所（一般的には .claude/rules/ ですが、異なる場合もあります）を調べ、実際のファイル名を特定してください。

• Playwright のスクリプティングルール：ロケーター、アサーション、待機、命名、コードスタイル、アクション、フォーム操作
• Playwright のアーキテクチャルール：POM の規約、フィクスチャ、認証設定、ディレクトリ構成

プロジェクトに Playwright のルールファイルがない場合は、既存のテストスイートから推測できる規約を適用してください（代表的な spec ファイルを2～3個と、テストユーティリティディレクトリの内容を読むこと）。その場合、レポートには文書化されたルールではなく、推測した規約に基づく監査であることを明記してください。

影響を受けるテストで Page Object Model が使われているか確認してください。

• POM を使用 — page-objects ディレクトリにページクラスが1つ以上あり、変更された spec が @playwright/test から test を直接インポートするのではなく、カスタムのテストフィクスチャ（一般的には pom）をインポートしている
• POM を不使用 — page フィクスチャのみを使う、標準的な Playwright

これによって適用する監査ルールが決まります。POM を使用していない場合、POM のルールは完全に対象外です。これは想定内の有効な構成です。POM がないことを違反として指摘しないでください。

3. 変更箇所が触れるアプリケーションのソースコードを読む

差分にあるロケーターまたは操作ごとに、その要素をレンダリングするフロントエンドのソースコードを読んでください。プロジェクトでは任意のフレームワーク（React、Vue、Angular、Svelte、プレーンな HTML など）やディレクトリ構成が使われている可能性があります。UI コンポーネントの場所を特定し、テストが操作するルートやコンポーネントをレンダリングするファイルを読んでください。

目的は、実際にレンダリングされる HTML と、プロジェクトのスクリプティングルールで定義されたロケーターの優先順位に基づいて、各ロケーターが正しく、一意で、利用可能な中で最もセマンティックな選択肢かを判断することです。

4. 変更を監査する

変更された行をすべて、以下のチェックリストに照らして確認してください。違反はそれぞれ file:line の形式で指摘してください。**プロジェクトのルールファイルにある具体的なルールを引用してください。**ルールを独自に作り出してはいけません。以下のカテゴリは、Playwright のルールセットで一般的に適用されるフレームワーク非依存のパターンです。プロジェクトの実際のルールファイルにある該当ルールを特定してください。プロジェクトのルールが以下の項目と矛盾する場合は、プロジェクトのルールを優先してください。

ロケーター

• 優先順位は次のとおりです：getByRole > getByLabel > getByText > getByPlaceholder > getByTestId > CSS（安定した構造タグに限り、スタイルクラスは使用しません）
• ロケーターとして CSS クラス名セレクターを使用しません
• data-testid がソースに実際に存在することを確認します。新たに追加する場合は、その値をプロジェクトの命名規則に従わせます（例：プロジェクトで必要とされる場合、要素を表す名詞で終わらせます）
• アクションメソッド（click、fill、check、selectOption）で使用するロケーターが、要素を正確に 1 つだけ特定することをソースを読んで確認します
• 繰り返し表示される UI パターン（カード、行、リスト項目）はコンテナー内にスコープを限定します。誤検出の恐れがある .first() や、スコープを限定しないアクション用ロケーターは使用しません
• ページをまたぐナビゲーションでは、遷移元のページから値（見出しテキストなど）を取得し、遷移先でその値を検証します。遷移先にある任意の要素タイプを検証するだけでは不十分です
• どちらか一方で十分な場合は、.filter() よりもコンストラクターの name / hasText オプションを優先します。.filter() は 2 段階目の絞り込みに限って使用します
• ロケーターのテキストは、テストのビューポートで表示されるレスポンシブ版を含め、ソースコードと完全に一致させます
• セマンティックなスコープ設定：特定のセクションに属する値の検証は、ページ全体ではなく、そのセクションにスコープを限定します

アサーション

• 汎用的な expect(value).toBe(...) パターンよりも、ロケーターの（自動再試行される）アサーションを優先します
• expect.soft(...) は使用しません
• 否定アサーションでは、存在しないことを検証する前に DOM の変更（レスポンス、waitFor({ state: 'hidden' }) など）を待ちます
• 一意なロケーターに対する toHaveText / toContainText を、getByText(...).toBeVisible() より優先します

待機

• page.waitForTimeout(...) は使用しません
• アクションや自動待機するロケーターアサーションの前に、冗長な waitFor() や waitForURL を使用しません
• 明示的な待機は、自動待機しないメソッド（all、count、textContent、inputValue、allTextContents）の前に限って使用します
• 最初のドラフトではカスタムタイムアウトを使用しません。アサーションに { timeout: ... } を指定したり、test.setTimeout(...) を使用したりしません。カスタムタイムアウトは、事前に設定せず、デバッグ時の修正に限って使用できます

テスト構成

• テスト名では実装の詳細ではなく、ユーザーの操作を表します
• テストのエントリーポイントはプロジェクトの規約に従います（例：常にホームページから開始する、または文書化された別のパターンに従う）
• 各テストでは、論理的なユーザーフローを 1 つ検証します
• test.describe の配置と beforeEach の使い方は、ファイル内の既存の規約に従います

コードスタイル

• 1 行に 1 つの文を記述します。ロケーターチェーン、expect(...) の折り返し、テストシグネチャを複数行に縦積みしません
• ロケーター定数は、プロジェクトのルールで必要な場合に限って使用します（通常は 3 回以上繰り返し使う場合、または不透明なロケーターを 2 回以上使う場合）。それ以外はインラインで記述します
• 次の定数を構築するためだけに使う中間定数は作成しません
• 同じロケーターをバリエーション名（*AfterUpdate、*AfterRevert）で再宣言しません。ロケーターは遅延評価され、再解決されます
• allTextContents / textContent の結果を格納する変数名は Values / Texts で終わらせます。Links、Headings などの要素タイプ名は、ロケーターを保持する変数に限って使用します
• 同じ要素を繰り返しクリックする場合、複数行ではなく click({ clickCount: N }) を使用します

POM のルール（POM を使用している場合のみ）

• コンストラクターが受け取るのは Page のみです。ロケータープロパティを追加せず、クラス上でロケーターを先行して構築しないでください
• ロケーターは、使用するメソッド内でインラインに宣言してください
• 1 つの操作だけを行う小さなメソッドを作らないでください。意味のある複数ステップのユーザータスクをメソッドで扱ってください
• 2 つのページにまたがるメソッドを作らないでください。ページ遷移のたびに、別のページオブジェクトのメソッドを呼び出す境界を設けてください
• 操作メソッドでテストの目的に対するアサーションを行わないでください。目的に対するアサーションは、再利用できるようパラメーター化した、expect で始まる専用の検証メソッドに記述してください
• 操作メソッドには、必要に応じて軽量な安定化アサーションを含めてください（自動待機しないコードの前には開始時のガードを置き、ページ遷移の後には expect(page).toHaveURL(...) で完了を確認し、ページ内の変更後には toBeVisible または toHaveText で確認してください）
• メソッド名はキャメルケースで、略語を使わず、動作が明確に伝わる動詞句にしてください。検証メソッドは expect で始めてください
• ハードコードされた値だけが異なる重複メソッドを作らないでください。既存のメソッドをパラメーター化してください
• 新しいページクラスは、プロジェクトの PageManager（または同等の仕組み）に登録し、先行してインスタンス化したうえで、プロパティ名をキャメルケースにしてください
• Spec では @playwright/test から直接ではなく、プロジェクトのカスタムフィクスチャモジュールから test と expect をインポートしてください
• 再利用を優先してください。既存メソッドに近いものがある場合は、複製せずにパラメーター化してください。新しいメソッドを追加する前に、該当するクラスに既存の対応機能がないか確認してください

アーキテクチャ

• Spec ファイルは、プロジェクトの既存のテスト構成に従い、アクター／ロール／シナリオに適したディレクトリに配置してください
• 認証設定ファイルは、変更対象として意図されている場合を除き、変更しないでください
• ステートレスなユーティリティは、ページメソッドや Spec にインラインで記述せず、プロジェクトのヘルパー用ディレクトリに配置してください

5. 監査レポートを作成する

Markdown テーブルを使用して、重大度ごとに 1 つのテーブルを設け、単一の構造化されたレポートをユーザーに直接出力してください。ユーザーが適用する項目を ID で指定できるよう、すべてのテーブルを通して指摘事項に 1、2、3、…と順番に番号を付けてください。

## Audit summary
<one-sentence verdict: passes cleanly / minor issues / multiple violations>

## Findings — Must-fix

| #  | Location              | Issue                                    | Fix                                          |
|----|-----------------------|------------------------------------------|----------------------------------------------|
| 1  | `<file>:<line>`       | <rule violated + one-line evidence>      | <one-line suggested fix>                     |

## Findings — Should-fix

| #  | Location              | Issue                                    | Fix                                          |
|----|-----------------------|------------------------------------------|----------------------------------------------|
| 2  | `<file>:<line>`       | <rule violated + one-line evidence>      | <one-line suggested fix>                     |

## Suggestions

| #  | Location              | Improvement                              | Suggested change                             |
|----|-----------------------|------------------------------------------|----------------------------------------------|
| 3  | `<file>:<line>`       | <stylistic / readability nudge>          | <one-line suggested change>                  |

## What looks good
- <brief callouts of well-applied conventions so positive choices are reinforced>

書式ルール：

• 項目がないセクションは省略してください。
• 各セルの内容は 1 行に収めてください。ルールの引用と根拠の両方が欠かせない場合は、2 行に分けず、Issue 列に <ルール>: <根拠> の形式でまとめてください。
• セル内のコード識別子、ファイルパス、セレクターはバッククォートで囲んでください（例：`.ion-trash-a`、`getByTestId`、`article-page.ts:14`）。
• テーブルを見やすくするため、Location 列ではディレクトリのプレフィックスを省略し、ファイル名と行番号のみを示してください（例：article-page.ts:14。完全なパスは記載しないでください）。読者は文脈から特定できます。完全なパスは、必要に応じて前後の文章にのみ記載してください。
• Issue 列には、プロジェクトのルールファイルから具体的なルールを引用してください。
• 「良い点」セクションは、対応を求める項目ではなく称賛であるため、箇条書きのままにしてください。

重大度の目安：

• 要修正 — 文書化されたルールへの直接的な違反
• 修正推奨 — ルールで推奨されているものの、現状のコードも動作するパターン
• 提案 — ルールとして明文化されていない、スタイルや読みやすさの改善案

6. 次のステップを提示する

AskUserQuestion を使用します。

• Question: "監査が完了しました。次に何をしますか？"
• Header: "次のステップ"
• Option 1: label "必須修正を適用", description "必須修正の指摘のみを解決するようテストを編集します"
• Option 2: label "すべて適用", description "必須修正と推奨修正の指摘を解決するようテストを編集します"
• Option 3: label "相談する", description "変更する前に、個別の指摘について話し合います"

ユーザーは「その他」を選んで、番号を指定して対象を絞ることもできます（例：「1、3、5を適用」）。表ではすべての指摘に一意の ID が割り当てられているため、指定を正確に尊重してください。

ユーザーが必須修正を適用またはすべて適用を選んだ場合（または特定の指摘番号を指定した場合）、選択された指摘を解決するように spec（POM を使用している場合はページオブジェクトも）を編集し、影響を受けるテストのみを再実行します。

npx playwright test -g "<exact test title>" --retries 0

修正後にテストが失敗した場合は、トレースを基にした反復サイクルでデバッグします（npx playwright trace open でトレースを開き、アクションとスナップショットを調べて、修正を適用し、再実行する）。テストが成功するまで繰り返してください。

ユーザーが相談するを選んだ場合は、質問に回答し、明示的に依頼された場合にのみコードを編集してください。

運用原則

• 新鮮な視点を保つ — このコードを書いたエージェントではありません。アプリケーションのソースからすべてのロケーターを改めて導き出してください。あらゆる選択を問い直します。以前のエージェントの意図は関係ありません。判断基準はルールとソースコードのみです。
• 最近の未コミット変更のみを対象にする — 未コミット差分が監査対象のすべてです。過去のコミットに遡らず、変更されていないファイルをレビューせず、差分の範囲外にあるテストの書き換えを提案しないでください。
• 意見ではなくルールを根拠にする — 必須修正の指摘はすべて、プロジェクトの文書化されたルールファイル内のルールに対応付けてください。意見にすぎないフィードバックは「提案」に記載してください。
• ソースと照合してロケーターを検証する — ロケーターが誤っていると指摘する前に、そのロケーターを描画するコンポーネントを必ず読んでください。弱そうに見えるロケーターでも、その DOM で信頼できる唯一の選択肢である場合があります。
• テストの意図を推測しない — 指摘の判断がテストの目的に左右される場合は、推測せずに確認してください。
• POM の使用有無に応じてレビューする — POM が使用されていない場合は、POM のセクション全体を省略してください。Playwright の spec のみで構成されたプロジェクトも有効な構成であり、違反ではありません。
• フレームワークに依存しない — プロジェクトでは任意のフロントエンドフレームワークやディレクトリ構成が使用されている可能性があります。特定のスタックを前提にせず、ファイルからプロジェクトの規約を確認してください。