test-genie

test-genie-mcp

专为氛围编程者打造：运行一条命令，即可获取项目实际问题的优先级列表。

面向 iOS、Android、Flutter、React Native 和 Web 应用的自愈式测试自动化——以 MCP 服务的形式提供。

v3.1.1 — 氛围检查 + 诚实的自动修复。 一次 MCP 调用，约 30 秒：按优先级列出竞态条件、安全问题、内存泄漏、逻辑错误和性能隐患。所有操作都在你的设备上进行，不收集遥测数据。设置 autoFix: true 可应用小型、安全的机械式修复（弱哈希、简单的 Math.random 赋值）——先备份，再进行语法验证，语法验证失败时回滚。若要通过测试验证更复杂的修复，请使用 v3.0.0 的迭代修复循环。

---

氛围编程者快速入门

你不看文档。你打开项目，和 Claude 对话，然后想要一个结论。答案就在这里：

在 Claude 中（已安装 test-genie-mcp — 设置）：

/vibe-check /Users/me/my-app

Claude 会在底层调用 diagnose_project。约 30 秒后，你会看到：

# vibe-check report

- Project: /Users/me/my-app
- Platform: web
- Findings: 11 total — 4 critical, 4 high, 1 medium, 1 low
- Estimated fix time: ~85 min

## Top 5 issues

### 1. [CRIT] Hardcoded AWS access key id found in source
- File: `server.js:7`
- Category: security / secret (CWE-798)
- Confidence: 95%
- Fix: Move the value to an env var, gitignore the config, rotate the leaked key.

### 2. [CRIT] SQL string built by concatenating user input
- File: `server.js:21`
- Category: security / injection (CWE-89)
- Fix: Use parameterized queries (`db.query("... WHERE id = ?", [id])`).

### 3. [HIGH] useState setter called after await without mount guard
- File: `UserProfile.tsx:16`
- Category: race-condition / react-setstate-after-await (CWE-362)
- Confidence: 78%
- Fix: Use AbortController and check signal.aborted before calling setters.

… (top 5 shown — full list at output: "detailed")

## Next steps
1. Address the critical / high findings above.
2. Re-run diagnose_project after fixing to confirm convergence.
3. Use run_iterative_fix_loop for test-driven verification of each fix.

如果某个发现的 autoFixable: true 且严重级别为 high/critical，diagnose_project 调用可接受 autoFix: true，直接应用机械式替换（包括备份和语法验证——具体防护措施见 SAFETY.md）。v3.1.1 诚实限定了适用范围：弱哈希（createHash('md5'|'sha1') → createHash('sha256')）以及安全敏感文件中的独立 Math.random()。要进行范围更广或涉及结构的修复（竞态条件、eval、exec 注入），请单独运行 run_iterative_fix_loop——它会重新运行测试，并在出现回归时自动回滚。

---

为什么选择 test-genie？

移动端和跨平台测试自动化的瓶颈不在于编写测试，而在于失败测试与通过测试之间的循环。test-genie 补上了这个循环：

failing test → analyzer flags issue → fix proposed → dry-run + syntax check →
applied with backup → affected tests re-run → regression check → loop or stop

这个完整循环由 run_iterative_fix_loop 工具实现。v3.1.1 中的 diagnose_project autoFix: true 路径只涵盖其中严格限定的一部分——备份 + 试运行 + 语法验证 + 应用，不会重新运行测试（因此该路径不会因测试回归而回滚）。根据任务选择合适的工具——各工具的具体防护措施见 SAFETY.md。

其他工具（Detox、Maestro、Playwright、xcodebuild test）会运行测试。test-genie 既运行测试，又会持续推动修复，直到达到标准或无法继续取得进展——你不必自己翻查堆栈跟踪。

---

5 分钟快速入门

# 1. Install
npm install -g test-genie-mcp

# 2. Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json)
{
  "mcpServers": {
    "test-genie": {
      "command": "npx",
      "args": ["test-genie-mcp"],
      "env": {
        "TEST_GENIE_ALLOWED_ROOT": "/path/to/your/project"
      }
    }
  }
}

# 3. Restart Claude Desktop. From a chat:
#    "Run the iterate-fix loop on /Users/me/my-rn-app with autoApply=false"

预期输出（已截断）：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Iterative fix loop f8b3… — PAUSED-FOR-CONFIRMATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Iterations completed: 1
Fixes applied:        0
Regressions rolled back: 0
Final tests:          7/10 passing (3 failing)

Pending confirmations (3):
  - 71fbe…: Fix: useEffect missing cleanup for setInterval (confidence: 85)
  - 92ad1…: Fix: Force-unwrap on possibly-undefined name (confidence: 85)
  - …

Resume token: f8b3…

使用 autoApply: true（或 resumeToken: "f8b3…"）再次调用，即可实际修补文件。

