testfinder

testfinder

小さな編集のたびにテストスイート全体を実行すると、 時間のかかる反復になります。testfinderなら対象を絞り込めます。ソースファイルを1つと、 プロジェクトのファイル／インポートマップ（各ファイルのパスと インポート先のパス）を渡すと、そのファイルに実際に関連するテストと、 それぞれが関連する理由、そして該当するテストだけを実行する正確なコマンドを 特定します。

• 直接インポート — ソース ファイルを直接インポートするテストファイル。距離は1です。
• 命名規則による一致 — ソースのパスの最後の拡張子の前に .test または .spec を挿入したパスを持つテストファイルです。同じ ディレクトリに置く形式（src/foo.ts → src/foo.test.ts）と、 __tests__ 形式（src/__tests__/foo.test.ts）があります。名前に拡張子がない ソースの場合は、代わりに末尾へサフィックスを追加します （src/foo → src/foo.test）。
• 推移的なインポート — 他のファイルを経由して ソースに到達するテストファイルです。それぞれ最短のインポート距離を使うため、 グラフ内のダイヤモンド構造でも短い経路が選ばれます。

関連する各テストには、優先順位に基づいて決定される理由が1つだけ付与されます。 優先順位は 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 — ファイル／インポートマップから、 1つのソースファイルに関連するテストを特定します。

  • source_file（string、必須）— ソース ファイルのパス。指定されたファイルのいずれかである必要があります。
  • files（array、必須、1件以上）— {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 — Copyright (c) 2026 Rene Turcios