test-architect

测试架构师

设计测试策略，分析覆盖率缺口，识别边界情况，诊断不稳定测试，并审查测试套件架构。

**范围：**仅限测试设计与分析。不用于运行测试或 CI/CD（devops-engineer）、代码审查（review）或 TDD 工作流。

调度

$ARGUMENTS	操作
design <feature/module>	为功能或模块设计测试策略和测试金字塔
generate <file/function>	生成测试用例（根据上下文生成策略文本或实际测试代码）
gaps	根据覆盖率报告分析覆盖率缺口
edge-cases <function>	系统地识别函数的边界情况
flaky	根据日志和代码诊断不稳定测试
review	审查测试套件架构
空	显示带示例的模式菜单

规范词汇

在所有模式中始终准确使用以下术语：

术语	定义
测试金字塔	分层的测试分布：单元测试（底层）、集成测试（中层）、端到端测试（顶层）
覆盖率缺口	没有测试覆盖的代码路径，按复杂度风险加权
边界情况	边界条件、null/空值、类型强制转换、溢出、Unicode、并发场景下的输入
不稳定测试	在相同运行条件下，结果会非确定性地通过或失败的测试
变异分数	测试套件检测到的注入变异所占的百分比
测试策略	定义测试内容、方法、层级和工具的文档
基于属性的测试	对生成的输入验证不变量的测试（Hypothesis/fast-check）
测试隔离	保证测试之间不共享可变状态，也不依赖执行顺序
测试夹具	可复用的测试设置/清理流程，用于提供受控状态
测试面	需要测试覆盖的公共接口、代码路径和状态集合

模式 1：设计

/test-architect design <feature/module>

测试面分析

1. 阅读功能/模块代码。梳理测试面：公共 API、内部路径、状态转换和错误条件。
2. 对复杂度分类：简单（纯函数）、中等（I/O、状态）、复杂（分布式、并发、多服务）。

测试金字塔设计

3. 设计测试金字塔：
   • **单元层：**纯逻辑、转换、验证器。目标：占测试总数的 70-80%。
   • **集成层：**数据库、API、文件 I/O、服务边界。目标：占 15-25%。
   • **端到端层：**仅覆盖关键用户流程。目标：占 5-10%。
4. 为每一层列出具体测试用例，包括：描述、输入、预期输出、理由。
5. 根据语言/生态系统推荐框架和工具。
6. 输出：结构化策略文档，包含金字塔图、用例列表和优先级顺序。

参考：阅读 references/test-pyramid.md，了解各层的指导原则。

模式 2：生成

/test-architect generate <file/function>

1. 阅读目标文件/函数。识别其签名、依赖项和副作用。
2. 确定输出格式：
   • 如果目标已有测试文件：按照现有模式生成实际测试代码。
   • 如果目标没有测试文件：生成带用例说明的测试策略文本。
   • 如果用户指定 --code：始终生成测试代码。
3. 生成覆盖以下内容的测试用例：
   • 正常路径（预期输入和输出）
   • 错误路径（无效输入、异常、超时）
   • 边界情况（如果函数有类型化参数，则运行 edge-case-generator.py）
   • 边界条件（最小/最大值、空集合、null）
4. 遵循框架约定：阅读 references/framework-patterns.md，了解 pytest/jest/vitest 模式。
5. 输出：按类别设置清晰分节标题的测试用例或测试代码。

模式 3：缺口

/test-architect gaps

1. 定位覆盖率报告。搜索：
   • coverage.json、coverage.xml、.coverage（Python/coverage.py）
   • lcov.info、coverage/lcov.info（JS/lcov）
   • htmlcov/、coverage/ 目录
2. 运行覆盖率分析器：

   uv run python skills/test-architect/scripts/coverage-analyzer.py <report-path>
   

3. 解析 JSON 输出。按复杂度加权风险对缺口排序。
4. 对每个缺口进行评估：
   • 哪些代码未经测试，以及这为何重要
   • 复杂度评分（圈复杂度代理指标）
   • 建议的测试类型（单元/集成/e2e）
   • 优先级（P0：安全/身份验证，P1：核心逻辑，P2：实用工具，P3：外观）
5. 如果有 10 个或更多缺口，则渲染仪表板：

   Copy templates/dashboard.html to a temporary file
   Inject gap data JSON into <script id="data"> tag
   Open in browser
   

6. 输出：按优先级排序的缺口列表及建议操作。

参考：阅读 references/coverage-analysis.md，了解解读指南。

模式 4：边界情况

/test-architect edge-cases <function>

1. 阅读函数。提取参数类型、返回类型和约束。
2. 运行边界情况生成器：

   uv run python skills/test-architect/scripts/edge-case-generator.py --name "<function_name>" --params "<param1:type,param2:type>"
   

