TestAtlas

 TestAtlas

.NET テスト自動化ソリューションを意味的にマッピングし、クエリで検索可能にします。SQLite ファイル 1 つに収め、MCP 経由で AI エージェントに提供します。

設定不要  ·  AI 不使用  ·  ネットワーク不使用  ·  決定論的

_{11 個の MCP ツール
resolve_step · step_catalog · impact · search_steps · search_scenarios · get_scenario · get_step_definition · list_tags · list_endpoints · project_dependencies · stats}

課題 · 動作を見る · クイックスタート · MCP · コマンド · マップを最新に保つ · ロードマップ

課題

大規模なテスト自動化ソリューションは、人間にとっても AI エージェント にとっても把握が困難です。新しいストーリーの自動化を依頼されても、エージェントには既存のステップや類似コードの場所、ソリューションで採用されている規約が分からず、ステップを重複させたり、コードを不適切な場所に配置したりします。TestAtlas はソリューションを一度だけインデックス化し、単一の SQLite マップにまとめて、モデルやネットワーク呼び出しを使わず、オフラインかつ決定論的に、こうした質問へ正確に回答します。

動作を見る

付属の 8 プロジェクトのサンプルを一度インデックス化します — testatlas index samples/SampleShop/SampleShop.sln — その後、ターミナルから質問できます。以下の数値はすべて、その実行時の実際の出力です：

$ testatlas stats sampleshop.db
TestAtlas map: sampleshop.db (schema v5)

totals: 8 project(s), 15 class(es), 36 method(s), 14 step definition(s)
class kinds:
  api_client     7
  page_object    4
  step_class     4

gherkin: 4 feature(s), 5 scenario(s), 16 step(s)
bound steps: 16 · unbound: 0 · ambiguous: 0
endpoints: 3 (3 call site(s))

…または、MCP 経由でエージェントに質問させることもできます。ここでは、エージェントがこれから記述しようとしているステップがすでに存在するかを確認しています — resolve_step は、そのステップにバインドされる定義、または代わりに再利用できる最も近い候補を返します：

// agent → testatlas: resolve_step { "text": "I add the product to my cart" }
{
  "status": "none",            // nothing binds this exact text — don't invent it from scratch:
  "suggestions": [             // these existing steps are the closest, ranked by shared terms
    { "expression": "product (.*) is added to the cart with quantity (.*)",
      "keyword": "When", "location": "SampleShop.Tests.Api/Steps/CatalogApiSteps.cs:34" },
    { "expression": "the cart is not empty",
      "keyword": "Then", "location": "SampleShop.Tests.Api/Steps/CatalogApiSteps.cs:43" }
    // …8 more
  ]
}

同じソリューションからコミットされた、実際のサンプル出力： HTML レポート（フィーチャー、シナリオ、バインディング、クラスの種類、エンドポイント） · 依存関係マップ（8 つのプロジェクトをレイヤー別に表示。プロジェクトをクリックすると、そのプロジェクトが使用するもの、そこに依存するもの、変更の影響が及ぶ可能性のあるテストを確認できます）。 _{（GitHub は .html をソースとして表示するため、リンクは htmlpreview.github.io 経由です。または、docs/ からダウンロードしてローカルで開いてください。）}

得られるもの

TestAtlas はソリューションを静的に解析し、codemap.db を出力します。そこには、プロジェクトとその依存関係のエッジ、Gherkin の機能／シナリオ／ステップ、ステップ定義とそのバインディング（バインド済み／未バインド／曖昧）、ページオブジェクト、API クライアント、ヘルパー、テストクラス、それらをつなぐ呼び出し／使用のエッジが含まれます。さらに、このマップを回答に変換します。

すべてがオフラインで、決定論的かつ再現可能です。同じ入力なら、毎回同じマップが得られます。

🚀 クイックスタート

必要条件： .NET SDK 8.0+。企業のマシンで dotnet tool install が 401 エラーで失敗する場合は、 docs/troubleshooting.md をご覧ください。

