bagisto-playwright-testing

Playwright Testing

先に仕様を書かない

「X の Playwright テストを追加する」は、仕様を書き始める指示ではありません。X が実際に何をするのか、すでに何でカバーされているのか、そして Pest テストでは証明できず、ブラウザーで証明できる動作はどれなのかを調べる指示です。

調査の前に書いたテストは、たいてい重複したテストか、誤ったレイヤーをテストするもの、あるいは機能が動いても動かなくても通るものです。どれも得られるものよりコストのほうが大きく、誰かが保守し続ける一方で、誰も信頼できません。

パイプラインの順に進めます。機能とそのルールを理解し、すでにカバーされている内容を整理し、シナリオと Pest に含めるものを決め、データとロケーターを設計してから実装し、何かを変更する前にすべての失敗を分類します。

フェーズ	読むもの	作成するもの
調査	investigation.md	機能、そのルール、影響範囲、すでにカバーされている内容
構成	architecture.md	ヘルパー、ページオブジェクト、共有ユーティリティの配置場所
設計	test-design.md、admin-and-shop.md	状態遷移、カバレッジマトリクス、シナリオごとの E2E と Pest の判断
実装	authoring.md、test-data.md、locators.md、assertions.md	仕様とそのページオブジェクト
時間に依存する作業	time-and-timezone.md	CI で安定して動作する予約、レンタル、時間枠、空き状況、「今日」のカバレッジ
検証	troubleshooting.md	正しい理由で 2 回通る実行
ゲート	quality-gate.md	完了したチェックリスト

変更の規模に合わせてプロセスを調整します。 1 行のロケーター修正に必要なのは、調査のステップ（ロケーターが壊れた理由は何か）と検証のステップ（機能が壊れた場合も失敗するか）であり、カバレッジマトリクスではありません。新しい機能領域ならすべてが必要です。決して省略してはならないのは、アプリケーションコードを読むことと、テストが失敗し得ることを証明することです。

この作業で意識すること

• テスト数ではなく、意味のある動作のカバレッジを最大化します。 入力値だけが異なる 10 件のテストは、データテーブルを使った 1 件のテストです。
• テストが通ったからといって、よいテストの証拠にはなりません。 それとは別に、「失敗し得たか」を確認します。機能を削除した場合、このテストは失敗するでしょうか。
• 何を証明するかを決めずに、既存のテストをコピーしないでください。 これらのテストスイートには、トーストが表示されたことしか検証しないテストがあります。
• ビジネス上の前提条件は、実行上の依存関係ではありません。 必要な状態を自分で設定し、別の仕様が先に実行されることを前提にしてはいけません。
• 何を待つのかを明示せずに、待機を追加しないでください。
• 何かを変更する前に、失敗を分類します。 アプリケーションに問題があるなら、テストが失敗するのは正しい動作です。テストを通すためにアサーションを編集してはいけません。
• ロケーターは、安定していて、意図した要素を一意に識別できることを理由に選びます。 短いから、または strict mode のエラーが出なくなるからという理由で選んではいけません。
• 作る前に検索します。 新しいフィクスチャ、ヘルパー、ページオブジェクトの追加は、再利用、拡張、リファクタリングを検討した後の最終手段です。
• 回帰テストは、バグがある状態で失敗するまで完成ではありません。
• 最小限の仕組みで、最も強力な動作検証を行い、リスクをカバーしたらそこで止めます。 その判断基準については test-design.md を参照してください。

アーキテクチャ