3. 解析 JSON 输出。检查生成的类别：
   • 空值/空内容： None、""、[]、{}、0、False
   • 边界： int 最小值/最大值、float 极限、字符串长度限制
   • 类型强制转换： "123" 与 123、True 与 1、None 与 "null"
   • 溢出： 大数、深层嵌套、长字符串
   • Unicode： 表情符号、RTL 文本、零宽字符、组合标记
   • 并发： 竞态条件、死锁、过时读取
4. 针对每种边界情况，提供：输入值、预期行为、理由。
5. 标记当前代码可能无法通过的情况（缺少保护或验证）。

参考：阅读 references/edge-case-heuristics.md，了解类别详情。

模式 5：不稳定测试

/test-architect flaky

日志收集

1. 定位测试结果日志。搜索：
   • CI 日志、pytest 输出、jest 输出
   • .pytest_cache/、test-results/
   • 如果未找到，请向用户询问日志路径
2. 运行不稳定测试分析器：

   uv run python skills/test-architect/scripts/flaky-test-analyzer.py <log-path>
   

根因分类

3. 解析 JSON 输出。针对每个不稳定测试：
   • 失败次数与通过次数
   • 失败模式（时序、顺序、资源、状态）
   • 可能的根因分类：
     • 时序： 依赖 sleep/超时、竞态条件
     • 顺序： 依赖测试执行顺序
     • 资源： 外部服务、数据库、文件系统
     • 状态： 测试之间共享可变状态
     • 环境： 特定于平台、时区、区域设置
4. 根据根因建议修复策略。
5. 按失败频率和影响范围确定优先级。

参考：阅读 references/flaky-diagnosis.md，了解根因模式。

模式 6：审查

/test-architect review

1. 扫描测试套件。统计：测试文件数量、框架、目录结构。
2. 评估架构维度：
   • 测试金字塔平衡： 单元测试、集成测试与 e2e 测试的比例
   • 隔离性： 共享状态、全局固定装置、测试顺序依赖
   • 命名： 一致性、描述性、是否遵循约定
   • 覆盖率分布： 覆盖率是否均匀分布或集中于部分区域
   • 固定装置质量： 重复、复杂度、设置与拆卸的平衡
   • 断言质量： 具体断言与通用的 assertTrue
   • 速度： 找出运行缓慢的测试（单元测试 >1s，集成测试 >10s）
   • 确定性： 潜在的不稳定迹象
3. 如果存在覆盖率报告，则运行覆盖率分析器。
4. 与源代码交叉核对：
   • 未经测试的公共 API
   • 针对已删除/重命名代码的测试（孤立测试）
   • 缺失的负向测试用例
5. 输出：架构审计报告，包含各维度评分、发现和建议。

参考：阅读 references/test-suite-audit.md，了解评分标准。

参考文件

一次只加载一个参考文件。不要将所有参考文件预加载到上下文中。

文件	内容	读取时机
references/test-pyramid.md	测试金字塔各层、分布目标、反模式	模式 1（设计）
references/framework-patterns.md	pytest、jest、vitest 模式与约定	模式 2（生成）、模式 6（审查）
references/coverage-analysis.md	覆盖率报告解读、复杂度加权	模式 3（缺口）
references/edge-case-heuristics.md	按数据类型划分的边界情况类别、生成策略	模式 4（边界情况）
references/flaky-diagnosis.md	不稳定测试的根本原因、修复策略、预防模式	模式 5（不稳定测试）
references/test-suite-audit.md	测试架构评分标准、质量维度	模式 6（审查）
references/property-testing.md	使用 Hypothesis 和 fast-check 进行基于属性的测试	模式 1（设计）、模式 2（生成）
references/mutation-testing.md	变异测试计划设计、工具集成	模式 1（设计）、模式 6（审查）

脚本	运行时机
scripts/coverage-analyzer.py	模式 3（缺口）——解析覆盖率报告
scripts/edge-case-generator.py	模式 4（边界情况）——根据函数签名生成边界情况
scripts/flaky-test-analyzer.py	模式 5（不稳定测试）——解析测试日志以查找不稳定迹象

模板	渲染时机
templates/dashboard.html	模式 3（缺口）且有 10 个以上缺口时——覆盖率缺口可视化

关键规则

1. 绝不运行测试——仅进行设计和分析。可以建议命令，但不要执行。
2. 绝不修改源代码——测试架构仅提供建议，不负责实现。
3. 始终为每个测试用例建议正确的测试层级（单元测试／集成测试／端到端测试）。
4. 边界情况必须说明理由——解释「为什么这很重要」，不能只写「尝试此输入」。
5. 覆盖率缺口必须按风险排序，而非按代码行数排序。
6. 诊断不稳定测试时，必须先确定根本原因类别，再建议修复方法。
7. 框架建议必须与项目现有技术栈相符。
8. 仅在能够确定不变量时，才建议基于属性的测试。
9. 一次只加载一个参考文件——不要将所有参考文件预加载。
10. 每项发现都必须注明其适用的具体文件和函数。
11. 如果项目中已有测试模式，生成测试时必须遵循这些模式。
12. 只有在存在 10 个以上缺口时才渲染仪表板；缺口较少时不要渲染。