---

实际用例

以下流程介绍的是 run_iterative_fix_loop 路径（v3.0 的主要亮点）——完整流程包括检测 → 提议 → 试运行 → 备份后应用 → 重新运行测试 → 出现回归时回滚。v3.1.1 中的 diagnose_project autoFix 路径范围更窄，仅支持机械式替换；具体会修改哪些内容，请参见 SAFETY.md §4。

1. React Native 内存泄漏自愈

某团队在 useEffect 中添加了 setInterval(...)，却忘记清理。test-genie 的 detect_memory_leaks 会标记这个问题，suggest_fixes 会提议添加 return () => clearInterval(id)（src/tools/fixing/suggestFixes.ts:169-179）；随后循环会通过 TS 编译器试运行补丁、备份后应用补丁，仅重新运行受影响的快照测试，确认 100% 通过后停止。修复前： 1 个快照测试失败。修复后： 0 个测试失败，已应用 1 项修复，并在 .test-genie-backups/ 中保存 1 份备份。

2. Flutter widget dispose() 自动化

AnimationController 未调用 dispose() 释放。test-genie 发现缺少 dispose() 重写，生成 Dart @override dispose() { controller.dispose(); super.dispose(); } 代码块（suggestFixes.ts:214-217），在修补后的文件上运行 dart analyze，应用修复，再次运行 flutter test，最终收敛。

3. iOS 保留环（闭包捕获）

self.timer = Timer.scheduledTimer(...) { _ in self.tick() } —— 基于规则的检测器会标记闭包捕获 self，修复器将其改写为 [weak self] _ in guard let self = self else { return }; self.tick()（suggestFixes.ts:239-242）。如果 PATH 中有 swiftc，就会进行真实的语法检查；否则，test-genie 会报告“验证已降级”，以便你知悉。

---

迭代修复循环的工作原理

┌────────────────────┐
│   collect tests    │  (run_scenario_test / supplied list)
└─────────┬──────────┘
          │
   pass-rate ≥ threshold? ── yes ──▶  SUCCESS
          │ no
          ▼
┌────────────────────┐
│  detect issues     │   memory + logic analyzers
└─────────┬──────────┘
          │
┌────────────────────┐
│  suggest fixes     │   rule-based (default) → LLM (hybrid, optional)
└─────────┬──────────┘
          │
┌────────────────────┐
│  dry-run + syntax  │   TS compiler API / platform compiler / brace check
└─────────┬──────────┘
          │
┌────────────────────┐
│  apply with backup │   per-file `.test-genie-backups/`
└─────────┬──────────┘
          │
┌────────────────────┐
│  re-run tests      │   regression?  yes → auto-rollback
└─────────┬──────────┘
          │
          ▼
   loop (≤ maxIterations, ≤ totalTimeout)

请参阅 docs/ITERATE_FIX_LOOP.md，了解时序图和完整的安全防护列表。

---

工具（23 个）

#	工具	模式
1	analyze_app_structure	真实
2	generate_scenarios	真实
3	create_test_plan	真实
4	run_scenario_test	混合
5	run_simulation	模拟
6	run_stress_test	混合
7	detect_memory_leaks	真实
8	detect_logic_errors	真实
9	suggest_fixes	真实
10	confirm_fix	真实
11	apply_fix	真实
12	rollback_fix	真实
13	run_full_automation	混合
14	run_iterative_fix_loop（v3.0 重点）	混合
15	generate_report	真实
16	get_pending_fixes	真实
17	get_test_history	真实
18	analyze_performance	真实
19	analyze_code_deep	真实
20	generate_cicd_config	真实
21	diagnose_project（v3.1 重点——氛围检查）	真实
22	detect_race_conditions	真实
23	detect_security_issues	真实

docs/SIMULATION_VS_REAL.md 中说明了 mode 的含义。

另外还有 4 个资源（test-genie://iteration-logs、…/test-history/{path}、…/iteration-logs/{loopId}、…/applied-fixes/{path}）和 3 个提示词（full-test-pipeline、diagnose-failure、vibe-check）。

---

vibe-check 可检测的内容

竞态条件（detect_race_conditions / diagnose_project）：

模式	语言	严重级别	可自动修复（v3.1.1）
useState setter 在 await 后调用，且没有挂载保护	TS/JS/React	高	否（结构性）
useEffect 中执行异步 fetch，且没有 AbortController/清理逻辑	TS/JS/React	高	否（结构性）
arr.forEach(async ...)（静默地启动异步任务后不等待）	TS/JS	中	否（对执行顺序敏感）
相邻的 fetch 未使用 Promise.all / 串行处理	TS/JS	中	否
TOCTOU：调用 existsSync 后调用 readFileSync，且没有锁	TS/JS Node	中	否
异步上下文中的非原子计数器递增	TS/JS	低	否
在 @MainActor 之外修改 @Published	Swift	中	否
并发 DispatchQueue 写入时没有 .barrier	Swift	中	否
在 Dispatchers.Main 之外修改 MutableStateFlow	Kotlin	中	否
收集 Flow 时未使用 flowOn	Kotlin	低	否
Goroutine 与共享 map 配合使用时没有 sync.Mutex	Go	高	否

