ns-backend-tests

创建后端测试

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

会话启动

如存在 .nextstage-harness/rules/backend-tests-rules.mdc 和 backend-rules.mdc，请加载。有关目录布局、运行约定和引导摘要，请参阅 references/backend-testing-architecture.md。

阶段 0 — 确定或引导后端测试根目录

编写任何测试类代码之前，先定位 PHPUnit 项目或创建最小结构。

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

按以下顺序在仓库中搜索：

1. backend/phpunit.xml
2. 仓库根目录下的 phpunit.xml
3. composer.json 所在目录下的 tests/Unit/ 或 tests/Feature/（其中 composer.json 包含 PHPUnit）

将包含 phpunit.xml 的目录记录为 {backend_root}。以下所有路径均相对于 {backend_root}。

0.2 — 无现有结构时进行引导（绿地项目）

如果存在后端应用代码（app/、src/ 或同等目录），但不存在 phpunit.xml 和 tests/：

规则	详情
位置	如果存在 backend/ 包，则使用该目录；否则使用仓库根目录
目录树	按照 references/backend-testing-architecture.md — phpunit.xml、tests/TestCase.php、tests/Unit/、tests/Feature/
依赖	通过现有的 composer.json 使用 PHPUnit — 绝不添加到前端或无关的包中

然后将该目录设为 {backend_root}。

绿地项目中禁止： 假定测试已存在、在主机上运行 PHPUnit，或在后端包之外搭建测试结构。

0.3 — 引导后的文档更新

如果存在 docs/context/stack-confirmed.md 或 architecture-rules.md，请添加或更新后端测试行：{backend_root}、Docker 测试容器，以及阶段 5 中的 PHPUnit 运行命令。

确认 {backend_root} 且 phpunit.xml 可读后，才能继续阶段 1。

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

1. 被测代码 — 阅读实现文件（Service、FormRequest、Controller 等）
2. 现有测试 — 阅读 tests/Unit/ 和 tests/Feature/ 下的匹配文件；扩展现有测试，不要重复编写
3. 项目模式 — 根据 harness 规则检查工厂、RefreshDatabase、响应封装、多租户辅助工具
4. 任务约定 — 实现单元测试规划任务时，遵循其场景清单

阶段 2 — 编写测试

• 单元测试/功能测试的默认层级： 不通过 HTTP/网络访问真实第三方服务 — 仅使用 fake/fixture（参见 ../../ns-harness/references/docker-and-testing.md 中的测试层级）
• 单元测试：模拟依赖 — 不进行真实的 DB/队列/缓存 I/O
• 功能测试：HTTP 测试，涵盖认证、401/403，以及适用时的跨租户 P0
• 需要真实外部服务或真实 LLM → 使用 PHPUnit live 组（例如 #[Group('live')]）；在 phpunit.xml 中将该组排除在默认运行之外；在 architecture-rules.md 中记录标记和按需运行命令
• 命名：{Component}Test.php，方法名使用描述性 snake_case
• 匹配模块路径：tests/Unit/Modules/{Domain}/、tests/Feature/Modules/{Domain}/
• 绝不通过修改断言来迁就错误行为

阶段 3 — 运行（强制约定）

另请参阅 ../../ns-harness/references/docker-and-testing.md。

1. 运行 docker ps — 确认文档中记录的测试容器（如果未记录，询问一次）
2. 在 {backend_root} 工作目录中于测试容器内执行 — 仅运行默认测试套件（排除 live 组）。除非用户要求本次运行，否则绝不包含 live 组：

timeout 120 docker exec -w {workdir} {test_container} \
  vendor/bin/phpunit --testdox --stop-on-failure --stop-on-error {optional_filter}

3. 超时： 如果命令在 120 秒时被终止（例如退出码为 124），则视为运行已停止/挂起 — 中止并报告阻塞问题，不要悄悄重试
4. 绝不在主机上运行 vendor/bin/phpunit 或 phpunit.sh

筛选运行（单个类或方法）使用相同的标志和超时。

阶段 4 — 报告

• 通过：列出新增/更改的文件
• 失败：报告 --testdox 输出中的首个失败测试名称和断言
• 挂起/超时：说明已超过 120 秒限制；如果根因不明确，则调用 ns-investigator

参考资料

文件	用途
references/backend-testing-architecture.md	布局、引导、运行约定
../ns-spec-driven/references/unit-test-task-generator.md	任务约定来源

相关技能

• ns-spec-driven references/unit-test-task-generator.md — 规划任务
• ns-investigator — 调试失败或卡住的测试
• ns-coder — 处理计划外单元测试任务的临时修复