playwright-bdd

Playwright BDD

フェーズ 0：BDD の必要性の確認

ユーザーから依頼されたタスクごとに、まず、求められている成果を新規または更新された BDD シナリオで記述する必要があるかどうかを判断します。この判断は、コード変更の規模や関係するファイルの数ではなく、ユーザーから観察可能な製品の動作の変化に基づいて行います。

次の場合は、BDD フィーチャーファイルの変更が必要です。

• BDD シナリオの追加、更新、削除が明示的に依頼されている。
• ユーザーから観察可能な動作や、エンドツーエンドのユーザー体験を追加、削除、変更する。
• ユーザーフロー、受け入れ条件、検証ルール、権限、またはユーザーに表示されるエラーの動作を変更する。
• 既存のシナリオに期待される動作が記載されていない、または不正確に記述されているバグを修正する。

次の場合は、BDD フィーチャーファイルの変更は必要ありません。

• 既存の観察可能な動作を維持したまま、実装をリファクタリングまたは再構成する。
• 製品の動作を変更せずに、ドキュメント、コメント、書式、ツール、またはその他の開発インフラストラクチャを変更する。
• ユーザーの操作や意味を変更しない、表示のみの視覚的または幾何学的な調整を行う。
• 既存のシナリオですでに正確に仕様化されており、文言やカバレッジの変更が不要な動作を実装または修正する。
• 仕様化された製品の動作を変更せずに、ステップ定義またはテストインフラストラクチャのみを変更する。

この評価を行った後は、次のようにします。

• BDD フィーチャーファイルの変更が必要な場合は、確認を求めずにフェーズ 1 に進みます。
• BDD フィーチャーファイルの変更が不要な場合は、.feature ファイルを作成または変更せず、確認のために停止することなく、直ちにユーザーのタスクを続行します。
• 判断が本当に難しい場合は、次の質問のみを尋ねます。「この変更では BDD シナリオの更新が必要ですか？」 その後、ユーザーの回答を待ちます。質問する理由や詳細、根拠、推奨事項は説明しません。
• ユーザーが「はい」と回答した場合は、フェーズ 1 に進みます。「いいえ」と回答した場合は、.feature ファイルを変更せずにユーザーのタスクを続行します。

フェーズ 1：計画

1. プロジェクト設定を確認する — playwright.config.ts（または playwright.config.js）で defineBddConfig(...) の呼び出しを検索します。これにより、機能ディレクトリと、ステップ定義ファイルを指す steps の glob パターンがわかります。
   • defineBddConfig の呼び出しが複数ある場合は、状況に基づいて最も適切なものを選びます（たとえば、ディレクトリ名を説明されている機能領域に合わせます）。本当に判断がつかない場合に限り、ユーザーに確認します。
