ns-e2e-tests

创建端到端测试

执行阶段的 Cypress 实现。规划阶段：ns-spec-driven/references/e2e-test-task-generator.md。

会话启动

存在时加载 .nextstage-harness/rules/e2e-tests-rules.mdc。布局和引导摘要请参阅 references/e2e-architecture.md。

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

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

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

按以下顺序搜索仓库：

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 中没有匹配项，则将 tests-e2e/ 创建为独立的 Node 项目：

规则	详情
位置	仅限 tests-e2e/
package.json	放在此处 — 切勿将 Cypress 添加到 frontend/package.json
目录树	遵循 references/e2e-architecture.md（配置 + 空的 device/ 文件夹 + support 导入）
cypress.config.ts	baseUrl 从 CYPRESS_BASE_URL 获取；specPattern 为 cypress/e2e/**/*.cy.ts
脚本	在 tests-e2e/package.json 中添加 cypress:open、cypress:run

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

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

0.3 — 引导后的文档更新

当 docs/context/stack-confirmed.md 或 architecture-rules.md 存在时，添加或更新端到端测试行：位置为 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 中注册新的命令文件。

测试规格：使用 describe/it、cy.visit()、命令和断言 — 测试规格中不得包含 DOM 逻辑。

阶段 3 — 测试规格布局

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

在 beforeEach 中设置视口：

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

禁止：直接将测试规格放在 cypress/e2e/ 下，而不使用 device/ 前缀。

阶段 4 — 实现

• 使用 frontend 任务约定中的 data-testid — 不要自行编造
• 不使用固定的 cy.wait(N) — 使用拦截或断言超时
• 默认对第三方 HTTP/API 调用进行存根（拦截/夹具）。真实第三方流程 → 选择启用的项目/标签（实时层级）；除非人工要求，否则从默认的 cypress:run / CI 中排除
• RBAC：隐藏菜单 + 拒绝直接 URL 访问
• 身份验证：通过 UI 登录或使用 support session；使用支持租户的夹具

阶段 5 — 运行并报告

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

SDD 版本执行： 在 execution-handoff.md / run-implementation 下调用时，仅编写或重构测试规格 — 不要运行端到端测试套件。由人工在版本结束时运行端到端测试。

参考资料

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

相关技能

• ns-spec-driven references/e2e-test-task-generator.md — 使用 testid 契约规划任务
• ns-investigator — 调试失败的 E2E 测试
• ns-gitlab-ci-generator — CI cd tests-e2e 和变更路径