bagisto-playwright-testing

Playwright 测试

不要先写测试规范

“为 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	连续两次因正确原因而通过的运行
把关	quality-gate.md	已完成的检查清单

根据改动规模调整流程。 修复一行定位器，只需调查（定位器为何失效？）和验证（功能失效时测试是否仍会失败？），不需要覆盖矩阵。新增功能领域则需要完成所有步骤。无论如何都不能跳过：阅读应用程序代码，并验证测试确实能够失败。

如何思考这项工作

• 最大化有意义的行为覆盖，而不是测试数量。 十个仅输入值不同的测试，其实可以合并成一个带数据表的测试。
• 测试通过不代表测试质量好。 还要单独确认它是否可能失败——如果删掉该功能，测试会不会变红？
• 不要不加判断地复制现有测试。 这些测试套件中有些测试只断言提示消息是否出现。
• 业务前提条件不等于执行依赖。 建立所需状态；绝不要依赖另一个测试规范先运行。
• 添加等待前，先明确要等待的对象。
• 更改任何内容前，先对失败进行分类。 如果应用程序有问题，红色测试正在发挥作用——绝不要为了让测试变绿而修改断言。
• **选择定位器，是因为它稳定且能唯一标识目标元素，**绝不是因为它简短，或能让严格模式不再报错。
• 先搜索，再构建。 新建夹具、辅助函数或页面对象应是最后的选择；先考虑复用、扩展和重构。
• 回归测试只有在针对缺陷运行并失败后，才算完成。
• **优先采用所需机制最少、行为验证力度最强的方法，**并在风险得到覆盖后停止——何时停止请参阅 test-design.md。

架构

三个独立的 Playwright 项目 — packages/Webkul/{Admin,Shop,Installer}/tests/e2e-pw/， 每个项目都有自己的 playwright.config.ts、setup.ts、pages/、tests/、utils/ 和 data/ — 以及根目录下的 tests/e2e-pw/helpers/ 层，包含三个项目通过 @shared/* 引入的无依赖辅助工具。

以下两条规则至关重要：

• 共享层不依赖任何内容。 CI 仅按包安装 node_modules，因此 helpers/ 下的任何内容都不得导入 @playwright/test、dotenv 或任何第三方包。需要依赖这些内容的辅助工具应放在相应包的 utils/ 中。
• 各测试套件不共享页面对象、fixture 或测试规格。 每个套件都包含其驱动的屏幕所需的页面对象，包括另一侧的屏幕。切勿跨包边界导入。

各测试套件和发布分支的超时设置不同，因此请查看当前检出的 playwright.config.ts。使用 test.setTimeout(...) 延长单个流程的超时时间，切勿修改配置。

完整布局、代码放置位置表、封装模式和超时值：见 architecture.md。

运行

请在包目录中运行，切勿在仓库根目录运行 — node_modules 位于包目录中。三个包都提供相同的脚本：

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 规格文件也绝不能假设 Admin 规格文件配置过任何内容——admin-and-shop.md。
• Admin 身份验证由 adminPage fixture 缓存到 .state/admin-auth.json。 不要在规格文件中手动登录；调用 loginAsAdmin(page) 的 Shop 促销规格文件属于旧代码——参见 authoring.md。
• 任何前端更改后，运行测试前都要重新构建资源， 否则浏览器会加载之前的构建产物，导致看起来像是测试错误。
• 绝不要同时对同一个数据库运行 Pest 和 Playwright。 E2E 运行会重新定价商品并更改设置，而功能测试套件会读取这些数据；这会导致 Pest 测试失败，看起来像是代码有问题——troubleshooting.md。
• tests/e2e-pw/ 下的任何位置都不得有注释——不许有 //、/* */ 或文档块注释。这是 Bagisto 的约定，目前在所有三个测试套件中都无一例外地遵守，并且刻意不同于通用 Playwright 建议。改为在方法名中说明原因；authoring.md 介绍了具体做法。
• 在 beforeEach 内生成测试数据，绝不要在模块作用域生成。 在模块作用域调用一次 uniqueStamp()，会让文件中的所有测试都使用相同的 SKU；只有清理过程从未遗漏时，该文件才能通过。
• 依赖时钟的测试，首先要考虑时区问题。 应用运行于 APP_TIMEZONE（此处为 Asia/Kolkata），配置会将 Node 和浏览器固定到同一时区。凡是涉及今天、明天、时段、可用性或到期时间的情况，都应先参考 time-and-timezone.md 进行调查。
• “不稳定”是结论，不是起始假设。 单个分片失败、单个数据库驱动失败或本地测试通过，都不能证明测试不稳定。先获取跟踪记录、时间戳和服务器日志——troubleshooting.md。
• 文件名使用小写连字符格式，并且声明类的文件名必须与类名完全一致——用 CatalogAclPage.ts，而不是 catalog.ts。Describe 和测试标题使用小写字母，单词间用一个空格。不要添加数字排序前缀。

规格文件说明意图并组合工作流；页面对象负责所有定位器，并通过命名的 expect… 方法进行断言。包含 CSS 选择器的规格文件应改用页面对象——authoring.md。

必需的子技能： 在宣布任何更改完成前，使用 bagisto-change-verification。