automate-manual-test-cases

手動テストケースを自動化する

プロジェクト既存のフレームワーク、パターン、コンポーネントを再利用して、手動テストケースから本番環境で使える自動テストスクリプトを生成します。

チェックリスト

以下の手順を順番に完了してください。

1. プロジェクトのアーキテクチャを分析する => フレームワークを検出する（1.1）、規約を分析する（1.2）、再利用可能なコンポーネントを見つける（1.3）。
2. 手動テストを理解する => 入力を正規化する（2.1）、曖昧なステップに対処する（2.2）、矛盾を検出する（2.3）。
3. テストコードを記述する => 既存の POM／パターンを使用して実装する（3.1-3.2）、アサーションを追加する（3.3）、コードを出力する（3.4）。
4. 検証して修正する => テストを実行する（4.1）、失敗した場合は修正する：ロケーター → タイミング → アサーション → フロー（4.2）。試行は最大 3 回です。
5. 最終処理を行う => テストを保存する（5.1）、テストデータとフィクスチャを管理する（5.2）、関連テストを実行して概要を出力する（5.3）。

進捗状況

• STEP: 1/5（プロジェクトのアーキテクチャを分析）
• 前のステップ: （なし）
• 次のステップ ➡️ ステップ 2：手動テストを理解する

各ステップの完了後、このブロックを更新してください（CLAUDE.md を参照）。

ステップ 1：プロジェクトのアーキテクチャを分析する

1.1 自動化フレームワークを検出する

• ユーザーがフレームワーク（例：「CodeceptJS を使用」）を指定した場合は、それに従います。

• それ以外の場合は、プロジェクトを調査します。

  • package.json の依存関係とスクリプト。
  • 設定ファイル（playwright.config.js、codecept.conf.js、cypress.json など）。

• 検出に失敗した場合は、番号付きの選択肢を提示して質問します。

  ❓ Which framework should I use?
  1. Playwright
  2. CodeceptJS
  3. Cypress
  4. Other (specify)
  

検出後、該当するリファレンスを参照してください。

• CodeceptJS のベストプラクティス
• Playwright のベストプラクティス

1.2 プロジェクトの規約を分析する

• テストの構成と命名：フォルダー（tests/、e2e/）とファイルのパターン（*.spec.js など）。
• 実行方法：package.json のスクリプトとテストコマンド。
• 設定：ベース URL、環境変数、グローバルセットアップ。
• アサーションのスタイル：既存テストで使用されているライブラリとパターン。

1.3 再利用可能なコンポーネントを特定する

以下を検索します。

• ページオブジェクト：既存のロケーターとメソッド（src/pages、pages/、page-objects/ など）。
• フィクスチャ／フック：セットアップとティアダウンのパターン。
• テストデータ：定数、CSV、JSON（test-data、src/testData など）。
• ユーティリティ／ヘルパー（utils/、helpers/ など）。

分析から除外するもの：

• 依存関係のフォルダー（node_modules/）。
• ビルド生成物（dist/、build/、out/）。
• 隠しフォルダー／システムフォルダー（.git/、.cache/）。
• 非推奨のコード：deprecated/、legacy/、old/、backup/、__backup__/、archive/、temp/、outdated と記されたファイル、新しいバージョンが存在する古いバージョンのフォルダー（v1/、v2/）。
• 用途が不明確なフォルダーは自動的に除外しないでください。
• ユーザーが指定した除外対象は、常に自動検出された除外対象より優先されます。

ステップ 2：手動テストを理解する

入力は、プレーンテキスト、Markdown のステップ、またはソースファイル内のコメントブロック（//、/* */）の場合があります。

2.1 入力構造を正規化する

入力を以下に変換します。

• summary（またはシナリオのタイトル）。
• preconditions（任意）。
• steps（必須）— 期待結果を伴う順序付きの操作。

コメントベースの入力の場合：

• コメントマーカー（//、*、-）を構造上のヒントとして扱います。
• 箇条書きを順序付きのステップに変換します。
• _Expected:_ または Expected Results のブロックを、直前のステップに結び付けます。
• 複数行の期待結果を、単一の論理的な期待結果にまとめます。

例：

* Navigate to page  
  _Expected:_ Page opens
* Click once on the ${Custom statuses} block
  _Expected_: List includes "manual" option.

元の手動テストのコメントを削除したり書き換えたりしないでください。

• ファイル内にそのまま残してください。
• その下、または横に自動化コードを生成してください。
• // === AUTO-GENERATED TEST (based on steps above) === というマーカーで区切ってください。

2.2 曖昧なステップに対処する

各ステップを分類します。

• 明確 => 続行します。

• 一部明確 => 妥当な仮定を置き、出力内で ⚠️ を付けて示し（例：「⚠️ 『Submit』ボタンはフォームを送信すると仮定します」）、続行します。

• 不明確で作業を妨げる => ユーザーに質問します。選択肢がある場合は、番号付きで提示します。

  ❓ Do you want to:
  1. Use existing LoginPage
  2. Create new LoginPage
  3. Skip login step
  

前のステップの文脈や一般的な UI パターン（クリック、入力、画面遷移）を活用してください。 不明確なステップが 1 つあるだけでフロー全体を止めず、残りのステップを続行してください。

