flakyguard

flakyguard

「そのテストは不安定です」というのは、たいてい感覚にすぎません。flakyguard はそれを根拠に変えます。CI の複数の実行からテストごとの結果を渡すと、各テストについて次の記録を作成します。

• テストごとの履歴 — テストが含まれていた実行回数と、成功、失敗、スキップの回数
• 根拠となる実行 — 成功と失敗。スキップも記録されますが、根拠としては数えません。テストが実行されなかった場合、どちらの結果も証明できないためです
• 分類 — 判定を得るには、テストに最低限の根拠が必要です（デフォルトでは根拠となる実行が 2 回）。その後、失敗が一度もなければ stable_pass、成功が一度もなければ stable_fail、両方あれば flaky と分類され、それまでは insufficient_data となります
• 不安定率 — 根拠となる実行のうち、少数派の結果が占める割合です。そのため、結果が均等に分かれるテストは 0.5、ほとんど安定しているテストは 0 に近い値になります
• 隔離リスト — 不安定率が隔離しきい値（デフォルトでは 0.5）以上の不安定なテストを、不安定率の高い順に並べたものです。各項目には、不安定率の根拠となる成功数と失敗数が含まれます
• 判定 — リストが空でなければ quarantine_recommended、空であれば clean となります

不安定率は小数点以下 4 桁に丸められます。すべての計算は、指定された実行データを使ってローカルで行われます。ネットワークも設定も不要で、呼び出し間で履歴が保持されることもありません。実行結果のない実行、passed／failed／skipped 以外のステータス、1 回の実行における同一テストの重複など、不正な入力は該当するパスを示すエラーで拒否され、部分的な分析結果は生成されません。

CLI

npx @reneturcios/flakyguard analyze --input args.json
npx @reneturcios/flakyguard --version

args.json には、引数オブジェクト全体を記述します。

{
  "runs": [
    {
      "run_id": "run-101",
      "results": [
        { "test": "checkout totals", "status": "passed" },
        { "test": "search ranking", "status": "failed" }
      ]
    },
    {
      "run_id": "run-102",
      "results": [
        { "test": "checkout totals", "status": "failed" },
        { "test": "search ranking", "status": "failed" }
      ]
    }
  ],
  "min_runs": 2,
  "quarantine_threshold": 0.5
}

min_runs と quarantine_threshold は省略可能です。分析結果は JSON として出力されます。

終了コード：成功時は 0、実行時エラー（読み取れない、または無効な入力ファイルや、不正な入力を含む）の場合は 1、使用方法のエラーの場合は 2 です。

MCP サーバー

npx -y @reneturcios/flakyguard mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "flakyguard": {
      "command": "npx",
      "args": ["-y", "@reneturcios/flakyguard", "mcp"]
    }
  }
}

ツール

• analyze_test_flakiness — CI の実行を通じて、テストの不安定さを分析します。

  • runs（配列、必須、1 件以上）— {run_id, results} オブジェクトとして実行を指定します。各結果は {test, status} で、status は passed、failed、skipped のいずれかです。1 回の実行に同じテストを重複して含めることはできません
  • min_runs（整数、省略可能、>= 1、デフォルトは 2）— テストを安定または不安定と分類する前に必要な、根拠となる実行の最小数
  • quarantine_threshold（数値、省略可能、0 から 1、デフォルトは 0.5）— 隔離リストに含める不安定率のしきい値

  {run_count, test_count, tests, quarantine, summary, verdict} を返します。

Docker

docker run -i ghcr.io/cloudcorprecords/flakyguard
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/flakyguard analyze --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios