ln-743-test-infrastructure

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

ln-743-test-infrastructure

类型： L3 Worker 类别： 7XX 项目引导

为项目设置测试框架、覆盖率工具和示例测试。

---

目的与范围

会做：

• 检测项目技术栈，以选择合适的测试框架
• 创建测试配置文件
• 设置带阈值的覆盖率报告
• 创建用于演示模式的示例测试
• 验证测试套件能否成功运行

不会做：

• 配置代码检查工具（ln-741 负责）
• 设置提交前钩子（ln-742 负责）
• 编写实际的应用测试（由开发者负责）

---

支持的技术栈

技术	测试框架	覆盖率工具	配置文件
TypeScript/React	Vitest	v8/Istanbul	vitest.config.ts
.NET	xUnit	Coverlet	*.Tests.csproj
Python	pytest	pytest-cov	pytest.ini 或 pyproject.toml

---

阶段 1：检查现有测试

创建测试基础设施前，先检查现有内容。

要检查的文件：

技术栈	测试标识
TypeScript	vitest.config.*、jest.config.*、*.test.ts、*.spec.ts
.NET	*.Tests.csproj、*.IntegrationTests.csproj
Python	pytest.ini、conftest.py、tests/、test_*.py

决策逻辑：

1. 如果已有完整的测试配置：跳过（告知用户）
2. 如果已有部分配置：询问是扩展还是替换
3. 如果没有测试：从模板创建

---

阶段 2：创建测试配置

TypeScript/React（Vitest）

创建 vitest.config.ts：

• 使用 v8 覆盖率提供程序（比 Istanbul 更快）
• 为 React 配置 jsdom 环境
• 设置覆盖率阈值（最低 80%）
• 为 testing-library 创建设置文件

依赖项：

npm install -D vitest @vitest/coverage-v8 @testing-library/react @testing-library/jest-dom jsdom

.NET（xUnit）

创建测试项目：

dotnet new xunit -n {Project}.Tests
dotnet sln add tests/{Project}.Tests

依赖项（在 .csproj 中）：

• Microsoft.NET.Test.Sdk
• xunit
• xunit.runner.visualstudio
• Moq
• FluentAssertions
• coverlet.collector

Python（pytest）

添加到 pyproject.toml 或创建 pytest.ini：

• 配置测试发现路径
• 设置覆盖率阈值（最低 80%）
• 配置覆盖率报告

依赖项：

pip install pytest pytest-cov pytest-asyncio
# OR with uv:
uv add --dev pytest pytest-cov pytest-asyncio

---

阶段 3：创建测试目录结构

TypeScript

src/
├── components/
│   ├── Button.tsx
│   └── Button.test.tsx  # Co-located tests
├── test/
│   └── setup.ts         # Test setup file

.NET

tests/
├── {Project}.Tests/
│   ├── Controllers/
│   │   └── SampleControllerTests.cs
│   ├── Services/
│   └── {Project}.Tests.csproj
└── {Project}.IntegrationTests/  # Optional

Python

tests/
├── conftest.py          # Shared fixtures (from conftest_template.py)
├── unit/
│   └── test_sample.py
└── integration/         # Optional

对于 FastAPI/异步项目，使用 conftest_template.py 生成 conftest.py，其中包含共享的异步 HTTP 客户端 fixture。调整应用导入路径以匹配项目。

---

阶段 4：创建示例测试

为每种技术栈创建一个示例测试，用于演示：

• AAA 模式（准备-执行-断言）
• 测试命名约定
• 基本断言
• 特定于框架的模式

TypeScript 示例测试

演示：

• testing-library 中的 render()
• screen 查询
• Jest-dom 匹配器

.NET 示例测试

演示：

• [Fact] 特性
• 使用 Moq 进行模拟
• FluentAssertions 语法

Python 示例测试

演示：

• pytest fixtures
• assert 语句
• 参数化测试（可选）

---

阶段 5：验证测试运行

设置完成后，验证测试能否正常工作。

TypeScript：

npm test
npm run test:coverage

预期：示例测试通过，并生成覆盖率报告

.NET：

dotnet test
dotnet test --collect:"XPlat Code Coverage"

预期：示例测试通过，并收集覆盖率数据

Python：

pytest
pytest --cov=src --cov-report=term-missing

预期：示例测试通过，并显示覆盖率报告

**失败时：**检查测试配置和依赖项，并验证示例测试语法。

---

覆盖率要求

指标	最低值	目标值
行	70%	80%
分支	70%	80%
函数	70%	80%
语句	70%	80%

配置 CI，使覆盖率低于阈值时构建失败。

---

关键规则

**RULE 1：**必须配置覆盖率阈值。没有例外。

**RULE 2：**示例测试必须通过。不要创建有问题的示例。

**RULE 3：**所有示例测试都必须使用 AAA 模式（Arrange-Act-Assert）。

**RULE 4：**单元测试应与源代码放在一起（TypeScript），或放在 tests/ 目录中（.NET、Python）。

---

**Monitor（2.1.98+）：**如果脚手架生成后的测试验证预计耗时超过 30 秒，请使用 Monitor。备用方案：Bash(run_in_background=true)。

完成标准

• 已安装并配置测试框架
• 已配置覆盖率工具，阈值为 80%
• 已创建测试目录结构
• 已创建示例测试，且测试通过
• npm test / dotnet test / pytest 均可成功运行
• 可生成覆盖率报告
• 已告知用户：
  • 如何运行测试
  • 在哪里添加新测试
  • 覆盖率要求

---

参考文件

文件	用途
vitest_template.ts	Vitest 配置模板
vitest_setup_template.ts	测试设置文件
react_test_template.tsx	React 组件测试
xunit_csproj_template.xml	.NET 测试项目
xunit_test_template.cs	xUnit 测试示例
pytest_config_template.toml	pytest 配置
pytest_test_template.py	pytest 测试示例
conftest_template.py	共享异步固件（FastAPI）
testing_guide.md	测试最佳实践

---

错误处理

错误	原因	解决方案
未找到 Vitest	尚未安装	npm install -D vitest
jsdom 错误	缺少依赖	npm install -D jsdom
xUnit 发现失败	SDK 版本不匹配	更新 Microsoft.NET.Test.Sdk
未找到 pytest	不在 PATH 中	pip install pytest
覆盖率为 0%	源代码路径错误	检查 coverage.include 配置

---

**版本：**3.0.0 **最后更新：**2026-03-18