1 — インストール CLI（エージェントに接続する場合は MCP サーバーも）をインストールします。

dotnet tool install --global TestAtlas.Cli
dotnet tool install --global TestAtlas.Mcp

2 — インデックス作成 ソリューションをインデックス化します。これによりマップ（./codemap.db）が生成されます。すべてのクエリ、レポート、MCP の回答はこのマップを読み取ります。マップがなければ何も動作しません。

testatlas index path/to/YourSolution.sln

先にソリューションをビルドしたり、復元したりする必要はありません。インデックス作成は構文のみを対象とするため、復元していないチェックアウトでも問題なくマップを作成できます。index にフォルダー（または何も指定しない）を渡すと、その中の .sln／.csproj を 1 つ自動検出します。

3 — クエリを実行します。

testatlas stats
testatlas search "login"
testatlas report        # writes codemap.html
testatlas map           # writes codemap-map.html

…AI エージェントに提供するには、MCP のセットアップ に進んでください。

git clone https://github.com/Karzone/TestAtlas.git
cd TestAtlas
dotnet build TestAtlas.sln
dotnet run --project src/CodeMap.Cli -- index path/to/YourSolution.sln

🔌 AI エージェントから使用する（MCP）

TestAtlas には testatlas-mcp という MCP サーバーが付属しています。このサーバーは、MCP 対応クライアント（Visual Studio／VS Code Copilot、Claude Code など）に対し、stdio の JSON-RPC 経由でマップを提供します。エージェントは的確な質問を行い、ソースファイルをコンテキストウィンドウに詰め込む代わりに、.db から直接、正確で構造化された回答を得られます。

前提条件：両方のツールがインストール済みで、マップが作成されていること — クイックスタートの手順 1～2 を参照してください。その後、サーバーを登録します。

Visual Studio／VS Code（GitHub Copilot エージェントモード） — .mcp.json （%USERPROFILE%\.mcp.json または <SolutionDir>\.mcp.json）に追加します。

{
  "servers": {
    "testatlas": {
      "type": "stdio",
      "command": "testatlas-mcp",
      "args": ["C:\\path\\to\\codemap.db"]
    }
  }
}

マップのパスを明示的に渡してください（上記の方法、または TESTATLAS_DB 環境変数を使用）。ほとんどのエージェントはソリューションフォルダーではなく、自身の作業ディレクトリからサーバーを起動します。そのため、自動検出に頼るとサーバーにマップが渡されません。サーバーは起動してツール一覧を表示しますが、各呼び出しはマップの指定方法を示すエラーを返します（0.1.11 より前のリリースでは、代わりに code 2 で終了していました）。Visual Studio では、ツールピッカー → + → カスタム MCP サーバーの追加からも、この設定を作成できます。.NET 10 SDK では、インストールを省略して "command": "dnx", "args": ["TestAtlas.Mcp", "--yes", "C:\\path\\to\\codemap.db"] を使用できます。dnx が必要に応じてサーバーを取得し、実行します。

Claude Code — プラグインとして（サーバー、どのツールをいつ使うかを示すスキル、/testatlas:index、/testatlas:report、およびマップがないか古い場合に Claude に知らせるセッション開始時のチェックを含みます）。

claude plugin marketplace add Karzone/TestAtlas
claude plugin install testatlas@testatlas

プラグインは引数なしで testatlas-mcp を起動するため、セッションを開いたプロジェクトのルートにある codemap.db を提供します。/testatlas:index でビルドしてください。0.1.12 以降は、次の呼び出し時にサーバーがマップを読み込むため、再接続は不要です。両方のツールが PATH に通っている必要があります（dotnet tool install --global TestAtlas.Cli を実行し、続けて同様に TestAtlas.Mcp をインストールしてください）。プラグインは claude-plugin/ にあります。

Claude Code — プラグインを使わず、サーバーを 1 つ登録：

claude mcp add testatlas -- testatlas-mcp path/to/codemap.db
claude mcp list        # the testatlas row should read: ✔ Connected