v3.1.1 诚实性审查：此前曾宣称 useEffect-no-abort 和 forEach-await 可自动修复，但实际并非如此——添加 AbortController，或改写为 Promise.all(arr.map(...))，都会改变我们无法通过静态分析验证的行为。现在它们仅生成报告。请参阅 SAFETY.md。

安全问题（detect_security_issues / diagnose_project）：

模式	严重级别	CWE	可自动修复（v3.1.1）
硬编码的 AWS / Stripe / GitHub / Google / Slack 令牌	严重 / 高	CWE-798	否（需轮换）
硬编码的 JWT 密钥字面量	高	CWE-798	否
URL 查询字符串中的 API 令牌	高	CWE-200	否
存在 .env 文件，但未加入 gitignore	高	CWE-538	否（必须先轮换）
使用 req.params / req.body 拼接 SQL 字符串	严重	CWE-89	否
使用动态值的 innerHTML / dangerouslySetInnerHTML	高	CWE-79	否
使用非字面量参数的 eval() / new Function()	严重	CWE-95	否
安全敏感文件中的 Math.random()，独立赋值	高	CWE-338	是（crypto.randomInt）
混入算术运算的 Math.random()	高	CWE-338	否（语义原因）
安全关键词文件中的 createHash('md5'|'sha1')	高	CWE-327	是（'sha256'）
其他位置的 createHash('md5'|'sha1')	中	CWE-327	否（低于严重级别下限）
使用用户输入模板字面量的 child_process.exec	严重	CWE-78	否
fetch(req.query.url)（SSRF）	高	CWE-918	否
CORS 来源设为 * 且 Allow-Credentials: true	高	CWE-942	否
设置 Cookie 时未使用 httpOnly / secure / sameSite	低	CWE-1004	否
调用 yaml.load 时未使用安全 schema	中	CWE-502	否

v3.1.1 诚实性审查：此前曾宣称 .env/Math.random（一般情况）/yaml.load 可自动修复。但盲目改写风险过高，或者尚未提供相应策略，因此已改为仅生成报告。请参阅 SAFETY.md §5。

---

vibe-check 的不足之处（如实列举）

这是一个「30 秒内捕捉明显问题」的筛查工具，不是 Snyk、Semgrep 或完整的 SAST 工具。它无法捕捉：

• 跨文件数据流。 如果用户输入经过三个文件后才到达 db.query，正则表达式无法串联这些信息。真正的 SAST 会沿调用图追踪污点。路线图：使用 ts-morph 遍历引用，覆盖排名靠前的入口点。
• 存在漏洞的传递依赖。 我们不会查询 npm 公告——那是 npm audit 的工作，而打包一份过时的公告列表会误导用户。如果需要覆盖依赖项中的 CVE，可以并行运行 npm audit --json。
• 跨进程竞态条件。 我们能捕捉进程内的 JS / Swift / Kotlin / Go 竞态。分布式竞态（服务间的锁排序、DB 事务）需要使用其他工具。
• 类型正确但逻辑错误的代码。 分析器基于语法，而非语义。Math.random() 即使命名为 getNonce 也骗不过我们；但命名恰当的 crypto.randomBytes 若使用的熵预算过小，就能骗过我们。
• 自定义密钥格式。 带有独特前缀的公司内部令牌需要添加正则表达式，你可以将其加入 securityAnalyzer.SECRET_PATTERNS。欢迎提交 PR。
• 实时 / 动态问题。 负载下的内存泄漏、网络超时、交互过程中的渲染缓慢——这些需要使用 run_stress_test / run_simulation，而非静态分析。

如果你想在 vibe-check 的基础上获得更深入的覆盖，可以将发现的问题交给 run_iterative_fix_loop，以通过测试验证的方式进行修复；也可以针对合规场景升级使用 Snyk / Semgrep / GitHub Advanced Security。

---

vibe-check 与其他工具的比较

	vibe-check (test-genie)	Snyk	Semgrep	GitHub Advanced Security
在本地运行	是	混合（云端）	是	否（云端）
无遥测	是（零网络调用）	否	部分	否
集成修复循环	是（run_iterative_fix_loop）	否	否	否
竞态条件检测	是（JS/Swift/Kotlin/Go）	否	部分	部分
跨文件污点流	否（路线图）	是	是	是
设置时间	无（安装 test-genie 后即已安装）	账户 + 身份验证	安装 + 规则集	在仓库级别启用

