ns-code-backend-tests

创建后端测试

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

探查测试框架

如果存在，请加载 {harness_root}/rules/backend-tests-rules.mdc 和 backend-rules.mdc。布局、运行约定和引导摘要见 references/backend-testing-architecture.md。

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

编写任何测试类代码之前，先找到 PHPUnit 项目或创建最精简的结构。

0.1 — 检测现有测试（存量项目）

按以下顺序搜索 {product_root}：

1. backend/phpunit.xml
2. {product_root}/ 下的 phpunit.xml
3. 含有 PHPUnit 的 composer.json 所在目录下的 tests/Unit/ 或 tests/Feature/

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

0.2 — 在不存在测试时进行引导（全新项目）

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

规则	详情
位置	单体仓库使用 {product_root}/backend/；否则使用 {product_root}/
目录树	按照 references/backend-testing-architecture.md — phpunit.xml、tests/TestCase.php、tests/Unit/、tests/Feature/
依赖	通过现有 composer.json 使用 PHPUnit — 切勿添加到前端或无关软件包中

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

全新项目中禁止： 假设测试已存在、在主机上运行 PHPUnit，或在后端软件包之外搭建测试结构。

0.3 — 引导后的文档更新

当 {product_root}/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. 项目模式 — 参考框架规则中的工厂、RefreshDatabase、响应封装、多租户辅助工具
4. 任务约定 — 实现 ns-pm-unit-test-task-generator 任务时，遵循其场景检查清单

阶段 2 — 编写测试

• 单元测试：模拟依赖 — 不进行真实的数据库、队列或缓存 I/O
• 功能测试：编写 HTTP 测试，涵盖身份验证、401/403，以及适用时的跨租户 P0
• 命名：{Component}Test.php，方法名使用描述性的蛇形命名法
• 匹配模块路径：tests/Unit/Modules/{Domain}/、tests/Feature/Modules/{Domain}/

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

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

1. 运行 docker ps — 确认文档中指定的测试容器（若未记录，则询问一次）
2. 在测试容器内、以 {backend_root} 为工作目录执行：

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-code-investigator

参考

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

相关技能

• ns-pm-unit-test-task-generator — 规划任务
• ns-code-investigator — 调试失败或卡住的测试
• ns-code-coder — 修复计划外单元测试任务中的临时问题