bagisto-change-verification

Change Verification

The completion gate for Bagisto. A change is not done until every gate its diff reaches has passed and been reported. These four gates are the five test workflows in .github/workflows/ — E2E runs as two, Admin and Shop — so a change that clears them locally is a change that clears the pipeline.

The four gates

#	Gate	Command	Applies when
1	Style	vendor/bin/pint --test	any .php changed
2	Tests	vendor/bin/pest	any .php changed
3	E2E	npm run test:e2e from the package directory	any view, JS, CSS or route changed
4	Translations	php artisan bagisto:translations:check	any Resources/lang/** changed
5	Naming	the greps in naming.md	any route name, translation key or storage path added

Run them in that order — style is seconds, E2E is minutes, and a Pint failure makes the rest moot.

1. Style

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

Pint does not format .blade.php. Blade style is applied by hand — see the bagisto-coding-standards skill.

2. Tests

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

Suites live in phpunit.xml, one per package that has tests. A package with no tests/ directory has no suite; adding a <testsuite> for a path that does not exist makes PHPUnit error.

3. End-to-end

Admin, Shop and Installer are separate Playwright projects. Node dependencies are installed per package — there is no root node_modules — so these only work from the package directory:

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 runs Admin and Shop across 10 shards each, against MySQL, MariaDB and PostgreSQL, gated by an installer job. Locally, run the spec files your change touches rather than the whole suite, and report which ones.

Load bagisto-playwright-testing before writing or debugging one. It owns failure classification, including the rule that one shard or one database driver failing is not evidence of flakiness.

4. Translations

php artisan bagisto:translations:check

A key must exist in all 22 locales under Resources/lang/. One missing locale fails the workflow.

This checker only scans packages/Webkul. For a package installed from anywhere else — a symlinked extension clone, for instance — it reports success without reading one of its lang files. See translations.md for how to verify those, and how to source wording rather than invent it.

5. Naming

Route names are snake_case, translation keys are kebab-case, and storage directories are plural and kebab-case. naming.md has the greps that catch each one; every one should print nothing.

The security checkpoint

Not a gate — there is no command that returns "secure". It is a question the diff has to answer before the work is called done:

Does this change touch authorization, rendered output, user input, uploads, raw SQL, secrets or payments?

If yes, load bagisto-coding-standards and work its checklist for the surfaces the diff actually touches. If no, say so — "no authorization, output or input surfaces touched" — the same way a skipped Playwright run is stated rather than left silent.

The gates above cannot answer this. Pint has no opinion on an unscoped query, and a test suite passes just as happily with an IDOR in it.

Establish the baseline before you blame your change

Bagisto's suites do not start green on every checkout. Some tests assert absolute counts (meta.total) that a seeded install does not satisfy, and the suites share one database with no rollback between runs, so counts drift.

Never report a failure count as a regression without comparing. Revert your change, re-run the same command, and diff the failing test names, not the counts — baseline.md has the commands. An empty diff is the evidence that the gate passed.

Rules

• A gate you did not run is a gate that failed. Report each one explicitly, including the ones the diff did not reach: "no view or JS changes — Playwright skipped" is a result; silence is not.
• Fix the cause, never the check. Do not delete or skip a test, loosen an assertion, or add a Pint exclusion to reach green.
• A pre-existing failure you did not cause is still reported, with the evidence that it pre-dates the change.
• Prove a fix by breaking it. When a change fixes a bug, revert the fix and watch the new test fail. A test that passes both ways guards nothing — it is the most common way a regression test is born dead.
• Rebuild assets after any frontend change, then re-run the E2E gate: cd packages/Webkul/<Admin|Shop> && npm run build.
• Do not commit or stage as part of verification unless asked.

Common mistakes

• Reporting counts instead of names. Two runs of the same suite can differ without any code change; only the name diff is meaningful.
• Running Pint over the whole repo and reporting someone else's debt. Scope it: vendor/bin/pint --test <changed paths>.
• Claiming the translation gate passed after editing only en. The checker compares all 22 locales; editing one and running nothing is the usual path to a red pipeline.
• Treating a green translation gate as covering an extension. It only scans packages/Webkul. For a symlinked extension it reports success without having read a single one of its lang files — see gate 4.
• Skipping E2E because "it is only a Blade change". Views are exactly what the E2E gate covers.