flakiness-knowledge-graph-mcp

📊 flakiness-knowledge-graph-mcp

一个 Playwright 自定义报告器和 MCP 服务，可根据测试运行历史构建本地不稳定性知识图谱。询问 AI Agent 哪些测试不可靠、在哪种浏览器上不可靠，以及情况是否正在恶化。

🤔 问题

单条 Playwright 跟踪记录只能告诉你当前_发生了什么_失败。它不会告诉你这个测试是否已经悄悄地不稳定了两周、是否只在 CI 中的 Firefox 上失败，或者是否每次发布后都变得更慢。

此工具会将运行历史累积到 SQLite 数据库中，并通过 MCP 将其提供给 AI Agent，从而解决这个问题。

🛠️ 工具

工具	参数	返回内容
get_flaky_tests	db_path、min_runs?、limit?、since_days?	按不稳定率（失败 + 不稳定 / 总运行次数）排名的测试
get_test_history	db_path、test_id、limit?	特定测试的完整运行历史记录——状态、耗时、错误、重试、浏览器、操作系统
get_failure_patterns	db_path、since_days?	按浏览器 × 操作系统组合细分的失败率
get_slow_tests	db_path、limit?	按平均耗时排名的测试
get_error_groups	db_path、min_failures?、limit?、since_days?	按精确错误前缀聚类的失败——揭示多个测试之间共同的根本原因
get_flakiness_trend	db_path、test_id、days?	过去 N 天的每日不稳定率——显示测试是否正在变得更糟
cluster_semantic_error_trees	db_path、min_instances?、since_days?	类似 get_error_groups，但会先规范化动态值（UUID、ID、URL），再使用 Levenshtein 距离进行模糊合并
correlate_git_commit_flakiness	db_path、min_stable_runs?、since_days?	找出测试从稳定转为不稳定（或反向转换）时的确切提交 SHA，并提供分支和作者信息

🚀 设置

1. 安装

npm install -g flakiness-knowledge-graph-mcp

或者从源代码构建：

git clone https://github.com/vola-trebla/flakiness-knowledge-graph-mcp.git
cd flakiness-knowledge-graph-mcp
npm install && npm run build

2. 将报告器添加到 Playwright 项目

// playwright.config.ts
export default defineConfig({
  reporter: [["html"], ["flakiness-knowledge-graph-mcp/reporter", { dbPath: "./flakiness.db" }]],
});

照常运行测试——报告器会自动将每个结果写入 flakiness.db。

3. 将 MCP 服务添加到编辑器

Cursor / VS Code（.cursor/mcp.json 或 .vscode/mcp.json）

{
  "mcpServers": {
    "flakiness-knowledge-graph": {
      "command": "flakiness-knowledge-graph-mcp"
    }
  }
}

Claude Code

claude mcp add flakiness-knowledge-graph flakiness-knowledge-graph-mcp

4. 使用演示数据进行试用

还没有 Playwright 项目？生成 30 天的逼真示例数据：

npx flakiness-graph-seed ./demo.db

然后让 AI Agent 使用 ./demo.db，即可探索全部 8 个工具。

💬 使用示例

I've been running my Playwright suite for two weeks. The DB is at /my-project/flakiness.db.

1. get_flaky_tests — which tests are most unreliable? Show last 7 days only.
2. get_test_history for the top flaky test — is it getting worse?
3. get_flakiness_trend for the same test over 14 days — plot the daily rate.
4. get_failure_patterns — does it only fail on a specific browser or OS?
5. cluster_semantic_error_trees — are multiple tests failing with semantically identical errors?
6. correlate_git_commit_flakiness — which commit introduced the flakiness?
7. get_slow_tests — which tests should I optimize for CI speed?

将看似不同、实则相同的错误分组

get_error_groups 按原始字符串前缀聚类——如果错误中包含 UUID 或元素 ID，就会把实际上由同一个根本原因引起的错误分成多个组。cluster_semantic_error_trees 会先剥离动态值：

