testfinder

testfinder

每次只做一点小改动，都运行整个测试套件，会形成缓慢的迭代循环。testfinder 可以缩小范围：提供一个源文件，以及项目的文件／导入映射——其中包含每个文件的路径和它导入的路径——它就会找出与该文件实际相关的测试、说明每个测试为何相关，以及仅运行这些测试的确切命令：

• 直接导入者 — 直接导入源文件的测试文件，距离为 1。
• 命名约定匹配 — 路径中在最后一个扩展名前插入 .test 或 .spec 后与源文件路径相符的测试文件，既可以与源文件位于同一目录（src/foo.ts → src/foo.test.ts），也可以位于 __tests__ 目录形式的路径中（src/__tests__/foo.test.ts）。没有扩展名的源文件会直接追加后缀（src/foo → src/foo.test）。
• 传递导入者 — 通过其他文件间接到达源文件的测试文件，各自按最短导入距离计算，因此图中的菱形路径会取较短路线。

每个相关测试恰好对应一个原因，优先级为：self（源文件本身就是测试）高于 direct，高于 convention，高于 transitive。结果先按原因优先级排序，再按距离排序，最后按路径排序；run_command 是按排名顺序运行这些测试的 npx tsx --test 命令；如果没有相关测试，则为 null。结果还会报告 total_files 和 test_files_considered，后者表示集合中的测试文件数量，无论这些文件是否相关。文件名包含 .test. / .spec.（或以 .test / .spec 结尾），或者文件位于 test、tests 或 __tests__ 目录下，即视为测试文件。

导入中指定的路径如果不在所提供的集合中，则视为外部导入：会被忽略，不会继续追踪，也不会报错。重复的导入条目会去重；出于图计算目的，文件对自身的导入会被忽略，但距离仍会经过途中的普通非测试文件传递。格式错误的输入——缺少或未知的 source_file、文件集合为空、文件路径重复、字段类型错误——会产生验证错误，并指出出错路径（例如 files[1].imports[0] must be a string），且不会返回部分结果。该计算是纯本地操作，工具只负责查找测试：使用它返回的命令运行测试由你自己的环境负责。

CLI

npx @reneturcios/testfinder find --input args.json
npx @reneturcios/testfinder --version

args.json 包含完整的参数对象：

{
  "source_file": "src/foo.ts",
  "files": [
    { "path": "src/foo.ts" },
    { "path": "src/bar.ts", "imports": ["src/foo.ts"] },
    { "path": "src/foo.test.ts" },
    { "path": "src/bar.test.ts", "imports": ["src/bar.ts", "react"] }
  ]
}

每个文件的 imports 默认为 []；此处的 react 不在集合中，因此会被忽略。src/foo.test.ts 是命名约定匹配项，且没有自己的导入；src/bar.test.ts 通过 src/bar.ts 到达源文件，距离为 2。结果以 JSON 格式打印：

{
  "source_file": "src/foo.ts",
  "relevant_tests": [
    { "path": "src/foo.test.ts", "reason": "convention", "distance": null },
    { "path": "src/bar.test.ts", "reason": "transitive", "distance": 2 }
  ],
  "total_files": 4,
  "test_files_considered": 2,
  "run_command": "npx tsx --test src/foo.test.ts src/bar.test.ts"
}

退出代码：成功时为 0，运行时错误时为 1（包括无法读取或无效的输入文件，或无效输入），用法错误时为 2。

MCP 服务

npx -y @reneturcios/testfinder mcp

MCP 客户端配置：

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

工具

• find_relevant_tests — 根据文件／导入映射，查找与一个源文件相关的测试。

  • source_file（字符串，必填）— 源文件的路径；必须是所提供文件之一
  • files（数组，必填，至少一个）— 文件列表，元素为 {path, imports?} 对象；path 在集合中必须唯一，每个 imports 条目可以指定另一个所提供的文件，也可以指定其他路径（视为外部导入并忽略）

  返回 {source_file, relevant_tests, total_files, test_files_considered, run_command}，其中 relevant_tests 的每一项为 {path, reason, distance}。

Docker

docker run -i ghcr.io/cloudcorprecords/testfinder
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/testfinder find --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 — 版权归 Rene Turcios 所有，2026 年