TestAtlas

<!-- mcp-name: io.github.Karzone/TestAtlas.Mcp -->
<h1 align="center">
  <img src="assets/logo-mark.svg" width="40" height="40" alt="" valign="middle">
  &nbsp;TestAtlas
</h1>

<p align="center">
  <strong>A queryable, semantic map of your .NET test-automation solution — in one SQLite file, served to your AI agent over MCP.</strong>
</p>

<p align="center">
  <em>Zero config&nbsp; ·&nbsp; No AI&nbsp; ·&nbsp; No network&nbsp; ·&nbsp; Deterministic</em>
</p>

<p align="center">
  <a href="https://www.nuget.org/packages/TestAtlas.Mcp"><img alt="TestAtlas.Mcp on NuGet" src="https://img.shields.io/nuget/v/TestAtlas.Mcp?logo=nuget&label=TestAtlas.Mcp&color=004880"></a>
  <a href="https://www.nuget.org/packages/TestAtlas.Cli"><img alt="TestAtlas.Cli on NuGet" src="https://img.shields.io/nuget/v/TestAtlas.Cli?logo=nuget&label=TestAtlas.Cli&color=004880"></a>
  <img alt="Model Context Protocol — listed" src="https://img.shields.io/badge/MCP_Registry-listed-7C3AED">
  <img alt=".NET 8.0" src="https://img.shields.io/badge/.NET-8.0-512BD4?logo=dotnet&logoColor=white">
  <img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue">
</p>

<p align="center">
  <sub><b>11 MCP tools</b></sub><br>
  <sub><code>resolve_step</code> · <code>step_catalog</code> · <code>impact</code> · <code>search_steps</code> · <code>search_scenarios</code> · <code>get_scenario</code> · <code>get_step_definition</code> · <code>list_tags</code> · <code>list_endpoints</code> · <code>project_dependencies</code> · <code>stats</code></sub>
</p>

<p align="center">
  <a href="#why">Why</a> ·
  <a href="#see-it">See it</a> ·
  <a href="#-quick-start">Quick start</a> ·
  <a href="#-use-it-from-an-ai-agent-mcp">MCP</a> ·
  <a href="#-commands">Commands</a> ·
  <a href="#-keeping-the-map-fresh">Fresh maps</a> ·
  <a href="#-roadmap">Roadmap</a>
</p>

---

## Why

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

One command over the bundled 8-project sample (`testatlas index samples/SampleShop/SampleShop.sln`),
then `testatlas report` — every number below is real output:

<p align="center">
  <a href="https://htmlpreview.github.io/?https://github.com/Karzone/TestAtlas/blob/main/docs/sample-report.html"><img alt="TestAtlas HTML report for SampleShop.sln — entity counts, 100% step-binding coverage, class kinds" src="assets/sample-report.png" width="820"></a>
</p>

Ask it questions from the terminal:

```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).
<sub>(GitHub serves `.html` as source, so the links route through htmlpreview.github.io — or download from [`docs/`](docs/) and open locally.)</sub>

## 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).

<details>
<summary><b>Or run from source</b> (no install)</summary>

```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
```

</details>

---

## 🔌 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 `<SolutionDir>\.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