flakyguard

flakyguard

“这个测试不稳定”通常只是一种感觉。flakyguard 将其转化为证据。向它提供一组 CI 运行中每项测试的结果，它就会为每项测试建立记录：

• 每项测试的历史记录 — 测试出现于多少次运行中，以及通过、失败或跳过了多少次
• 证据运行 — 通过次数加失败次数；跳过会被记录，但永远不计为证据，因为测试没有运行，无法证明任何一方
• 分类 — 测试需要达到最低证据数量（默认为两次证据运行）才能获得判定：从未失败时为 stable_pass，从未通过时为 stable_fail，既通过又失败时为 flaky，在达到最低数量前为 insufficient_data
• 不稳定率 — 少数结果占证据运行的比例，因此结果平分的测试不稳定率为 0.5，而大多时候可靠的测试不稳定率接近 0
• 隔离列表 — 不稳定率达到隔离阈值（默认为 0.5）的不稳定测试，按最严重程度从高到低排列，每项均附带该不稳定率对应的通过和失败次数
• 判定 — 列表非空时为 quarantine_recommended，否则为 clean

不稳定率四舍五入到小数点后四位。所有计算均在本地根据你提供的运行结果完成：不联网、无需配置，也不会在调用之间保留历史记录。输入有误时——例如某次运行没有结果、状态不属于 passed / failed / skipped，或同一项测试在一次运行中出现两次——程序会报错并指出出错路径，不会生成部分分析结果。

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（数组，必需，至少一个）— 运行记录，格式为 {run_id, results} 对象；每项结果的格式为 {test, status}，其中 status 为 passed、failed 或 skipped 之一；同一项测试不得在一次运行中出现两次
  • 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 — 版权所有 (c) 2026 Rene Turcios