如果你的目标是「提交之前，看看有什么问题？」，vibe-check 的延迟更低。如果你的目标是「合规 + 供应链审计」，请使用专用工具。

---

不要使用 test-genie 的情况

• 生产环境的门禁测试运行。 test-genie 专为开发反馈循环而构建。对于发布决策，请使用由你端到端掌控的正规 CI。
• 团队必须逐行人工审查的代码。 该循环的工作是提出并应用修复；如果每项修复都需要人工检查，请保留 autoApply: false（默认值），仅将其用作修复建议生成器。
• 没有备份 / 没有版本控制的情况。 test-genie 的自动回滚尽力而为，并且需要存在对应文件的备份。务必在 git 工作树中运行。

---

对比

	test-genie	Detox	Maestro	xcodebuild test
运行 E2E / 单元测试	✅（通过 Jest/Detox 等）	✅	✅	✅
检测代码问题	✅ 规则 + LLM	❌	❌	❌
迭代修复循环	✅ (run_iterative_fix_loop)	❌	❌	❌
测试回归时自动回滚	✅ 仅在 run_iterative_fix_loop 中	❌	❌	❌
语法检查失败时自动回滚	✅ 所有应用路径	❌	❌	❌
原生支持 MCP（可与 Claude / Agent 对话）	✅	❌	❌	❌
多平台	iOS+Android+Web+Flutter+RN	iOS+Android	iOS+Android	仅 iOS

范围说明：diagnose_project autoFix: true 会在语法验证失败时回滚 (applyFix.ts:185-202)，但不会重新运行测试，因此无法检测测试回归。要使用基于测试的回滚，请用 run_iterative_fix_loop。参见 SAFETY.md §2.4。

test-genie 会在底层使用 Jest、Detox 和 xcodebuild test 等工具——它位于编排层，而非测试运行器层。

---

已知限制

• 平台语法检查降级。 对于 Swift/Kotlin/Java/Dart，我们会尝试使用平台编译器的 -typecheck 模式。如果编译器不在 PATH 中，则会回退到大括号匹配验证，并在结果中显示 downgraded: true。安装 swiftc / kotlinc / javac / dart 以进行实际验证。
• LLM 可选且受条件限制。 只有当基于规则的置信度低于阈值时，strategy: 'hybrid' 才会启用 LLM。没有 API 密钥时，循环仅使用基于规则的方式——不会失败。
• 存储仅限单机。 测试历史记录 / 迭代日志保存在 $TEST_GENIE_STORAGE_DIR 下（默认为 ~/.test-genie-mcp），不会在不同机器间同步。
• 模拟模式是“模拟”，不是魔法。 run_simulation 返回的是看似合理的异常，而非真实异常。需要在真实设备上运行时，请使用 run_scenario_test（混合模式）。

---

配置

环境变量	默认值	用途
TEST_GENIE_ALLOWED_ROOT	cwd	基于能力的路径安全机制——服务拒绝在此根目录之外进行读写。
TEST_GENIE_STORAGE_DIR	~/.test-genie-mcp	场景 / 结果 / 迭代日志的存放位置。
TEST_GENIE_LLM_PROVIDER	自动检测	anthropic / openai / none。
ANTHROPIC_API_KEY	—	当 provider = anthropic 时使用。
OPENAI_API_KEY	—	当 provider = openai 时使用。
TEST_GENIE_ANTHROPIC_MODEL	claude-haiku-4-5	覆盖 Anthropic 模型。
TEST_GENIE_OPENAI_MODEL	gpt-4o-mini	覆盖 OpenAI 模型。

---

从 v2.x 迁移

• run_full_automation 仍可使用。为保持兼容，保留了 confirmMode / autoFix 选项，但新方式是 autoApply: boolean——autoApply: true 等同于 confirmMode: 'auto'。
• 子进程加固意味着平台工具现在会拒绝包含 shell 元字符的 scheme / device / package-name 参数。如果你的 CI 传入了看起来异常的值，请先进行清理。
• 完整的破坏性变更列表和迁移指南请参见 CHANGELOG.md。

---

路线图

• 基于 LLM 的修复提案投票（多个提案 → 根据语法 + 重测结果差值选出最佳提案）
• 多仓库同步（通过一次 MCP 调用并行运行 N 个仓库的循环）
• 文件保存时运行循环的“监视模式”
• 改进 Detox / Maestro 工件的导入（将视频链接到迭代日志中）

---

参与贡献

欢迎提交问题、PR 和想法——请参见 CONTRIBUTING.md（TODO）。代码位于 src/ 下，测试位于 tests/ 下。提交 PR 前请运行 npm test。

维护者

@MUSE-CODE-SPACE — Yoonkyoung Gong。

许可证

MIT — 参见 LICENSE。