{
  "total_clusters": 2,
  "clusters": [
    {
      "cluster_id": "cluster-1",
      "canonical_message": "TimeoutError: locator.click: Timeout 30000ms exceeded\n  waiting for locator('#submit-btn')",
      "normalized_message": "TimeoutError: locator.click: Timeout <num>ms exceeded waiting for locator",
      "error_taxonomy": "TimeoutError",
      "instance_count": 14,
      "affected_tests": 3,
      "sample_test_ids": ["checkout > submit order", "cart > add item", "checkout > apply coupon"]
    },
    {
      "cluster_id": "cluster-2",
      "canonical_message": "Error: 2 requests to https://api.example.com/orders/8f3a1c were made. Expected 1",
      "normalized_message": "Error: <num> requests to <url> were made. Expected <num>",
      "error_taxonomy": "AssertionError",
      "instance_count": 6,
      "affected_tests": 1,
      "sample_test_ids": ["api-mock > intercept order"]
    }
  ]
}

查找导致测试失败的提交

correlate_git_commit_flakiness 使用状态机——它会查找测试连续通过 ≥3 次且保持稳定，随后失败的运行记录。状态转换记录包含来自 CI 环境的 SHA：

{
  "total_transitions": 1,
  "transitions": [
    {
      "test_id": "auth > login > should redirect after login",
      "title": "should redirect after login",
      "transition_type": "stable_to_flaky",
      "git_commit_sha": "a3f8c1d9e2b54f6a",
      "git_branch": "main",
      "git_author": "dev-handle",
      "transition_date": "2025-04-14"
    }
  ]
}

reporter 会自动读取 GITHUB_SHA / CI_COMMIT_SHA / CIRCLE_SHA1 / GIT_COMMIT——升级到 v0.2.0 即可，无需更改 reporter 配置。

🔗 与 playwright-trace-decoder-mcp 搭配使用效果更佳

这两个 MCP 服务旨在相互补充：

• flakiness-knowledge-graph-mcp 回答“这个测试过去是否不稳定？是哪个提交导致的？”
• playwright-trace-decoder-mcp 回答“这次运行具体出了什么问题？”

结合使用后，AI Agent 无需打开任何文件，就能诊断 CI 失败是由已知的不稳定测试还是新回归导致的。

⚖️ 并行执行与 CI 分片

flakiness-knowledge-graph-mcp 使用进程内写入队列，确保单个 Node 进程中的并行 Playwright 工作进程不会损坏数据库。

但是，如果你在多个独立进程中运行测试（例如并行 CI 分片或独立的机器运行器），并让它们写入同一个共享网络文件：

1. 竞态条件： 如果没有操作系统级锁定，标准文件系统无法保证跨进程对 SQLite 文件执行原子写入。
2. 建议做法： 每个 CI 分片都应写入自己的数据库文件（例如 flakiness-shard-1.db、flakiness-shard-2.db）。
3. 合并： CI 流水线结束时，你可以使用标准 SQLite 工具合并这些文件，或运行脚本从一个文件读取并插入到另一个文件中，合并成单个主数据库。

对于本地开发或单机 CI 运行，默认配置是安全的。

🏗️ 架构

playwright.config.ts
  └── FlakinessReporter → flakiness.db (SQLite via sql.js)

flakiness.db
  └── test_runs table
        id, test_id, title, suite, file,
        status, duration_ms, browser, os,
        timestamp, error, retry,
        git_commit_sha, git_branch, git_author   ← added in v0.2.0

MCP server
  └── reads flakiness.db on demand (in-process handle reuse)

使用 sql.js 而非 better-sqlite3——它是编译为 WebAssembly 的纯 JavaScript SQLite，无需原生编译。首次使用时会通过 ALTER TABLE 迁移添加 git 列——现有数据库会自动升级。

📋 脚本

npm run build        # compile TypeScript → dist/
npm run lint         # ESLint
npm run format       # Prettier --write
npm run format:check # Prettier check (used in CI)
npm run seed         # populate flakiness.db with 30 days of demo data

📄 许可证

MIT