Back to Details

test-architect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Test Architect

测试架构师

Design test strategies, analyze coverage gaps, identify edge cases, diagnose flaky tests, and audit test suite architecture.
Scope: Test design and analysis only. NOT for running tests or CI/CD (devops-engineer), code review (review), or TDD workflow.
设计测试策略、分析覆盖率缺口、识别边缘用例、诊断不稳定测试，并审核测试套件架构。
适用范围： 仅用于测试设计与分析。不适用于执行测试或CI/CD（devops-engineer）、代码评审（review）或TDD工作流。

Dispatch

命令调度

$ARGUMENTSAction
design <feature/module>
Design test strategy and pyramid for a feature or module
generate <file/function>
Generate test cases (strategy text or actual test code based on context)
gaps
Analyze coverage gaps from coverage reports
edge-cases <function>
Systematic edge case identification for a function
flaky
Diagnose flaky tests from logs and code
review
Audit test suite architecture
EmptyShow mode menu with examples
参数操作
design <feature/module>
为功能/模块设计测试策略和测试金字塔
generate <file/function>
生成测试用例（根据上下文生成策略文本或实际测试代码）
gaps
从覆盖率报告分析覆盖率缺口
edge-cases <function>
系统性识别函数的边缘用例
flaky
从日志和代码诊断不稳定测试
review
审核测试套件架构
无参数显示包含示例的模式菜单

Canonical Vocabulary

标准术语

Use these terms exactly throughout all modes:
TermDefinition
test pyramidLayered test distribution: unit (base), integration (middle), e2e (top)
coverage gapCode path with no test coverage, weighted by complexity risk
edge caseInput at boundary conditions, null/empty, type coercion, overflow, unicode, concurrent
flaky testTest with non-deterministic pass/fail behavior across identical runs
mutation scorePercentage of injected mutations detected by the test suite
test strategyDocument defining what to test, how, at what layer, with what tools
property-based testTest asserting invariants over generated inputs (Hypothesis/fast-check)
test isolationGuarantee that tests do not share mutable state or execution order dependencies
fixtureReusable test setup/teardown providing controlled state
test surfaceSet of public interfaces, code paths, and states requiring test coverage
所有模式中需严格使用以下术语：
术语定义
test pyramid分层测试分布：单元测试（底层）、集成测试（中层）、端到端测试（顶层）
coverage gap无测试覆盖的代码路径，按复杂度风险加权
edge case边界条件、空值/空输入、类型转换、溢出、Unicode、并发场景下的输入
flaky test在相同运行环境下结果不稳定（时而通过时而失败）的测试
mutation score测试套件检测到注入突变的百分比
test strategy定义测试对象、测试方式、测试层级及测试工具的文档
property-based test针对生成输入断言不变量的测试（Hypothesis/fast-check）
test isolation确保测试之间不共享可变状态或执行顺序依赖
fixture可复用的测试前置/后置操作，提供可控状态
test surface需要测试覆盖的公开接口、代码路径和状态集合

Mode 1: Design

模式1：设计

/test-architect design <feature/module>
/test-architect design <feature/module>

Surface Analysis

测试面分析

  1. Read the feature/module code. Map the test surface: public API, internal paths, state transitions, error conditions.
  2. Classify complexity: simple (pure functions), moderate (I/O, state), complex (distributed, concurrent, multi-service).
  1. 阅读功能/模块代码，梳理测试面：公开API、内部路径、状态转换、错误场景。
  2. 复杂度分类：简单（纯函数）、中等（I/O、状态相关）、复杂（分布式、并发、多服务）。

Pyramid Design

测试金字塔设计

  1. Design test pyramid:
    • Unit layer: Pure logic, transformations, validators. Target: 70-80% of tests.
    • Integration layer: Database, API, file I/O, service boundaries. Target: 15-25%.
    • E2E layer: Critical user flows only. Target: 5-10%.
  2. For each layer, list specific test cases with: description, input, expected output, rationale.
  3. Recommend framework and tooling based on language/ecosystem.
  4. Output: structured strategy document with pyramid diagram, case list, and priority order.