2. BDD シナリオを作成する — 既存の機能ファイルを確認し、入力に応じて BDD シナリオを作成または更新します。「シナリオ作成ルール」セクションに厳密に従ってください。
3. 機能ファイルの変更内容をユーザーに提示し、question ツールで「提案した機能ファイルの変更を承認しますか？」と質問する — ユーザーが内容を検討できるよう、正確な新規または変更後の Gherkin を提示します。
   • 既存のシナリオへの変更を提示する場合は、追加と削除が明確にわかるよう、統一 diff 形式（```diff）を使用します。シナリオを新規作成する場合は、プレーンな Gherkin 形式で提示します。
   • シナリオを追加または変更する場所が明確になるよう、対象の機能ファイルのパスを必ず示します。
   • question ツールでは、簡潔な承認を求める質問「提案した機能ファイルの変更を承認しますか？」を使い、質問自体に diff 全体を含めないでください。
   • ユーザーから計画を求められた場合は、機能ファイルの変更内容を提示し、明示的な承認を得るまで計画を確定しないでください。
   • 機能ファイルの diff／Gherkin の代わりに、要約、チェックリスト、実装計画を提示しないでください。ユーザーには提案する .feature ファイルの更新内容そのものを確認してもらう必要があります。
   • ユーザーから変更を求められた場合は、提案するシナリオのテキストを修正して、再度提示します。
   • ユーザーがシナリオを明示的に承認するまで、やり取りを続けます。ユーザーがシナリオを正しいと確認するまで、実装計画の作成や実装には進まないでください。
4. シナリオの承認後に限り、実装を計画する — Gherkin が承認されたら、依頼に応じて実装計画を作成または実行します。計画では、承認されたシナリオを唯一の基準とします。

フェーズ 2：実装

1. 機能を実装する — プロジェクトのガイドラインに従って、実際の機能実装コードを記述します。このスキルのガイドラインには従わないでください。
2. ステップ定義を実装する — シナリオで使用されるステップのステップ定義を作成または更新します。既存のステップ作成パターンに従ってください。既存のファイル名から推測し、新しいステップを追加するのに最適なファイルを提案します。

フェーズ 3：検証

npx bddgen && npx playwright test を実行して、機能ファイルからテストファイルを生成し、Playwright で実行します。

Playwright CLI に生成された spec ファイルのパスを渡して、関連するテストのみを実行します。生成先ディレクトリは playwright.config.ts の defineBddConfig()（testDir の値）で定義されています。

例：

npx bddgen && npx playwright test .features-gen/@homepage/homepage.feature.spec.js

シナリオ作成のルール

デフォルトでは、以下のルールを適用してください。ユーザーが異なる表現、構成、または対象範囲を明示的に求めた場合は、該当するシナリオについてその指示に従ってください。

• シナリオでは、意味のある結果につながる、ユーザーの操作を最初から最後まで網羅してください。 シナリオには、中間状態の確認ではなく、ユーザーが実際に目にする動作や結果を記述してください。

• シナリオの数は最小限にしてください。 機能の主なユーザーフローを網羅するために必要な、最少数のシナリオを使用してください。

• シナリオの作成時には既存のステップを再利用してください。 新しい表現を考える前に、再利用できるステップがないか、既存のステップ定義とフィーチャーファイルを確認してください。登録済みのステップ定義をすべて一覧表示するには、npx bddgen export またはファイル検索ツールを使用してください。

• 操作によって要素の利用可能性を示してください。 シナリオで要素をクリック、入力、選択、またはその他の方法で使用する場合、同じ要素が存在するか、表示されているか、有効になっているかを別のステップで確認しないでください。要素の利用可能性自体が意味のある前提条件または結果となる場合に限り、利用可能性を確認するステップを追加してください。

• 技術的でパラメーターの多い名前よりも、業務内容が伝わるステップ名を優先してください。 悪い例：When('I click {string} on {string}', ...) 良い例：When('I click the "Add" button in the product list', ...)\

• 同種の操作が複数ある場合は、ステップを繰り返すのではなく、データテーブルを使った単一のステップを優先してください。 シナリオで同種の値を複数指定する場合（例：フォームへの入力、リスト項目の追加）は、値ごとにステップを繰り返すのではなく、データテーブルを使った1つのステップにまとめてください。 悪い例：

  When I fill "Name" with "Alice"
  And I fill "Email" with "[email protected]"
  And I fill "Role" with "Admin"
  

  良い例：

  When I fill the form with:
    | Name  | Alice             |
    | Email | [email protected] |
    | Role  | Admin             |
  

• すべてのフィーチャーに短い説明を追加してください。 各Feature:行の直後に、フィーチャーの主なユーザー向けの目的を説明する、1～2文の説明をインデントして追加してください。簡潔で具体的な表現を使い、プロジェクトで既に使われているドメイン用語を使用してください。フィーチャー全体を説明し、シナリオ、エッジケース、実装の詳細を列挙しないでください。説明の前後には空行を入れてください。

• 新しいシナリオは末尾に追加してください。 既存のフィーチャーファイルにシナリオを追加する場合は、既存のすべてのシナリオの後に配置してください。ユーザーが特定の位置を明示的に求めた場合を除き、先頭や既存のシナリオの間に挿入しないでください。

スコープ付きステップ定義

ステップ定義を特定のフィーチャードメインにスコープするため、@プレフィックス付きディレクトリを優先してください。これにより、共通のステップ名（例：I should see {string} text）に対して、コンテキストに応じて異なる実装が必要な場合の競合を避けられます。 スコープ付きステップの詳細：https://vitalets.github.io/playwright-bdd/#/writing-steps/scoped?id=tags-from-path

スコープ付きステップを使った構成例

features/
├── fixtures.ts
├── @homepage/
│   ├── homepage.feature
│   └── steps.ts
├── @profile/
│   ├── profile.feature
│   └── steps.ts
└── shared-steps.ts

features/@homepage/steps.ts内で定義されたステップは、同じディレクトリにあるフィーチャーに自動的にスコープされます。{ tags: '@homepage' }を明示的に指定する必要はありません。

フィーチャーファイルの例

Feature: Shopping cart
  Customers can collect products they intend to buy and review the current cart contents.

  Scenario: Add item to cart
    Given I am on a product page
    And the cart is empty
    When I add the product "banana" to the cart
    Then the cart contains "banana"
    And the cart badge shows 1

ステップ定義の例

import { Given, When, Then } from './fixtures';

Given('I am on a product page', async ({ page }) => {
  await page.goto('/product');
});

When('I add the product {string} to the cart', async ({ page }, name: string) => {
  await page.getByRole('button', { name: `Add ${name}` }).click();
});

Then('the cart badge should show {int}', async ({ page }, count: number) => {
  await expect(page.locator('.cart-badge')).toHaveText(String(count));
});