独立した Playwright プロジェクトが 3 つあります。packages/Webkul/{Admin,Shop,Installer}/tests/e2e-pw/ にそれぞれ配置され、各プロジェクトに独自の playwright.config.ts、setup.ts、pages/、tests/、utils/、data/ があります。さらに、ルート直下の tests/e2e-pw/helpers/ 層にある依存関係のないヘルパーを、3 つのプロジェクトすべてが @shared/* 経由でインポートします。

以下の 2 つのルールは、どちらも不可欠です。

• 共有レイヤーに依存関係を持たせません。 CI ではパッケージごとに node_modules をインストールするため、helpers/ 内のコードから @playwright/test、dotenv、その他のサードパーティパッケージをインポートしてはいけません。それらが必要なヘルパーは、そのパッケージの utils/ に配置してください。
• 各テストスイートでページオブジェクト、フィクスチャ、スペックを共有しません。 それぞれのスイートは、操作対象となる画面のページオブジェクトを、相手側のものも含めて個別に用意します。パッケージの境界を越えてインポートしてはいけません。

タイムアウトはテストスイートごと、リリースラインごとに異なるため、チェックアウトしたコードの playwright.config.ts を確認してください。1 つのフローのタイムアウトを延長するには test.setTimeout(...) を使い、設定ファイルは変更しないでください。

全体の構成、コードの配置先を示す表、ラッパーパターン、タイムアウト値については、architecture.md を参照してください。

実行方法

必ずパッケージのディレクトリから実行してください。リポジトリのルートではなく、そこに node_modules が存在します。3 つのパッケージすべてで同じスクリプトを利用できます。

cd packages/Webkul/Admin          # or Shop, or Installer
npm install && npm run install:browsers
npm run test:e2e
npm run test:e2e -- tests/catalog/categories.spec.ts -g "create a category"
npm run typecheck                 # tsc --noEmit over the suite

test:e2e:headed、:ui、:debug、:report は、それぞれ Playwright のフラグに対応しています。Admin と Shop では、アプリが起動済みで、インストールおよびシード済みである必要があります。Installer では、アプリが未インストールである必要があります。環境要件については、troubleshooting.md を参照してください。

絶対に守ること

• スイート全体でデータベースを共有し、ロールバックは行いません。 E2E の実行では、作成したすべてのレコードが残ります。そのため、アサーションでは作成した行に対象を絞り、全体の件数やリスト内の位置を使わないでください。
• テストは自身の状態を管理します。 必要なものを作成し、変更したグローバル設定を元に戻し、自分で作成したものだけを削除します。都合がよいからといって「最初の行」や既存の任意のレコードを操作しないでください — test-data.md。
• テストはスイートをまたいでも、個別に実行できる必要があります。 workers: 1 やファイルの実行順は、別のテストが先に実行されていることを前提にする許可にはなりません。また、Shop の spec は Admin の spec が何かを設定したことを前提にしてはいけません — admin-and-shop.md。
• Admin 認証は adminPage フィクスチャによって .state/admin-auth.json にキャッシュされます。 spec 内で手動ログインしないでください。loginAsAdmin(page) を呼び出す Shop のプロモーション spec はレガシーです — authoring.mdを参照してください。
• フロントエンドを変更した後は、実行前に必ずアセットを再ビルドしてください。 そうしないとブラウザーが以前のバンドルを読み込み、失敗がテストの不具合に見えてしまいます。
• Pest と Playwright を同じデータベースに対して同時に実行しないでください。 E2E の実行中は商品の価格が再設定され、設定も変更される一方、feature スイートはそれらを読み取ります。その結果発生する Pest の失敗は、コードの不具合に見えてしまいます — troubleshooting.md。
• tests/e2e-pw/ 以下にはコメントを一切書かないでください — //、/* */、docblock は禁止です。これは Bagisto の規約であり、現在の 3 つすべてのスイートで例外なく守られています。一般的な Playwright の推奨事項とは意図的に異なります。理由は代わりにメソッド名に含めてください。その方法は authoring.mdに記載されています。
• テストデータはモジュールスコープではなく、必ず beforeEach 内で生成してください。 モジュールスコープで uniqueStamp() を 1 回呼び出すと、ファイル内のすべてのテストで同じ SKU が使われ、クリーンアップが漏れない間だけファイルが成功します。
• 時刻に依存するテストでは、まずタイムゾーンを確認してください。 アプリは APP_TIMEZONE（ここでは Asia/Kolkata）で動作し、設定では Node とブラウザーに同じタイムゾーンを指定しています。今日、明日、スロット、利用可能状況、期限に関わるものは、まず time-and-timezone.md を使って調査してください。
• 「不安定」というのは結論であり、最初に立てる仮説ではありません。 1 つのシャードでの失敗、1 つのデータベースドライバーでの失敗、ローカルでの成功は、いずれも不安定さの証拠にはなりません。まずトレース、タイムスタンプ、サーバーログを確認してください — troubleshooting.md。
• ファイル名は lower-kebab 形式にし、クラスを宣言するファイルの名前は、そのクラス名と完全に一致させてください — catalog.ts ではなく CatalogAclPage.ts とします。describe と test のタイトルは小文字にし、単語間には半角スペースを 1 つだけ使います。番号付きの順序プレフィックスは禁止です。

spec には意図を記述してワークフローを組み立て、page object にはすべてのロケーターを持たせ、名前付きの expect… メソッドを通じてアサーションを行います。CSS セレクターを含む spec は、page object に移してください — authoring.md。

必須サブスキル： 変更を完了したと判断する前に、bagisto-change-verification を使用してください。