test-failure-investigator

测试失败调查员

用于系统化调查测试失败的运行手册式技能。给定一个失败的测试，确定根本原因并建议后续操作。

激活

/test-failure-investigator [test-name-or-file]

调查流程

步骤 1：对失败进行分类

运行测试 3 次并分类：

结果模式	分类	操作
持续失败	回归或环境问题	继续步骤 2
间歇性失败	不稳定测试	跳至步骤 4
现在通过	暂时性问题	检查 CI 日志和环境差异

# Run test 3 times
for i in 1 2 3; do npx jest {{test_file}} 2>&1 | tail -5; echo "--- Run $i ---"; done

步骤 2：缩小范围

# When did it start failing?
git log --oneline -20 -- {{related_source_files}}

# What changed recently?
git diff HEAD~5 -- {{related_source_files}}

# Does it fail in isolation?
npx jest {{test_file}} --testNamePattern="{{test_name}}"

# Does it fail with other tests?
npx jest --runInBand  # sequential execution

步骤 3：根本原因分析

症状	可能原因	调查方法
超时	网络／数据库依赖	检查外部服务是否可用
断言不匹配	逻辑变更	比较预期值与实际值，检查 git blame
导入错误	依赖变更	检查 package.json 变更，运行 npm ci
权限被拒绝	环境问题	检查文件权限和 Docker 卷
内存不足	资源泄漏	使用 --detectOpenHandles 进行分析

步骤 4：不稳定测试调查

# Run 10 times to confirm flakiness
for i in $(seq 1 10); do npx jest {{test_file}} --forceExit 2>&1 | grep -E 'PASS|FAIL'; done

# Common flaky causes:
# - Shared state between tests (missing cleanup)
# - Time-dependent assertions (use fake timers)
# - Race conditions (missing await)
# - Port conflicts (use random ports)
# - Order dependency (run with --randomize)

步骤 5：报告

## Test Failure Report
- **Test**: {{test_name}}
- **File**: {{test_file}}
- **Classification**: Regression / Flaky / Environment / Transient
- **Root Cause**: {{description}}
- **First Failed**: {{commit_hash}} ({{date}})
- **Fix**: {{recommended_action}}
- **Verified**: [ ] Fix applied and test passes 3x consecutively

组合使用

调查后，与以下技能组合使用：

• /bug-reporting-excellence — 如果发现回归，则提交错误报告
• /regression-testing — 如果发现回归，则将其加入回归测试套件
• /qe-test-execution — 修复后重新运行测试

注意事项

• Agent 可能会在未运行测试的情况下猜测根本原因——务必先复现问题
• “在我的机器上可以运行”不是诊断结果——比较环境（node 版本、操作系统、依赖项）
• 通过率为 9/10 的不稳定测试仍会被 CI 报告为“通过”——运行 10 次以上
• 测试隔离失败是不稳定测试的首要原因——检查 beforeAll/afterAll 中是否存在共享状态