2.3 不整合の検出

ステップのアクション、期待される結果、既知の UI パターンが一致しない場合：

• 最善の解釈に基づいて進めます。
• 出力で ⚠️ を付けて示します。

ステップ 3：テストコードの作成

3.1 実装方針の選択

• 再利用可能なコンポーネント（Page Objects、ヘルパー、フィクスチャ）がある場合 => 再利用し、プロジェクトのパターンと命名規則に従います。
• 部分的な構造がある場合 => 既存のコンポーネントを拡張し、現在の設計との一貫性を保ちます。
• 構造がない場合 => シンプルで読みやすいロケーターを使い、最小限の実装にとどめ、不要な抽象化は行いません。

優先順位は、プロジェクトとの一貫性、読みやすさ、保守性の順です。

既存の Page Objects を無視したり、セレクターやロジックを重複させたりしないでください。

3.2 フレームワークのパターンに従う

• 1 つのテストにつき 1 つのフローとし、各テストで単一のシナリオを検証します。
• 関心事を分離します。テスト => アサーションとフロー制御、Page Objects => UI 操作、utils => 再利用可能なロジック。
• 変更ではなく拡張を行い、既存のコンポーネントに追加して、安定したコードは変更しません。
• セットアップ、認証、共有状態にはフィクスチャを使用します。

Page Object Model のベストプラクティスを参照してください。

3.3 アサーションの生成

• 手動ステップの期待される結果に基づいてアサーションを作成します。
• UI の状態（表示、テキスト、属性）、データの正確性、ナビゲーションの結果を検証します。
• ページの読み込みだけを確認するような弱いアサーションや、無関係な詳細を過剰に検証することは避けます。

3.4 テストコードの出力

• 既存のフレームワークと統合できる、完全で実行可能なコードを生成します。
• プロジェクトのフォーマットとスタイルの規約に従います。
• 適切なテストファイルにコードを配置するか、配置先を提案します。

ステップ 4：検証と修正

4.1 テストの実行

生成したテストのみを実行し、テストスイート全体は実行しないでください。

• Playwright：npx playwright test path/to/spec.ts
• CodeceptJS：npx codeceptjs run path/to/test.js

成功した場合はステップ 5 に進みます。失敗した場合は修正します（4.2）。

4.2 失敗したテストの修正

次の優先順位で、一度に 1 つの問題を修正します。

1. ロケーター — 安定したセレクター（data-testid、aria-label）を優先し、深くネストした XPath は避けます。
2. タイミング — フレームワーク標準の待機処理を使用し、固定時間の待機は避けます。
3. アサーション — 想定ではなく、実際のアプリの動作に合わせます。
4. フロー — ナビゲーション、前提条件、ステップの不足を確認します。

手順：失敗を 1 つ特定 => 修正を 1 つ適用 => 再実行 => 繰り返します。 行き詰まった場合に戻せるよう、最後に動作したバージョンを保持してください。

修正の試行は最大 3 回です。それでも失敗する場合は停止し、問題を報告してください。

根本原因が不明な場合は、debug-fix-failed-flaky-autotests スキルを使用して、手順に沿って診断します。

MCP／デバッグツールが利用できる場合：

• DOM を確認します（document.querySelector(...).outerHTML）。
• ステップごとに実行します。
• ログ、スクリーンショット、またはトレースを取得します。

4.3 安定性の基準

以下を満たす場合、テストは安定していると判断します。

• 1～2 回連続で成功する。
• 固定時間の待機がない。
• 堅牢なロケーターを使用している。

ステップ 5：最終化

5.1 最終テストコードの保存

• 動作するテストを、プロジェクト内の適切な場所に保存します。
• 命名規則に従い、既存のテストとの一貫性を保ちます。

5.2 テストデータとフィクスチャ

• プロジェクトに中央管理されたテストデータ（JSON／CSV／定数）がある場合は、それを使用します。
• 認証／セットアップ用のフィクスチャを再利用し、テスト内でセットアップを重複させないでください。

テストデータ管理を参照してください。

5.3 最終実行と概要

• 統合を確認するため、関連するテストを 1～2 件実行します（関連テストのみとし、テストスイート全体は実行しません）。

• 終了条件：テストが 2 回連続で成功すること。

• 仕様とコードの対応を示します。

  手動ステップ	自動化アクション
  Settings に移動	basePage.clickOnNavigationMenuButton("Settings")

• 最終サマリーテンプレートを使用して、最終概要を出力します。

例：コメントによるリクエスト

Use automate-manual-test-cases skill for CodeceptJS framework to write automation
script "tests/plan-for-guest.test.ts" based on manual steps below in this file as
comments (leaving comments in the file for further analysis). Set a specific "smoke"
tag for this test.
Use as reference for extra proper examples:
* `tests/payment-methods.test.ts` - Canonical test file with team approved format.
* `src/pages/paymentMethods.page.ts` - Good described payment page object.
Avoid mistakes from legacy code examples:
* `src/pages/paymentOutdated.page.ts` - Outdated example with old patterns.

Finally, verify that the generated test is passed on - `BASE_URL = 'https://test.com/'`
and provide final review for user.