Reference: read references/test-pyramid.md for layer guidance.
  1. 设计测试金字塔：
    • 单元测试层： 纯逻辑、转换操作、验证器。目标占比：70-80%。
    • 集成测试层： 数据库、API、文件I/O、服务边界。目标占比：15-25%。
    • 端到端测试层： 仅覆盖关键用户流程。目标占比：5-10%。
  2. 为每个层级列出具体测试用例，包含：描述、输入、预期输出、设计理由。
  3. 根据语言/技术栈推荐框架和工具。
  4. 输出：包含金字塔示意图、用例列表及优先级排序的结构化策略文档。
参考：阅读references/test-pyramid.md获取层级指导。

Mode 2: Generate

模式2：生成

/test-architect generate <file/function>
  1. Read the target file/function. Identify signature, dependencies, side effects.
  2. Determine output format:
    • If test file exists for target: generate actual test code matching existing patterns.
    • If no test file exists: generate test strategy text with case descriptions.
    • If user specifies 
      --code
      : always generate test code.
  3. Generate test cases covering:
    • Happy path (expected inputs and outputs)
    • Error path (invalid inputs, exceptions, timeouts)
    • Edge cases (run edge-case-generator.py if function has typed parameters)
    • Boundary conditions (min/max values, empty collections, null)
  4. Follow framework conventions: read references/framework-patterns.md for pytest/jest/vitest patterns.
  5. Output: test cases or test code with clear section headers per category.
/test-architect generate <file/function>
  1. 读取目标文件/函数，识别签名、依赖项、副作用。
  2. 确定输出格式：
    • 若目标已有测试文件：生成匹配现有模式的实际测试代码。
    • 若目标无测试文件：生成包含用例描述的测试策略文本。
    • 若用户指定
      --code
      ：始终生成测试代码。
  3. 生成覆盖以下场景的测试用例：
    • 正常路径（预期输入与输出）
    • 错误路径（无效输入、异常、超时）
    • 边缘用例（若函数有类型化参数，运行edge-case-generator.py）
    • 边界条件（最小/最大值、空集合、空值）
  4. 遵循框架约定：阅读references/framework-patterns.md获取pytest/jest/vitest模式。
  5. 输出：按类别划分、带有清晰章节标题的测试用例或测试代码。

Mode 3: Gaps

模式3：覆盖率缺口

/test-architect gaps
  1. Locate coverage reports. Search for: 
    • coverage.json
      , 
      coverage.xml
      , 
      .coverage
      (Python/coverage.py)
    • lcov.info
      , 
      coverage/lcov.info
      (JS/lcov)
    • htmlcov/
      , 
      coverage/
      directories
  2. Run coverage analyzer: 
    uv run python skills/test-architect/scripts/coverage-analyzer.py <report-path>
  3. Parse JSON output. Rank gaps by complexity-weighted risk.
  4. For each gap, assess:
    • What code is untested and why it matters
    • Complexity score (cyclomatic complexity proxy)
    • Recommended test type (unit/integration/e2e)
    • Priority (P0: security/auth, P1: core logic, P2: utilities, P3: cosmetic)
  5. Render dashboard if 10+ gaps: 
    Copy templates/dashboard.html to a temporary file
Inject gap data JSON into <script id="data"> tag
Open in browser
  6. Output: prioritized gap list with recommended actions.
Reference: read references/coverage-analysis.md for interpretation guidance.
/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. 针对每个缺口评估：
    • 未测试的代码内容及其重要性
    • 复杂度得分（圈复杂度代理值）
    • 推荐测试类型（单元/集成/端到端）
    • 优先级（P0：安全/认证，P1：核心逻辑，P2：工具类，P3：界面美化）
  5. 若缺口数量≥10，生成可视化仪表盘： 
    将templates/dashboard.html复制到临时文件
将缺口数据JSON注入<script id="data">标签
在浏览器中打开
  6. 输出：带有推荐操作的优先级缺口列表。
参考：阅读references/coverage-analysis.md获取解读指导。

Mode 4: Edge Cases

模式4：边缘用例

/test-architect edge-cases <function>
  1. Read the function. Extract parameter types, return types, and constraints.
  2. Run edge case generator: 
    uv run python skills/test-architect/scripts/edge-case-generator.py --name "<function_name>" --params "<param1:type,param2:type>"
  3. Parse JSON output. Review generated categories:
    • Null/empty: None, "", [], {}, 0, False
    • Boundary: min/max int, float limits, string length limits
    • Type coercion: "123" vs 123, True vs 1, None vs "null"
    • Overflow: large numbers, deep nesting, long strings
    • Unicode: emoji, RTL text, zero-width chars, combining marks
    • Concurrent: race conditions, deadlocks, stale reads
  4. For each edge case, provide: input value, expected behavior, rationale.
  5. Flag cases where current code would likely fail (no guard, no validation).
