Mcube333/playwright-java-test-writer

Playwright Java Test Writer

手動テストケースを、フレームワークを熟知した開発者が書いたかのような保守性の高いPlaywright Javaテストに変換します。並列実行安全、フレーキーなスリープなし、ロケーターを隠蔽するページオブジェクト、元のテストケースIDにトレースバックするAllureレポートを備えています。

ワークフロー

1. 手動テストケースの解析

各ケースから以下を抽出します: ID、タイトル、優先度/重大度、前提条件、テストデータ、ステップ、ステップごとの期待結果。入力形式は様々です（Excel行、Jiraエクスポート、Gherkin、自由テキスト）。コードを書く前に、これらをこの構造に正規化します。

ケースが記述されたまま自動化できない場合（実際の電話からのOTPが必要、"見た目が正しい"のような視覚的判断、実費によるサードパーティ決済など）、偽装しないでください。出力の自動化されなかったケースセクションに理由と提案（APIのモック、テスト用OTPの使用、ビジュアルスナップショット比較）をリストアップします。

2. 既存フレームワークの規約を先に検出

ユーザーがリポジトリのファイル（BaseTest、ページクラス、testng.xml、pom.xml）を共有した場合、それらを正確にミラーリングします: パッケージ名、基底クラス名、命名スタイル、アサーションスタイル、設定の読み取り方法。コードベースとの一貫性が、以下のリファレンススタイルよりも優先されます。

何も共有されていない場合は、references/framework-scaffold.md のスキャフォールドを使用します。スキャフォールドファイル（BaseTest、PlaywrightFactory、BasePage、config）は、ユーザーがフレームワークを要求した場合、または明らかにフレームワークを持っていない場合にのみ生成します。それ以外の場合は、それらが存在すると仮定し、ページオブジェクトとテストのみを生成します。

3. ページオブジェクトの設計

• ページまたは再利用可能なコンポーネント（ヘッダー、カートドロワー、フィルターパネル）ごとに1つのクラス。コンポーネントは独自のクラスを持ち、ページに合成されます。
• ロケーターは private final Locator フィールドで、コンストラクタで初期化します。テストは page.locator(...) を直接呼び出してはいけません。
• ページメソッドはユーザーの意図（login(user, pass)、addToCart(productName)）を記述し、操作（clickButton2）を記述しません。Allure @Step("...") でパラメータプレースホルダーを使用してアノテーションし、レポートが手動ケースのように読めるようにします。
• ナビゲートするアクションは次のページオブジェクトを返します（流暢なフロー）。ページに留まるメソッドは this または void を返します。
• 新しいメソッドを追加する前に、既存のページメソッドを再利用します。2つのステップが同じ意図にマッピングされる場合は、1つのメソッドを使用します。
• アサーション用の状態は、意図名のゲッターで Locator を返すように公開します（例: errorMessage()）。これにより、テストはWebファーストアサーションを使用できます。

ロケーターの優先順位（安定性が高い順）:

1. getByTestId（アプリが data-test、data-qa などを使用する場合、属性名を一度設定します）
2. アクセス可能な名前を持つ getByRole
3. ユーザーに見えるテキストの getByLabel / getByPlaceholder / getByText
4. 安定した属性のCSS
5. XPath、最後の手段としてのみ使用し、理由をコメントに記述します

ユーザーがDOM、HTML、スクリーンショットを提供しなかった場合、ロケーターは推測になります。最善の推測を書き、// TODO-VERIFY locator とマークして、発明されたセレクターがそのまま本番に出荷されないようにします。サマリーに未検証のロケーターの数を記載します。

4. テストの記述

