Back to Details

ns-backend-tests

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create Backend Tests

创建后端测试

Execution-phase PHPUnit implementation. Planning-phase: 
ns-spec-driven/references/unit-test-task-generator.md
.
执行阶段的PHPUnit实现。规划阶段请参考：
ns-spec-driven/references/unit-test-task-generator.md
。

Session boot

会话启动

Load 
.nextstage-harness/rules/backend-tests-rules.mdc
and 
backend-rules.mdc
when present. See 
references/backend-testing-architecture.md
for layout, run contract, and bootstrap summary.
若存在
.nextstage-harness/rules/backend-tests-rules.mdc
和
backend-rules.mdc
文件，请加载。关于布局、运行约定和初始化概要，请查看
references/backend-testing-architecture.md
。

Phase 0 — Resolve or bootstrap backend test root

阶段0 — 确定或初始化后端测试根目录

Before any test class code, locate the PHPUnit project or create minimal structure.
在编写任何测试类代码之前，定位PHPUnit项目或创建最小化结构。

0.1 — Detect existing tests (brownfield)

0.1 — 检测现有测试（遗留项目）

Search the repo in this order:
  1. backend/phpunit.xml
  2. phpunit.xml
    at repo root
  3. tests/Unit/
    or 
    tests/Feature/
    under the directory that contains 
    composer.json
    with PHPUnit
Record the directory containing 
phpunit.xml
as 
{backend_root}
. All paths below are relative to 
{backend_root}
.
按以下顺序搜索仓库：
  1. backend/phpunit.xml
  2. 仓库根目录下的
    phpunit.xml
  3. 包含带有PHPUnit依赖的
    composer.json
    的目录下的
    tests/Unit/
    或
    tests/Feature/
将包含
phpunit.xml
的目录记录为**
{backend_root}
**。以下所有路径均相对于
{backend_root}
。

0.2 — Bootstrap when nothing exists (greenfield)

0.2 — 无测试时初始化（全新项目）

If backend application code exists (
app/
, 
src/
, or equivalent) but no 
phpunit.xml
and no 
tests/
:
RuleDetail
Location
backend/
when that package exists; else repo root
TreePer 
references/backend-testing-architecture.md
— 
phpunit.xml
, 
tests/TestCase.php
, 
tests/Unit/
, 
tests/Feature/
DependenciesPHPUnit via existing 
composer.json
— never add to frontend or unrelated packages
Then set 
{backend_root}
to that directory.
Forbidden on greenfield: assuming tests exist, running PHPUnit on the host, or scaffolding tests outside the backend package.
若存在后端应用代码（
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 — Post-bootstrap documentation

0.3 — 初始化后文档更新

When 
docs/context/stack-confirmed.md
or 
architecture-rules.md
exists, add or update the backend test row: 
{backend_root}
, docker test container, and the PHPUnit run command from Phase 5.
Do not proceed to Phase 1 until 
{backend_root}
is confirmed and 
phpunit.xml
is readable.
若存在
docs/context/stack-confirmed.md
或
architecture-rules.md
文件，添加或更新后端测试行：
{backend_root}
、Docker测试容器，以及阶段5中的PHPUnit运行命令。
在确认
{backend_root}
且
phpunit.xml
可读之前，请勿进入阶段1。

Phase 1 — Discovery (before feature code)

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

  1. Code under test — read implementation files (Service, FormRequest, Controller, etc.)
  2. Existing tests — read matching files under 
    tests/Unit/
    and 
    tests/Feature/
    ; extend, do not duplicate
  3. Project patterns — factories, 
    RefreshDatabase
    , response envelope, multitenancy helpers from harness rules
  4. Task contract — when implementing a unit-test planning task, follow its scenario checklist
  1. 被测代码 — 阅读实现文件（Service、FormRequest、Controller等）
  2. 现有测试 — 阅读
    tests/Unit/
    和
    tests/Feature/
    下的匹配文件；扩展而非重复编写
  3. 项目模式 — 从测试框架规则中获取工厂类、
    RefreshDatabase
    、响应包、多租户助手等内容
  4. 任务约定 — 若实现单元测试规划任务，请遵循其场景检查清单