Reference: read references/edge-case-heuristics.md for category details.
/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
    • 边界值： 整数最小/最大值、浮点数限制、字符串长度限制
    • 类型转换： "123" vs 123、True vs 1、None vs "null"
    • 溢出： 大数、深层嵌套、长字符串
    • Unicode： 表情符号、RTL文本、零宽字符、组合标记
    • 并发： 竞态条件、死锁、脏读
  4. 为每个边缘用例提供：输入值、预期行为、设计理由。
  5. 标记当前代码可能失败的场景（无防护、无验证）。
参考：阅读references/edge-case-heuristics.md获取类别详情。

Mode 5: Flaky

模式5：不稳定测试诊断

/test-architect flaky
/test-architect flaky

Log Collection

日志收集

  1. Locate test result logs. Search for:
    • CI logs, pytest output, jest output
    • .pytest_cache/
      , 
      test-results/
    • Ask user for log path if not found
  2. Run flaky test analyzer: 
    uv run python skills/test-architect/scripts/flaky-test-analyzer.py <log-path>
  1. 定位测试结果日志，搜索以下内容：
    • CI日志、pytest输出、jest输出
    • .pytest_cache/
      , 
      test-results/
      目录
    • 若未找到，询问用户日志路径
  2. 运行不稳定测试分析器： 
    uv run python skills/test-architect/scripts/flaky-test-analyzer.py <log-path>

Root Cause Classification

根因分类

  1. Parse JSON output. For each flaky test:
    • Failure count vs pass count
    • Failure pattern (timing, ordering, resource, state)
    • Likely root cause classification:
      • Timing: sleep/timeout dependencies, race conditions
      • Ordering: test execution order dependencies
      • Resource: external service, database, file system
      • State: shared mutable state between tests
      • Environment: platform-specific, timezone, locale
  2. Recommend fix strategy per root cause.
  3. Prioritize by failure frequency and blast radius.
Reference: read references/flaky-diagnosis.md for root cause patterns.
  1. 解析JSON输出，针对每个不稳定测试：
    • 失败次数vs通过次数
    • 失败模式（时序、执行顺序、资源、状态）
    • 可能的根因分类：
      • 时序问题： 依赖sleep/超时、竞态条件
      • 执行顺序问题： 测试执行顺序依赖
      • 资源问题： 外部服务、数据库、文件系统
      • 状态问题： 测试间共享可变状态
      • 环境问题： 平台特定、时区、区域设置
  2. 针对每个根因推荐修复策略。
  3. 按失败频率和影响范围排序优先级。
参考：阅读references/flaky-diagnosis.md获取根因模式。

Mode 6: Review

模式6：架构审核

/test-architect review
  1. Scan the test suite. Map: test file count, framework(s), directory structure.
  2. Assess architecture dimensions:
    • Pyramid balance: ratio of unit:integration:e2e tests
    • Isolation: shared state, global fixtures, test ordering dependencies
    • Naming: consistency, descriptiveness, convention adherence
    • Coverage distribution: even vs clustered coverage
    • Fixture health: duplication, complexity, setup/teardown balance
    • Assertion quality: specific assertions vs generic assertTrue
    • Speed: identify slow tests (>1s unit, >10s integration)
    • Determinism: potential flakiness indicators
  3. Run coverage analyzer if reports exist.
  4. Cross-reference with source code:
    • Untested public APIs
    • Tests for deleted/renamed code (orphaned tests)
    • Missing negative test cases
  5. Output: architecture audit report with scores per dimension, findings, and recommendations.
