create-e2e-tests

创建端到端测试

执行阶段的 Cypress 实现。规划阶段：e2e-test-generator。

测试框架发现

如果存在 {harness}/rules/e2e-tests-rules.mdc，请加载该文件。有关目录结构和引导流程摘要，请参阅 references/e2e-architecture.md。

阶段 0 — 确定或引导 Cypress 根目录

在编写任何 spec 或命令代码之前，先定位 Cypress 项目或创建项目。

0.1 — 检测现有端到端测试（棕地项目）

按以下顺序搜索 {product_root}：

1. tests-e2e/cypress.config.ts
2. testes-cypress/cypress.config.ts（旧名称）
3. frontend/cypress.config.ts（旧的同级目录）

将包含 cypress.config.ts 的目录记录为 {e2e_root}。除非另有说明，以下所有路径均相对于 {e2e_root}。

0.2 — 不存在时进行引导（绿地项目）

如果 0.1 中没有匹配项，则创建 {product_root}/tests-e2e/，作为独立的 Node 项目：

规则	详情
位置	仅限 {product_root}/tests-e2e/
package.json	放在这里 — 绝不要将 Cypress 添加到 frontend/package.json
目录树	按照 references/e2e-architecture.md（配置文件 + 空的 device/ 文件夹 + support 导入）
cypress.config.ts	从 CYPRESS_BASE_URL 获取 baseUrl；specPattern 为 cypress/e2e/**/*.cy.ts
脚本	在 tests-e2e/package.json 中添加 cypress:open、cypress:run

然后设置 {e2e_root} = {product_root}/tests-e2e/。

绿地项目中禁止： 在 frontend/cypress/ 下搭建项目、将依赖复制到 frontend 的锁文件，或假设应用 package 中已安装 Cypress。

0.3 — 引导后更新文档

当 {product_root}/docs/context/stack-confirmed.md 或 architecture-rules.md 存在时，添加或更新 E2E 条目：位置为 tests-e2e/，运行命令为 cd tests-e2e && npm run cypress:run（或项目对应的 Docker 命令）。

确认 {e2e_root} 且 cypress.config.ts 可读取后，再进入阶段 1。

阶段 1 — 调研（编写功能代码之前）

1. 被测应用 — 路由、表单、API 用法、现有的 data-testid（读取 frontend/，不要在那里编写 Cypress 代码）
2. 现有命令 — 读取所有 {e2e_root}/cypress/support/commands/；绝不要重复定义
3. 配置 — {e2e_root}/cypress.config.ts 中的 baseUrl、环境变量（CYPRESS_BASE_URL、CYPRESS_API_URL）

阶段 2 — 优先设计命令架构

{e2e_root}/cypress/support/commands/
  shared/[feature].commands.ts   # business actions — all devices
  pages/[feature].commands.ts    # page structure
  device/mobile|tablet|desktop.commands.ts

行为	位置
所有设备通用	shared/
设备专属	device/
页面 DOM 结构	pages/

在 {e2e_root}/cypress/support/e2e.ts 中注册新的命令文件。

Specs：describe/it、cy.visit()、命令、断言 — spec 中不得包含 DOM 逻辑。

阶段 3 — Spec 目录结构

{e2e_root}/cypress/e2e/device/
  desktop/[feature]/[feature]-successful-flows.cy.ts
  tablet/...
  mobile/...

在 beforeEach 中设置视口：

• 桌面：1280×720
• 平板：768×1024
• 移动设备：375×812

禁止：在 cypress/e2e/ 下直接放置 spec，必须使用 device/ 前缀。

阶段 4 — 实现

• 使用 frontend 任务契约中的 data-testid — 不要自行编造
• 不使用固定的 cy.wait(N) — 使用拦截或断言超时
• RBAC：隐藏菜单 + 拒绝直接访问 URL
• 身份验证：通过 UI 登录或使用 support session；使用租户感知型 fixtures

阶段 5 — 运行并报告

在 {e2e_root} 中运行：npm run cypress:run（或产品文档中说明的等效 Docker 命令）。必要时使用 code-investigator 报告失败。

参考资料

文件	适用场景
references/e2e-architecture.md	根目录布局、引导目录树、规则
e2e-test-generator	任务契约来源

相关技能

• e2e-test-generator — 规划包含 testid 契约的任务
• code-investigator — 调试失败的 E2E 测试
• gitlab-ci-generator — CI 中的 cd tests-e2e 和变更路径