flakiness-knowledge-graph-mcp

📊 flakiness-knowledge-graph-mcp

Playwright のカスタムレポーターと MCP サーバーです。テスト実行履歴からローカルの不安定性ナレッジグラフを構築します。どのテストが不安定か、どのブラウザーで発生するか、悪化しているかどうかを AI エージェントに尋ねられます。

🤔 問題

1 回の Playwright トレースで分かるのは、今何が失敗したかです。このテストが 2 週間にわたって気づかれずに不安定な状態なのか、CI の Firefox でのみ失敗するのか、リリースのたびに遅くなっているのかは分かりません。

このツールは、実行履歴を SQLite データベースに蓄積し、MCP 経由で AI エージェントに公開することで、この問題を解決します。

🛠️ ツール

ツール	引数	返される内容
get_flaky_tests	db_path, min_runs?, limit?, since_days?	不安定率（失敗＋不安定 / 総実行回数）で順位付けされたテスト
get_test_history	db_path, test_id, limit?	特定のテストの全実行履歴 — ステータス、実行時間、エラー、再試行、ブラウザー、OS
get_failure_patterns	db_path, since_days?	ブラウザー × OS の組み合わせ別に分類された失敗率
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）を正規化してから、レーベンシュタイン距離であいまいに統合します
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 エージェントから./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"
    }
  ]
}

レポーターは GITHUB_SHA / CI_COMMIT_SHA / CIRCLE_SHA1 / GIT_COMMIT を自動的に読み取るため、v0.2.0 にアップグレードする以外にレポーターの設定を変更する必要はありません。

🔗 playwright-trace-decoder-mcp との優れた連携

この2つの MCP サーバーは、互いを補完するように設計されています：

• flakiness-knowledge-graph-mcp は「このテストは過去にも不安定だったか、また、どのコミットが原因か？」に答えます
• playwright-trace-decoder-mcp は「今回の実行で具体的に何が失敗したのか？」に答えます

組み合わせることで、AI エージェントはファイルを1つも開かずに、CI の失敗が既知の不安定なテストによるものか、新たなリグレッションによるものかを診断できます。

⚖️ 並列実行と CI のシャーディング

flakiness-knowledge-graph-mcp はプロセス内の書き込みキューを使用し、単一の Node プロセス内で Playwright のワーカーを並列実行しても、データベースが破損しないようにします。

ただし、複数の独立したプロセス（並列 CI シャードや別々のマシン上のランナーなど）でテストを実行し、同じ共有ネットワークファイルに書き込む場合は、次の点に注意してください：

1. 競合状態： OS レベルのロックがない場合、標準的なファイルシステムでは、プロセス間で SQLite ファイルへの書き込みがアトミックに行われる保証はありません。
2. 推奨される方法： 各 CI シャードは、それぞれ独自のデータベースファイル（例：flakiness-shard-1.db、flakiness-shard-2.db）に書き込むようにしてください。
3. マージ： CI パイプラインの最後に、標準的な SQLite ツールを使用するか、一方のファイルから読み取って他方に挿入するスクリプトを実行して、これらのファイルを1つのマスターデータベースにマージできます。

ローカル開発や単一マシンでの 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)

better-sqlite3 の代わりに sql.js を使用しています。これは WebAssembly にコンパイルされた純粋な JavaScript の SQLite であり、ネイティブコンパイルは不要です。Git の列は初回使用時に ALTER TABLE によるマイグレーションで追加され、既存のデータベースも自動的にアップグレードされます。

📋 スクリプト

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