Reference: read references/test-suite-audit.md for scoring criteria.
/test-architect review
  1. 扫描测试套件，梳理：测试文件数量、框架、目录结构。
  2. 评估架构维度：
    • 金字塔平衡： 单元:集成:端到端测试的比例
    • 隔离性： 共享状态、全局fixture、测试执行顺序依赖
    • 命名规范： 一致性、描述性、约定遵循度
    • 覆盖率分布： 均匀覆盖vs集中覆盖
    • Fixture健康度： 重复度、复杂度、前置/后置操作平衡
    • 断言质量： 特定断言vs通用assertTrue
    • 速度： 识别慢测试（单元测试>1s，集成测试>10s）
    • 确定性： 潜在不稳定测试指标
  3. 若存在覆盖率报告，运行覆盖率分析器。
  4. 与源代码交叉验证：
    • 未测试的公开API
    • 针对已删除/重命名代码的测试（孤立测试）
    • 缺失的负向测试用例
  5. 输出：包含各维度得分、发现问题及改进建议的架构审核报告。
参考：阅读references/test-suite-audit.md获取评分标准。

Reference Files

参考文件

Load ONE reference at a time. Do not preload all references into context.
FileContentRead When
references/test-pyramid.mdTest pyramid layers, distribution targets, anti-patternsMode 1 (Design)
references/framework-patterns.mdpytest, jest, vitest patterns and conventionsMode 2 (Generate), Mode 6 (Review)
references/coverage-analysis.mdCoverage report interpretation, complexity weightingMode 3 (Gaps)
references/edge-case-heuristics.mdEdge case categories by data type, generation strategiesMode 4 (Edge Cases)
references/flaky-diagnosis.mdFlaky test root causes, fix strategies, prevention patternsMode 5 (Flaky)
references/test-suite-audit.mdTest architecture scoring rubric, quality dimensionsMode 6 (Review)
references/property-testing.mdProperty-based testing with Hypothesis and fast-checkMode 1 (Design), Mode 2 (Generate)
references/mutation-testing.mdMutation testing plan design, tool integrationMode 1 (Design), Mode 6 (Review)
ScriptWhen to Run
scripts/coverage-analyzer.pyMode 3 (Gaps) -- parse coverage reports
scripts/edge-case-generator.pyMode 4 (Edge Cases) -- generate edge cases from function signature
scripts/flaky-test-analyzer.pyMode 5 (Flaky) -- parse test logs for flaky indicators
TemplateWhen to Render
templates/dashboard.htmlMode 3 (Gaps) with 10+ gaps -- coverage gap visualization
每次仅加载一个参考文件，不要预加载所有参考文件到上下文。
文件内容读取时机
references/test-pyramid.md测试金字塔层级、分布目标、反模式模式1（设计）
references/framework-patterns.mdpytest、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个时 -- 覆盖率缺口可视化

Critical Rules

核心规则

  1. Never run tests -- design and analyze only. Suggest commands but do not execute.
  2. Never modify source code -- test architecture is advisory, not implementation.
  3. Always recommend the correct test layer (unit/integration/e2e) for each test case.
  4. Edge cases must include rationale -- "why this matters" not just "try this input."
  5. Coverage gaps must be prioritized by risk, not by line count.
  6. Flaky test diagnosis must identify root cause category before recommending fixes.
  7. Framework recommendations must match the project's existing stack.
  8. Property-based testing is recommended only when invariants are identifiable.
  9. Load ONE reference file at a time -- do not preload all references.
  10. Every finding must cite the specific file and function it applies to.
  11. Test generation must follow existing test patterns in the project when present.
  12. Dashboard rendering requires 10+ gaps -- do not render for small gap sets.
  1. 绝不执行测试 -- 仅做设计与分析。可建议命令但不要执行。
  2. 绝不修改源代码 -- 测试架构仅提供建议，不负责实现。
  3. 始终为每个测试用例推荐正确的测试层级（单元/集成/端到端）。
  4. 边缘用例必须包含理由 -- 不仅要说明“尝试此输入”，还要说明“为何重要”。
  5. 覆盖率缺口必须按风险优先级排序，而非按代码行数。
  6. 不稳定测试诊断必须先确定根因类别，再推荐修复方案。
  7. 框架推荐必须匹配项目现有技术栈。
  8. 仅当可识别不变量时，才推荐属性测试。
  9. 每次仅加载一个参考文件 -- 不要预加载所有参考文件。
  10. 每个发现必须注明对应的具体文件和函数。
  11. 测试生成必须遵循项目中已有的测试模式（若存在）。
  12. 仅当缺口≥10个时才渲染仪表盘 -- 缺口数量较少时不渲染。