Back to Details

bagisto-change-verification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
Bagisto的完成校验关卡。只有当变更差异涉及的所有关卡都通过并完成报告后，变更才算完成。这四个关卡对应
.github/workflows/
中的五个测试工作流——E2E分为Admin和Shop两个独立运行——因此本地通过所有关卡的变更，也能顺利通过流水线校验。

The four gates

四个关卡

#GateCommandApplies when
1Style
vendor/bin/pint --test
any 
.php
changed
2Tests
vendor/bin/pest
any 
.php
changed
3E2E
npx playwright test --config=tests/e2e-pw/playwright.config.ts
any view, JS, CSS or route changed
4Translations
php artisan bagisto:translations:check
any 
Resources/lang/**
changed
Run them in that order — style is seconds, E2E is minutes, and a Pint failure makes the rest moot.
#关卡命令适用场景
1代码风格
vendor/bin/pint --test
任何
.php
文件被修改时
2测试
vendor/bin/pest
任何
.php
文件被修改时
3端到端测试（E2E）
npx playwright test --config=tests/e2e-pw/playwright.config.ts
任何视图、JS、CSS或路由被修改时
4翻译检查
php artisan bagisto:translations:check
任何
Resources/lang/**
文件被修改时
请按上述顺序运行——代码风格检查仅需数秒，E2E测试则需要数分钟，且如果Pint检查失败，后续所有检查都无需进行。

1. Style

1. 代码风格

bash
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.
bash
vendor/bin/pint          # 自动修复
vendor/bin/pint --test   # 验证修复结果：CI将运行该命令
Pint不会格式化
.blade.php
文件。Blade的代码风格需手动调整——请参考
bagisto-coding-standards
技能文档。

2. Tests

2. 测试

bash
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.
bash
vendor/bin/pest                                        # 运行所有测试
vendor/bin/pest packages/Webkul/Admin/tests/Feature    # 运行指定目录下的测试
vendor/bin/pest --testsuite="Admin Feature Test"       # 运行指定测试套件
测试套件定义在
phpunit.xml
中，每个包含测试的包对应一个套件。没有
tests/
目录的包则无对应套件；若为不存在的路径添加
<testsuite>
，会导致PHPUnit报错。

3. End-to-end

3. 端到端测试

Admin and Shop are separate Playwright projects, each run from its own package directory. See the 
bagisto-playwright-testing
skill before writing or debugging one.
bash
cd packages/Webkul/Admin   # or packages/Webkul/Shop
npx playwright test --config=tests/e2e-pw/playwright.config.ts
CI runs each project across 10 shards. Locally, run the spec files your change touches rather than the whole suite.
Admin和Shop是两个独立的Playwright项目，需分别从各自的包目录运行。在编写或调试E2E测试前，请先查看
bagisto-playwright-testing
技能文档。
bash
cd packages/Webkul/Admin   # 或 packages/Webkul/Shop
npx playwright test --config=tests/e2e-pw/playwright.config.ts
CI会将每个项目拆分为10个分片运行。本地测试时，只需运行变更涉及的测试用例文件，无需执行整个套件。

4. Translations

4. 翻译检查

bash
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.
bash
php artisan bagisto:translations:check
每个翻译键必须存在于
Resources/lang/
下的全部22个语言环境中。缺少任意一个语言环境的翻译键都会导致工作流失败。
该检查工具仅扫描
packages/Webkul
目录。对于其他来源的包——例如通过符号链接引入的扩展克隆——工具会直接返回成功，不会读取其语言文件。如需验证这类包的翻译，请参考translations.md文档，了解验证方法及翻译措辞的规范。

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.
这并非一个可通过命令验证的关卡——没有任何命令能直接返回“安全”结果。在标记工作完成前，需针对变更差异回答以下问题：
本次变更是否涉及授权逻辑、渲染输出、用户输入、文件上传、原生SQL、密钥或支付相关功能？
如果是，请参照
bagisto-coding-standards
技能文档中的检查清单，针对变更涉及的内容进行排查。如果否，请明确说明——例如“未涉及授权、输出或输入相关内容”，就像跳过Playwright测试时需要明确说明一样，不能保持沉默。
上述四个关卡无法覆盖安全检查。Pint不会关注未限定范围的查询，测试套件即使存在IDOR漏洞也可能正常通过。

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, run the same command, and diff the failing test names — not the counts, which move on their own:
bash
vendor/bin/pest <path> 2>&1 | grep -E "^  ⨯" | sed 's/ *[0-9.]*s *$//' | sort > /tmp/with.txt
Bagisto的测试套件并非在任何 checkout 状态下都能全部通过。部分测试会断言绝对计数（如
meta.total
），而种子数据安装无法满足这些断言；此外，所有套件共享同一个数据库，且测试间不会回滚数据，导致计数会逐渐偏移。
切勿直接将失败数量增加视为变更导致的回归。 请先回滚变更，运行相同命令，对比失败测试的名称——而非数量，因为数量会自行变化：
bash
vendor/bin/pest <path> 2>&1 | grep -E "^  ⨯" | sed 's/ *[0-9.]*s *$//' | sort > /tmp/with.txt

revert the change, re-run into /tmp/without.txt

回滚变更，重新运行并将结果写入/tmp/without.txt

comm -23 /tmp/with.txt /tmp/without.txt # empty means you introduced nothing

An empty diff is the evidence that the gate passed. A count that went 3 → 4 is
not evidence of anything.
comm -23 /tmp/with.txt /tmp/without.txt # 输出为空则说明变更未引入新问题

输出为空是关卡通过的证明。失败数量从3变为4并不能说明任何问题。

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.
  • 未运行的关卡视为失败。请明确报告每个关卡的结果，包括变更未涉及的关卡：例如“未修改视图或JS文件——跳过Playwright测试”是有效结果，保持沉默则不是。
  • 修复问题根源，而非修改检查规则。请勿为了通过检查而删除或跳过测试、放宽断言条件，或添加Pint排除规则。
  • 即使是预先存在的失败，也需报告，并提供该失败早于本次变更的证据。
  • 通过反向验证证明修复有效。当变更修复了某个bug时，回滚修复并确认新测试会失败。无论是否修复都能通过的测试毫无意义——这是回归测试失效的最常见原因。
  • 任何前端变更后需重新构建资源，然后重新运行E2E关卡：
    cd packages/Webkul/<Admin|Shop> && npm run build
    。
  • 除非明确要求，否则请勿在验证过程中提交或暂存文件。

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.
  • 仅报告失败数量而非测试名称。同一套件的两次运行可能在无代码变更的情况下出现数量差异；只有测试名称的差异才有意义。
  • 对整个仓库运行Pint并报告他人遗留的问题。请限定范围：
    vendor/bin/pint --test <变更文件路径>
    。
  • 仅修改
    en
    语言文件后就声称翻译检查通过    。检查工具会对比全部22个语言环境；仅修改一个语言文件且未运行检查是导致流水线失败的常见原因。
  • 认为翻译检查通过就覆盖了扩展包。该工具仅扫描
    packages/Webkul
    目录。对于符号链接引入的扩展包，工具会直接返回成功，但并未读取其任何语言文件——请参考第4个关卡的说明。
  • 因“仅修改了Blade文件”而跳过E2E测试。视图文件正是E2E关卡的覆盖范围。