デフォルトでは、サーバーは現在のプロジェクトに登録されます（--scope local）。マシン上のすべてのプロジェクトで利用できるようにするには --scope user を追加してください。または、コミットした .mcp.json を使ってチームで登録を共有するには --scope project を追加します。

重要

MCP クライアントはセッション開始時にサーバーを読み込みます。セッション中に登録した場合は、testatlas ツールが表示される前にエージェントのセッションを再起動してください。実際に使用されていること（無視されていないこと）を確認するには、 docs/troubleshooting.md のチェックを実行してください。

公開されるツール：

• resolve_step — Gherkin のフレーズに対応する既存のステップ定義を解決します（正規表現／cucumber、キーワード非依存）。exact / ambiguous / none（共有する用語の多さで順位付けされた近似一致の候補も表示）。既存のステップを再利用することを優先して作成してください。すでに存在するステップは作成しないでください。
• step_catalog — 抽出されたプレースホルダーと許可値を含む、再利用可能なステップの語彙（cucumber の {type}、正規表現の (a|b) 列挙）。既存の内容を基にシナリオを構成できます。
• impact — 変更の影響範囲を示します。指定したクラス、メソッド、ステップ定義、またはエンドポイントの影響を受けるシナリオを確認できます。
• search_steps — ステップ定義を全文検索します（式のテキスト、メソッド名、クラス名）。
• search_scenarios — シナリオを全文検索します（フィーチャー名、シナリオ名、ステップテキスト、タグ）。
• get_scenario — 名前を指定してシナリオの詳細を取得します。フィーチャー、タグ、種類、サンプル行数、順序付きのステップを確認できます。
• get_step_definition — 式を指定してステップ定義の詳細を取得します。キーワード、パラメーター、C# のクラス／メソッド／シグネチャ、および使用しているシナリオを確認できます。
• list_tags — タグごとのシナリオ数を含むタグの分類を、使用頻度の高い順に表示します。新しいシナリオにも一貫したタグを付けられます。
• list_endpoints — スイートが呼び出す HTTP エンドポイントを、HTTP メソッド、ルート、シナリオへの影響範囲とともに表示します（影響範囲の大きい順）。
• project_dependencies — 暗黙のプロジェクト依存関係グラフを表示します（依存先／依存元）。例：「Party プロジェクトに依存しているのは何ですか？」。
• stats — プロジェクト、クラス、メソッド、クラス種別の内訳、エンドポイント、エッジの集計などの概要を表示します。

検索は SQLite ファイルに対してローカルで実行されるため、決定論的でオフラインでも使用でき、回答あたり数百トークンで済みます。プロトコルの詳細は specs/codemap-mcp.md を、ソースからの登録方法とすべての障害ケースは docs/troubleshooting.md を参照してください。

📖 コマンド

# Index the solution (no build needed — the pass is syntax-only)
testatlas index YourSolution.sln --output atlas.db

# Before writing a new step — does one already exist?
testatlas search atlas.db "add a product to the cart" --steps

# About to change a shared client — what will it hit?
testatlas impact atlas.db --class ProductsApiClient

# Share human-readable snapshots
testatlas report atlas.db --html atlas.html
testatlas map    atlas.db --html atlas-map.html

                       ┌─▶ Api.Catalog  ──┐
Tests.Api  ────────────┼─▶ Api.Cart     ──┤
Tests.E2E  ──┬─────────┴─▶ Api.Identity ──┼─▶ Core   (ApiClientBase : HttpClient)
             └─▶ Ui.Pages ─────────────────┘          (PageBase      : IWebDriver)
Tests.Ui   ────▶ Ui.Pages ──────────────────▶ Core

testatlas index  samples/SampleShop/SampleShop.sln --output sampleshop.db
testatlas report sampleshop.db --html docs/sample-report.html
testatlas map    sampleshop.db --html docs/sample-map.html

🔄 マップを最新の状態に保つ

