ns-code-e2e-tests

创建端到端测试

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

测试框架发现

存在时，加载 {harness}/rules/e2e-tests-rules.mdc。布局和引导流程概要请参阅 references/e2e-architecture.md。

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

在编写任何测试规格或命令代码之前，先定位 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	baseUrl 取自 CYPRESS_BASE_URL；specPattern 为 cypress/e2e/**/*.cy.ts
脚本	在 tests-e2e/package.json 中添加 cypress:open、cypress:run

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

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

0.3 — 引导后的文档更新

当 {product_root}/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)——使用拦截或断言超时
• RBAC：菜单隐藏 + 直接访问 URL 时拒绝
• 身份验证：通过 UI 登录或使用 support 会话；使用租户感知型固定数据

阶段 5 — 运行并报告

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

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

参考资料

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

相关技能

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