Phase 2 — Write tests

阶段2 — 编写测试

  • Unit: mock dependencies — no real DB/queue/cache I/O
  • Feature: HTTP tests with auth, 401/403, cross-tenant P0 when applicable
  • Naming: 
    {Component}Test.php
    , descriptive snake_case method names
  • Match module paths: 
    tests/Unit/Modules/{Domain}/
    , 
    tests/Feature/Modules/{Domain}/
  • 单元测试：模拟依赖 — 不进行真实的数据库/队列/缓存I/O操作
  • 功能测试：带认证的HTTP测试，必要时覆盖401/403、跨租户P0场景
  • 命名规则：
    {Component}Test.php
    ，方法名使用描述性蛇形命名（snake_case）
  • 模块路径匹配：
    tests/Unit/Modules/{Domain}/
    、
    tests/Feature/Modules/{Domain}/

Phase 3 — Run (mandatory contract)

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

See also 
../../ns-harness/references/docker-and-testing.md
.
  1. Run 
    docker ps
    — confirm the documented test container (ask once if undocumented)
  2. Execute inside the test container at 
    {backend_root}
    workdir:
bash
timeout 120 docker exec -w {workdir} {test_container} \
  vendor/bin/phpunit --testdox --stop-on-failure --stop-on-error {optional_filter}
  1. Timeout: if the command is killed at 120s (e.g. exit 124), treat the run as dead/hung — abort, report blocker, do not silently retry
  2. Never run 
    vendor/bin/phpunit
    or 
    phpunit.sh
    on the host
Filtered runs (single class or method) use the same flags and timeout.
另请参考
../../ns-harness/references/docker-and-testing.md
。
  1. 运行
    docker ps
    — 确认文档中记录的测试容器（若未记录则询问一次）
  2. 在
    {backend_root}
    工作目录下的测试容器内执行：
bash
timeout 120 docker exec -w {workdir} {test_container} \
  vendor/bin/phpunit --testdox --stop-on-failure --stop-on-error {optional_filter}
  1. 超时处理： 若命令在120秒时被终止（例如退出码124），则判定运行无响应/挂起 — 终止操作，上报阻塞问题，请勿静默重试
  2. 禁止在宿主机上运行
    vendor/bin/phpunit
    或
    phpunit.sh
过滤运行（单个类或方法）需使用相同的参数和超时设置。

Phase 4 — Report

阶段4 — 报告

  • Pass: list files added/changed
  • Fail: first failing test name + assertion from 
    --testdox
    output
  • Hung/timeout: state 120s limit exceeded; invoke 
    ns-investigator
    if root cause unclear
  • 通过：列出新增/修改的文件
  • 失败：第一个失败测试的名称 + 
    --testdox
    输出中的断言信息
  • 无响应/超时：说明已超过120秒限制；若根因不明确则调用
    ns-investigator

References

参考文档

FileWhen
references/backend-testing-architecture.md
Layout, bootstrap, run contract
../ns-spec-driven/references/unit-test-task-generator.md
Task contract source
文件使用场景
references/backend-testing-architecture.md
布局、初始化、运行约定
../ns-spec-driven/references/unit-test-task-generator.md
任务约定来源

Related skills

相关技能

  • ns-spec-driven
    references/unit-test-task-generator.md
    — planning tasks
  • ns-investigator
    — failing or hung test debugging
  • ns-coder
    — ad-hoc fixes outside planned unit-test tasks
  • ns-spec-driven
    references/unit-test-task-generator.md
    — 规划任务
  • ns-investigator
    — 失败或挂起测试的调试
  • ns-coder
    — 计划外单元测试任务的临时修复