# TestAtlas **Category:** πŸ’» Developer Tools **Repository:** https://github.com/Karzone/TestAtlas **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/testatlas ## Description Semantic map of a .NET test-automation solution for AI agents β€” search, impact, endpoints ## Claude Desktop Quick Installation Heuristic fallback β€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "testatlas": { "command": "npx", "args": ["-y","testatlas"] } } ``` ## Documentation & README

 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

TestAtlas.Mcp on NuGet TestAtlas.Cli on NuGet Model Context Protocol β€” listed .NET 8.0 MIT license

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: ```console $ 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: ```jsonc // 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 and their edges). (GitHub serves `.html` as source, so the links route through htmlpreview.github.io β€” or download from [`docs/`](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: | | Capability | What you get | |:--:|---|---| | 🧩 | **Reuse-first authoring** | `resolve_step` β€” would this phrase bind an existing definition? `step_catalog` β€” the reusable step vocabulary with placeholders + allowed values | | πŸ’₯ | **Impact** | Blast radius β€” the scenarios affected by changing a class, method, step, or endpoint | | πŸ” | **Search** | FTS5 over step definitions + scenarios β€” *"does a step for this already exist?"* | | πŸ”Œ | **MCP** | All of it served to an AI agent over stdio β€” precise answers in a few hundred tokens, no context stuffing | | πŸ“Š | **Report & map** | Self-contained HTML drill-down of the whole map + project-dependency graph | | πŸ“ˆ | **Stats** | Entity counts, class-kind breakdown, binding coverage, diagnostics | All of it **offline, deterministic, and reproducible** β€” same input, same map, every time. --- ## πŸš€ Quick start > **Requires** the [.NET SDK 8.0+](https://dotnet.microsoft.com/download). On a corporate machine > where `dotnet tool install` fails with **401**, see > [docs/troubleshooting.md](docs/troubleshooting.md). **1 β€” Install** the CLI (and the MCP server, if you'll connect an agent): ```bash 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: ```bash 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:** ```bash 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](#-use-it-from-an-ai-agent-mcp).
Or run from source (no install) ```bash 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](#-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`): ```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 makes the server exit with `code 2`. 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:** ```bash 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](docs/troubleshooting.md#the-agent-doesnt-seem-to-use-testatlas). **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, methods, class-kind breakdown, endpoints, and edge tallies. Retrieval runs locally against the SQLite file β€” deterministic, offline, and a few hundred tokens per answer. Protocol details in [`specs/codemap-mcp.md`](specs/codemap-mcp.md); registration from source and every failure mode in [docs/troubleshooting.md](docs/troubleshooting.md). --- ## πŸ“– Commands | Command | What it does | | --- | --- | | `index []` | Analyse a `.sln`/`.csproj` and write the map (default `./codemap.db`). | | `stats []` | Entity counts per project, unbound/ambiguous steps, diagnostics. | | `search [] ` | FTS5 full-text search over step definitions and scenarios. | | `impact [] --class\|--method\|--step\|--endpoint ` | Blast radius: scenarios affected by changing an entity. | | `report []` | Write a self-contained HTML drill-down of the map. | | `map []` | Write a self-contained project dependency graph (HTML). | | `validate []` | Check a file is a supported TestAtlas map. |
Options & exit codes
**`index`**  `--output ` Β· `--config ` Β· `--include ` (repeatable) Β· `--exclude ` (repeatable) Β· `--verbose` Β· `--quiet` **`search`**  `--steps` (step definitions only) Β· `--scenarios` (scenarios only) **Exit codes**  `0` ok Β· `1` completed with warnings Β· `2` fatal Β· `3` bad arguments Run `testatlas --help` for the full usage text.
A typical session
```bash # 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 ```
About the bundled sample (SampleShop)
[`samples/SampleShop`](samples/SampleShop) is a self-contained **8-project** solution mixing API tests and UI tests, so the map has plenty of connected nodes β€” real `HttpClient` API clients, real Selenium `IWebDriver` page objects, and Reqnroll suites driving both: ```text β”Œβ”€β–Ά Api.Catalog ──┐ Tests.Api ────────────┼─▢ Api.Cart ─── Tests.E2E ──┬─────────┴─▢ Api.Identity ──┼─▢ Core (ApiClientBase : HttpClient) └─▢ Ui.Pages β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ (PageBase : IWebDriver) Tests.Ui ────▢ Ui.Pages ──────────────────▢ Core ``` Reproduce the committed sample outputs yourself: ```bash 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 ```
--- ## πŸ”„ Keeping the map fresh Answers are deterministic β€” but only as fresh as the map, so re-index on *change*, not on a timer. A full re-index is a single static pass (**seconds**), and its cost scales with solution size, not with how much changed: - **Locally** β€” `python scripts/check-map-age.py` tells you when your map drifted; a version-controlled `post-merge` git hook can warn automatically after every pull. - **In CI (team model)** β€” re-index on every merge to main and publish the `.db` to a shared feed (never commit it β€” it's a build artifact). Then teammates and agents only need **`TestAtlas.Mcp`** locally: download the shared map and point `TESTATLAS_DB` at it β€” no local `TestAtlas.Cli` or indexing required. (Index locally only to include your own *uncommitted* branch work.) Details β€” the staleness checker, the git hook, and copy-paste CI recipes (GitHub Actions + Azure DevOps with a Universal feed) β€” in **[docs/keeping-the-map-fresh.md](docs/keeping-the-map-fresh.md)**. --- ## 🧹 Uninstall Two separate things β€” remove them in this order, so the editor isn't launching a server whose binary just vanished: 1. **Remove the MCP registration** β€” delete the `testatlas` block from your `.mcp.json` (`\.mcp.json` or `%USERPROFILE%\.mcp.json`), then restart Visual Studio / VS Code. (Or just toggle it off in the agent's tools/wrench picker to keep it for later.) 2. **Uninstall the tools** β€” they're .NET global tools, not editor add-ins: ```bash dotnet tool uninstall --global TestAtlas.Mcp dotnet tool uninstall --global TestAtlas.Cli dotnet tool list --global # confirm they're gone ``` 3. **(Optional)** delete the `codemap.db` map file β€” it's just data, nothing else references it. --- ## 🎯 Design tenets - **Zero config** β€” a useful map on an unseen solution, no config file required. - **Solution agnostic** β€” heuristic, overridable detection; no company-specific assumptions. - **Deterministic & offline** β€” same input β‡’ byte-equivalent logical content; no network, no AI. - **Graceful degradation** β€” solutions without Gherkin still yield a useful map. - **Public schema as contract** β€” a versioned SQLite schema, so downstream consumers keep working even if a third party swaps in their own indexer. The project folders use the indexer's working name (**CodeMap**); the shipped tools and packages are **TestAtlas**. Full specs: [`specs/codemap-indexer.md`](specs/codemap-indexer.md) Β· [`specs/codemap-mcp.md`](specs/codemap-mcp.md). Repo layout: [CONTRIBUTING.md](CONTRIBUTING.md#project-layout). --- ## πŸ—Ί Roadmap - [x] **Indexer CLI** β€” C# indexer + documented, versioned SQLite schema - [x] **HTML visualization** β€” self-contained report + project map generated from the db - [x] **MCP server** β€” `testatlas-mcp` exposes the map to AI agents over stdio JSON-RPC (11 tools) - [ ] **Second-language indexer** β€” same schema, contract-tested **Deliberately not planned** (see [design tenets](#-design-tenets)): LLM-assisted analysis inside the indexer, network calls at index/query time, running or generating tests, and semantic (compilation-based) analysis that would require a restored build. Releases and per-version notes live on the [releases page](https://github.com/Karzone/TestAtlas/releases); current distribution channels in [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md). --- ## πŸ“„ License [MIT](LICENSE) Β© 2026 Karthik Kalaiyarasu