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.