TestAtlas

TestAtlas

A queryable, semantic map of your .NET test-automation solution — in one SQLite file, served to your AI agent over MCP.

Zero config · No AI · No network · Deterministic

11 MCP tools

resolve_step · step_catalog · impact · search_steps · search_scenarios · get_scenario · get_step_definition · list_tags · list_endpoints · project_dependencies · stats

The problem · See it in action · Quick start · MCP · Commands · Fresh maps · Roadmap

---

The problem

Large test-automation solutions are hard to navigate — for humans *and* for AI agents. Asked to automate a new story, an agent can't see which steps already exist, where similar code lives, or what conventions the solution follows — so it duplicates steps and misplaces code. TestAtlas indexes the solution once into a single SQLite map and answers those questions precisely: deterministically, offline, without a model or a network call.

---

See it in action

Index the bundled 8-project sample once — testatlas index samples/SampleShop/SampleShop.sln — then ask it questions from the terminal. Every number below is real output from that run:

$ 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))

…or let your agent ask them over MCP. Here an agent checks whether a step it is about to write already exists — resolve_step answers with the definitions that would bind it, or the closest near-misses to reuse instead:

// 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 ] }

Live sample outputs, committed from that same solution: [HTML report](https://htmlpreview.github.io/?https://github.com/Karzone/TestAtlas/blob/main/docs/sample-report.html) (features, scenarios, bindings, class kinds, endpoints) · [dependency map](https://htmlpreview.github.io/?https://github.com/Karzone/TestAtlas/blob/main/docs/sample-map.html) (the eight projects in layers — click one to see what it uses, what uses it, and which tests a change can reach). (GitHub serves .html as source, so the links route through htmlpreview.github.io — or download from docs/ and open locally.)

What you get

TestAtlas statically analyses the solution and emits codemap.db — projects and their dependency edges, Gherkin features/scenarios/steps, step definitions and their bindings (bound / unbound / ambiguous), page objects, API clients, helpers, test classes, and the call/usage edges connecting them — then turns that map into answers:

All of it offline, deterministic, and reproducible — same input, same map, every time.

---

🚀 Quick start

Requires the .NET SDK 8.0+. On a corporate machine

where dotnet tool install fails with 401, see

docs/troubleshooting.md.

1 — Install the CLI (and the MCP server, if you'll connect an agent):

dotnet tool install --global TestAtlas.Cli

dotnet tool install --global TestAtlas.Mcp

2 — Index your solution. This produces the map (./codemap.db) that every query, report, and MCP answer reads — nothing works without it:

testatlas index path/to/YourSolution.sln

No need to build or restore the solution first — indexing is a syntax-only pass, so an unrestored checkout maps fine. Point index at a folder (or nothing) and it auto-discovers a single .sln/.csproj there.

3 — Query it:

testatlas stats

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

…and to serve it to your AI agent, continue to MCP setup.

Or run from source (no install)

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

---

🔌 Use it from an AI agent (MCP)

TestAtlas ships an MCP server — testatlas-mcp — that serves the map to any MCP-aware client (Visual Studio / VS Code Copilot, Claude Code, and others) over stdio JSON-RPC. The agent asks a precise question and gets an exact, structured answer straight from the .db — instead of stuffing source files into its context window.

Prerequisites: both tools installed and a map built — steps 1–2 of the Quick start. Then register the server:

Visual Studio / VS Code (GitHub Copilot agent mode) — add to your .mcp.json (%USERPROFILE%\.mcp.json or \.mcp.json):

{

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

Pass the map path explicitly (as above, or via a TESTATLAS_DB env var) — most agents launch the server from their own working directory, not your solution folder, so relying on auto-discovery leaves the server with no map: it starts and lists its tools, but every call answers with an error saying how to supply one (releases before 0.1.11 exited with code 2 instead). In Visual Studio you can also use Tools picker → `+` → Add custom MCP server to write this entry for you. On the .NET 10 SDK you can skip the install and use "command": "dnx", "args": ["TestAtlas.Mcp", "--yes", "C:\\path\\to\\codemap.db"] — dnx fetches and runs the server on demand.

Claude Code — as a plugin (server, a skill that says when to use which tool, /testatlas:index, /testatlas:report, and a session-start check that tells Claude when the map is missing or stale):

claude plugin marketplace add Karzone/TestAtlas

claude plugin install testatlas@testatlas

The plugin starts testatlas-mcp with no arguments, so it serves the codemap.db at the root of whatever project the session is opened in — build it with /testatlas:index; from 0.1.12 the server picks the map up on the next call, with nothing to reconnect. Both tools must be on the PATH (dotnet tool install --global TestAtlas.Cli, then the same for TestAtlas.Mcp). The plugin lives in claude-plugin/.

Claude Code — one server, no plugin:

claude mcp add testatlas -- testatlas-mcp path/to/codemap.db

claude mcp list # the testatlas row should read: ✔ Connected

By default the server is registered for the current project (--scope local). Add --scope user to make it available in every project on your machine, or --scope project to share the registration with your team via a committed .mcp.json.

[!IMPORTANT]

MCP clients load servers at session start — if you register mid-session, restart your agent

session before the testatlas tools appear. To confirm it's actually being used (and not

silently ignored), run the checks in

docs/troubleshooting.md.

Tools exposed:

• resolve_step — resolve a Gherkin phrase to the existing step definition(s) that would bind it (regex/cucumber, keyword-agnostic). exact / ambiguous / none (+ near-match suggestions ranked by shared terms). Reuse-first authoring: don't write a step that already exists.
• step_catalog — the reusable step vocabulary with extracted placeholders and allowed values (cucumber {type}, regex (a|b) enums). Compose scenarios from what exists.
• impact — blast radius of a change: the scenarios affected by a given class, method, step definition, or endpoint.
• search_steps — full-text search over step definitions (expression text + method + class name).
• search_scenarios — full-text search over scenarios (feature + scenario name + step text + tags).
• get_scenario — full detail of scenario(s) by name: feature, tags, kind, example-row count, and the ordered steps.
• get_step_definition — full detail of step definition(s) by expression: keyword, params, C# class/method/signature, and the scenarios that use it.
• list_tags — the tag taxonomy with per-tag scenario counts, most-used first — tag new scenarios consistently.
• list_endpoints — the HTTP endpoints the suite calls, each with verb, route, and scenario blast radius (highest-reach first).
• project_dependencies — the implied project dependency graph (depends-on / depended-on-by), e.g. *"what depends on the Party project?"*.
• stats — summary counts: projects, classes, met