• 手動ケースごとに1つの @Test メソッド。メソッド名 = 振る舞い（shouldShowErrorForLockedUser）、IDではありません。
• トレーサビリティ: ケースIDを @TmsLink("TC-012") と description に記載します。ケースの優先度からマッピングした @Epic、@Feature、@Story、@Severity を追加します（P0/クリティカル → BLOCKER/CRITICAL、P1 → NORMAL、P2+ → MINOR）。
• すべての期待結果はアサーションになります。アサーションのないステップは、手動チェックが削除されたことを意味するため、終了前にクロスチェックします。
• 前提条件は、APIまたはディープリンクが存在する場合、長いUIクリックチェーンではなく、セットアップヘルパーまたはAPI呼び出しに配置します。ログイン前提条件（特にOTP/SSO）の場合は、APIログインを1回実行し、context.storageState() / Browser.NewContextOptions().setStorageStatePath(...) で再利用することを推奨します。
• 異なるデータを持つ繰り返しケース → TestNG @DataProvider を使用した1つのテスト。@TmsLink は静的なため、ケースIDを最初のデータ列として渡し、テスト内で Allure.link(caseId, "tms", caseId) を呼び出して、行ごとのトレーサビリティを維持します。テストデータはテスト本体の外（データプロバイダー、JSON、または定数クラス）に保持します。実際の顧客データは絶対に使用しないでください。
• テストは独立している必要があります: 実行順序に依存しない、テストごとに新しいコンテキスト、作成したものはクリーンアップします。

5. 待機: 条件ベースのみ

これはフレーキーさの主な原因であるため、厳格なルールとして扱います:

• Thread.sleep や page.waitForTimeout は絶対に使用しないでください。
• Webファーストアサーションを推奨: assertThat(locator).isVisible()、hasText、hasCount、assertThat(page).hasURL(...)。これらは自動リトライします。
• アクションは既にアクション可能性を自動待機します。click()/fill() の前に冗長な待機を追加しないでください。
• アクションが結果に関係するネットワーク呼び出しをトリガーする場合、ラップします: page.waitForResponse(r -> r.url().contains("/cart") && r.ok(), () -> addButton.click())。
• スピナー/ローダーの場合: assertThat(loader).isHidden()。
• ナビゲーションの場合: page.waitForURL("**/checkout**")。
• カスタムタイムアウトは設定から取得し、マジックナンバーをインラインで使用しないでください。

references/framework-scaffold.md → 「待機パターン」を参照してください。

6. 並列安全性

すべてのPlaywrightオブジェクト（Playwright、Browser、BrowserContext、Page）は、基底クラス/ファクトリによって管理される ThreadLocal に存在し、テストメソッドごとに作成およびクローズされます。これらをstaticフィールドに保存したり、テスト間で Page を共有したりしないでください。ページオブジェクトはコンストラクタを介して Page を受け取ります。ページオブジェクト内のstatic状態は許可されません。

出力形式

以下の順序で応答します:

1. ファイル: 各ファイルを独自のコードブロックに、完全なパスをヘッダーとして記述します（例: src/test/java/com/example/pages/LoginPage.java）。インポートを含む完全でコンパイル可能なファイル。ユーザーがスニペットを要求した場合を除き、断片ではありません。約3ファイルを超える場合、またはユーザーがダウンロードを希望する場合は、プロジェクトフォルダーとしてディスクに書き込みます。
2. トレーサビリティテーブル: ケースID | テストメソッド | 自動化されたステップ | メモ。
3. 自動化されなかったケース / ギャップ: スキップされたケースまたはステップとその理由。
4. 検証が必要: TODO-VERIFY ロケーターの数とリスト、テストデータまたは環境に関する仮定。

散文は簡潔に保ちます。コードが成果物です。

機密性

ユーザーが公開ポートフォリオを構築している場合、またはリクエストが公開デモアプリに言及している場合、すべてを汎用的に保ちます: パッケージ com.example（またはユーザーが指定したもの）、会社名、内部URL、内部エンドポイント、実際のユーザーデータ、独自のイベント名は使用しません。貼り付けられた手動ケースにこれらが含まれている場合は、中立の相当物に置き換え、その旨を1行で述べます。

リファレンスファイル

• references/framework-scaffold.md: pom.xmlの依存関係、ThreadLocalsを使用したPlaywrightFactory、トレーシングと失敗時のAllure添付ファイルを持つBaseTest、BasePage、ConfigReader、並列実行用のtestng.xml、待機パターンスニペット。スキャフォールディング時または正確なAPI形状が必要なときに読み取ります。
• references/example-saucedemo.md: 公開アプリsaucedemo.comにおける完全な実例（手動ケース → ページオブジェクト → テスト → トレーサビリティテーブル）。出力スタイルを調整するために読み取ります。