bagisto-change-verification

変更の検証

Bagisto の完了ゲートです。変更は、その差分が到達するすべてのゲートに合格し、その結果が報告されるまで完了ではありません。この4つのゲートは、.github/workflows/ にある5つのテストワークフローです。E2E は Admin と Shop の2つに分かれて実行されます。つまり、ローカルでこれらのゲートを通過した変更は、パイプラインも通過します。

4つのゲート

#	ゲート	コマンド	適用条件
1	スタイル	vendor/bin/pint --test	.php ファイルを変更した場合
2	テスト	vendor/bin/pest	.php ファイルを変更した場合
3	E2E	パッケージディレクトリで npm run test:e2e	ビュー、JS、CSS、ルートのいずれかを変更した場合
4	翻訳	php artisan bagisto:translations:check	Resources/lang/** を変更した場合
5	命名	naming.md に記載された grep	ルート名、翻訳キー、ストレージパスのいずれかを追加した場合

この順番で実行してください。スタイルチェックは数秒、E2E は数分かかります。Pint で失敗した場合、残りを実行する意味はありません。

1. スタイル

vendor/bin/pint          # fix
vendor/bin/pint --test   # then confirm: CI runs this form

Pint は .blade.php をフォーマットしません。Blade のスタイルは手動で適用します。bagisto-coding-standards スキルを参照してください。

2. テスト

vendor/bin/pest                                        # everything
vendor/bin/pest packages/Webkul/Admin/tests/Feature    # one directory
vendor/bin/pest --testsuite="Admin Feature Test"       # one suite

テストスイートは phpunit.xml に定義されており、テストがあるパッケージごとに1つあります。tests/ ディレクトリがないパッケージにはテストスイートはありません。存在しないパスに対して <testsuite> を追加すると、PHPUnit がエラーになります。

3. エンドツーエンド

Admin、Shop、Installer は、それぞれ独立した Playwright プロジェクトです。Node の依存関係はパッケージごとにインストールされ、ルートに node_modules はありません。そのため、以下のコマンドはパッケージディレクトリからのみ実行できます。

cd packages/Webkul/Admin   # or Shop, or Installer

npm run typecheck                          # tsc over the suite — seconds
npm run test:e2e -- tests/<area>/<file>.spec.ts

CI では、インストーラージョブをゲートとして、Admin と Shop をそれぞれ 10 シャードに分け、MySQL、MariaDB、PostgreSQL に対して実行します。ローカルでは、スイート全体ではなく、変更箇所に該当する spec ファイルを実行し、どのファイルを実行したか報告してください。

作成またはデバッグを始める前に、bagisto-playwright-testing を読み込んでください。失敗の分類もこのスキルが担います。1つのシャードまたは1つのデータベースドライバーで失敗しても、不安定さの証拠とはみなさないというルールも含まれます。

4. 翻訳

php artisan bagisto:translations:check

キーは Resources/lang/ 配下の23言語すべてに存在している必要があります。1つでも言語が欠けていると、ワークフローは失敗します。

このチェッカーがスキャンするのは packages/Webkul のみです。 たとえばシンボリックリンクされた拡張機能のクローンなど、ほかの場所からインストールされたパッケージの場合、その lang ファイルを1つも読み取らずに成功を報告します。こうしたパッケージを検証する方法や、文言を創作せずに参照元から取得する方法については、translations.md を参照してください。

5. 命名

ルート名は snake_case、翻訳キーは kebab-case、ストレージディレクトリ名は複数形の kebab-case にします。naming.md に、それぞれを検出する grep が記載されています。どの grep を実行しても、何も出力されない状態にしてください。

セキュリティチェックポイント

これはゲートではありません。「安全」と返すコマンドはありません。作業完了とする前に、差分に答えが必要な問いです。

この変更は、認可、レンダリングされた出力、ユーザー入力、アップロード、raw SQL、シークレット、または決済に触れますか？

該当する場合は、bagisto-coding-standards を読み込み、差分が実際に触れる箇所についてチェックリストに沿って作業してください。該当しない場合も、その旨を伝えてください。Playwright の実行をスキップした場合にその事実を明記するのと同様に、「認可、出力、入力に関わる箇所には触れていません」と明記し、黙ったままにしないでください。

上記のゲートでは、この問いには答えられません。Pint はスコープ指定のないクエリについて何も指摘せず、テストスイートは IDOR があっても問題なく通過します。

変更を原因と決めつける前にベースラインを確立する

Bagisto のテストスイートは、どのチェックアウトでも必ず成功するわけではありません。一部のテストでは絶対数（meta.total）を検証しますが、シード済みのインストール環境ではその条件を満たしません。また、スイートはロールバックなしで1つのデータベースを共有するため、件数が変動します。

比較せずに、失敗件数を回帰として報告してはいけません。 変更を元に戻し、同じコマンドを再実行して、件数ではなく失敗したテストの名前を差分比較してください。コマンドは baseline.md に記載されています。差分が空であれば、ゲートに合格した証拠になります。

ルール

• 実行していないゲートは失敗したゲートです。 差分が及ばなかったものも含め、すべて明示的に報告してください。「ビューや JS に変更なし — Playwright はスキップ」は結果です。何も報告しないのは結果ではありません。
• チェックではなく原因を修正してください。 テストを削除またはスキップしたり、アサーションを緩めたり、Pint の除外を追加して成功させたりしないでください。
• 自分が原因ではない既存の失敗も、その変更より前から存在していたことを示す証拠とともに報告してください。
• 修正を証明するには、わざと壊してください。 バグを修正したら、その修正を元に戻して新しいテストが失敗することを確認してください。どちらの状態でも成功するテストは何も検証していません。これは回帰テストが最初から機能していない、最もよくある原因です。
• フロントエンドに変更を加えたら、必ずアセットを再ビルドしてから E2E ゲートを再実行してください。 cd packages/Webkul/<Admin|Shop> && npm run build
• 検証の一環としてコミットやステージングをしないでください。依頼された場合を除きます。

よくある間違い

• 名前ではなく件数を報告する。 コードを変更していなくても、同じスイートの実行結果は異なることがあります。意味があるのは名前の差分だけです。
• Pint をリポジトリ全体に実行して、他人の負債まで報告する。 対象を絞ってください：vendor/bin/pint --test <changed paths>
• en だけ編集して翻訳ゲートに合格したと主張する。 チェッカーは 23 のロケールすべてを比較します。1 つだけ編集して何も実行しないのは、パイプラインが失敗するよくある原因です。
• 翻訳ゲートが成功したので、拡張機能も確認済みだと考える。 スキャン対象は packages/Webkul のみです。シンボリックリンクされた拡張機能の場合、lang ファイルを 1 つも読み込まずに成功と報告されます。ゲート 4 を参照してください。
• 「Blade の変更だけだから」と E2E をスキップする。 ビューこそ E2E ゲートの対象です。