回答は決定論的ですが、マップが最新である場合に限ります。そのため、タイマーではなく、変更時に再インデックスしてください。 完全な再インデックスは、1 回の静的パスで完了します（数秒）。処理時間は変更量ではなく、ソリューションの規模に応じて変わります。

• ローカル — python scripts/check-map-age.py を実行すると、マップにずれが生じたときに分かります。バージョン管理された post-merge git フックを使えば、プルのたびに自動で警告できます。
• CI（チームモデル） — main へのマージのたびに再インデックスし、.db を共有フィードに公開します（コミットしないでください。ビルド成果物です）。その後、チームメンバーとエージェントは、ローカルに TestAtlas.Mcp だけを用意すれば十分です。共有マップをダウンロードして TESTATLAS_DB にそのパスを指定すればよく、ローカルの TestAtlas.Cli もインデックス作成も必要ありません。（未コミットのブランチの作業を含める場合に限り、ローカルでインデックスを作成してください。）

詳細（鮮度チェッカー、git フック、コピーして使える CI の設定例（GitHub Actions + Universal feed を使う Azure DevOps））は、docs/keeping-the-map-fresh.md を参照してください。

🧹 アンインストール

削除するものは 2 つあります。エディターが、バイナリを削除した MCP サーバーを起動しようとしないよう、次の順序で削除してください。

1. MCP の登録を削除する — .mcp.json（<SolutionDir>\.mcp.json または %USERPROFILE%\.mcp.json）から testatlas ブロックを削除し、Visual Studio／VS Code を再起動します。（または、エージェントのツール／レンチ選択画面でオフに切り替えると、後で使えるよう登録を残せます。）
2. ツールをアンインストールする — エディターのアドインではなく、.NET のグローバルツールです。

   dotnet tool uninstall --global TestAtlas.Mcp
   dotnet tool uninstall --global TestAtlas.Cli
   dotnet tool list --global            # confirm they're gone
   

3. （任意） codemap.db マップファイルを削除します。これはデータファイルにすぎず、ほかから参照されていません。

🎯 設計の指針

• 設定不要 — 未知のソリューションでも、設定ファイルなしで役立つマップを作成します。
• ソリューションに依存しない — ヒューリスティックによる検出を行い、上書きも可能です。特定の企業を前提としません。
• 決定的かつオフライン — 同じ入力なら論理的に同一の内容が生成されます。ネットワークもAIも使用しません。
• 段階的な機能低下 — Gherkin を使用していないソリューションでも、役立つマップを生成します。
• 公開スキーマを契約とする — バージョン管理された SQLite スキーマにより、第三者が独自のインデクサーに置き換えても、下流の利用者は引き続き動作します。

_{プロジェクトのフォルダーでは、インデクサーの作業名（CodeMap）を使用しています。提供されるツールとパッケージの名称は TestAtlas です。完全な仕様は specs/codemap-indexer.md · specs/codemap-mcp.md をご覧ください。リポジトリの構成は CONTRIBUTING.md をご覧ください。}

🗺 ロードマップ

• インデクサー CLI — C# インデクサーと、文書化されたバージョン管理付き SQLite スキーマ
• HTML ビジュアライゼーション — データベースから生成される、自己完結型のレポートとプロジェクトマップ
• MCP サーバー — testatlas-mcp が stdio JSON-RPC を介して AI エージェントにマップを公開します（11 個のツール）
• 第 2 言語のインデクサー — 同じスキーマを使用し、契約テストで検証

意図的に計画していない項目（設計の指針をご覧ください）：インデクサー内での LLM 支援分析、インデックス作成時やクエリ時のネットワーク呼び出し、テストの実行または生成、復元済みのビルドを必要とするセマンティック（コンパイルベース）分析。リリースとバージョンごとの更新内容はリリースページに、現在の配布チャネルは docs/DISTRIBUTION.md に掲載されています。

📄 ライセンス

MIT © 2026 Karthik Kalaiyarasu