TestAtlas

Упорядочиваемая семантическая карта вашего .NET-решения по тест-автоматизации — в одном файле SQLite, доступном вашему AI-агенту через MCP.

Без настройки · Без ИИ · Без сети · Детерминированно

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",            // ничего не привязывается к этому тексту — не придумывайте его заново:
  "suggestions": [             // эти существующие шаги — ближайшие, ранжированные по общим терминам
    { "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-отчёт (фичи, сценарии, привязки, виды классов, конечные точки) ·

Карта зависимостей (восемь проектов и их связи).

(GitHub предоставляет .html как исходник, поэтому ссылки проходят через htmlpreview.github.io — или скачайте из docs/ и откройте локально.)

Что вы получаете

TestAtlas статически анализирует решение и генерирует codemap.db — проекты и их зависимости, фичи/Gherkin/сценарии/шаги, определения шагов и их привязки (bound / unbound / ambiguous), page objects, API-клиенты, хелперы, тестовые классы и связи вызовов, — затем превращает эту карту в ответы:

	Возможность	Что вы получаете
🧩	Авторинг с упором на повторное использование	`resolve_step` — привяжет ли эта фраза существующее определение? `step_catalog` — повторно используемая лексика шагов с заполнителями + допустимыми значениями
💥	Влияние	Радиус воздействия — сценарии, затрагиваемые изменением класса, метода, шага или конечной точки
🔍	Поиск	FTS5 по определениям шагов + сценариям — "существует ли шаг для этого?"
🔌	MCP	Всё это подается AI-агенту через stdio — точные ответы в пределах нескольких сотен токенов, без перегрузки контекстом
📊	Отчёт и карта	Самодостаточный HTML-расшифровка всей карты + граф зависимостей проекта
📈	Статистика	Подсчёт сущностей, разбор по видам классов, покрытие привязок, диагностика

Все это OFFLINE, детерминировано и воспроизводимо — один и тот же ввод всегда даёт один и тот же выход карты.

🚀 Быстрый старт

Требуется .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 там.

3 — Запросите её:

testatlas stats
testatlas search "login"
testatlas report        # пишет codemap.html
testatlas map           # пишет 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 поставляет MCP-сервер — testatlas-mcp — который обслуживает карту любому клиенту, поддерживающему MCP (Visual Studio / VS Code Copilot, Claude Code и др.) через stdio JSON-RPC. Агент задаёт точный вопрос и получает точный структурированный ответ прямо из .db — вместо того, чтобы загружать исходники в окно контекста.

Предварительные требования: установлены оба инструмента и собрана карта — шаги 1–2 Быстрого старта. Затем зарегистрируйте сервер:

Visual Studio / VS Code (режим агента GitHub Copilot) — добавьте в ваш .mcp.json ( <SolutionDir>\.mcp.json или %USERPROFILE%\.mcp.json ):

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

Передайте явным образом путь к карте (как выше, или через переменную окружения TESTATLAS_DB) — большинство агентов запускают сервер из своей рабочей директории, а не из папки вашего решения, поэтому полагаться на автообнаружение приводит к выходу сервера с code 2. В Visual Studio можно также использовать Tools picker → + → Add custom MCP server чтобы записать эту запись за вас. На .NET 10 SDK можно пропустить установку и использовать "command": "dnx", "args": ["TestAtlas.Mcp", "--yes", "C:\\path\\to\\codemap.db"] — dnx загружает и запускает сервер по запросу.

Claude Code:

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

По умолчанию сервер регистрируется для текущего проекта (--scope local). Добавьте --scope user, чтобы сделать его доступным в каждом проекте на вашей машине, или --scope project, чтобы разделить регистрацию с вашей командой через зафиксированный .mcp.json.

Важно: клиенты MCP загружают серверы при старте сессии — если вы зарегистрировали сервер в середине сессии, перезапустите вашу сессионную агентскую сессию перед появлением инструментов testatlas. Чтобы убедиться, что сервер действительно используется (а не молча игнорируется), проверьте в docs/troubleshooting.md.

Доступные инструменты:

resolve_step — определить фразу Gherkin и существующее определение(я), которое бы ее связало (регекс/cucumber, без привязки к ключевому слову). exact / ambiguous / none (+ предложения близких совпадений, ранжированные по общим терминам). Авторинг с упором на повторное использование: не писать шаг, который уже существует.
step_catalog — повторно используемая лексика шагов с извлечёнными заполнителями и допустимыми значениями (cucumber {type}, перечисления (a|b) в виде регулярного выражения). Компонуйте сценарии из существующего.
impact — радиус воздействия изменений: сценарии, затрагиваемые изменением класса, метода, шага илиEndpoint.
search_steps — полнотекстовый поиск по определениям шагов (текст выражения + имя метода + класс).
search_scenarios — полнотекстовый поиск по сценариям (фича + имя сценария + текст шага + теги).
get_scenario — полное описание сценария(ов) по имени: фича, теги, вид, число примеров и упорядоченные шаги.
get_step_definition — полное описание определения шага по выражению: ключевое слово, параметры, класс/метод/сигнатура C#, и сценарии, которые его используют.
list_tags — таксономия тегов с подсчётом по тегу (часто встречающийся вначале) — тегируйте новые сценарии последовательно.
list_endpoints — HTTP-конечные точки, которые вызывает пакет, каждая с глаголом, маршрутом и радиусами воздействия сценариев (от самых широких к узким).
project_dependencies — предполагаемая граф зависимостей проектов (зависит‑от / на кого зависит) — например, “что зависит от проекта Party?”.
stats — сводные счётчики: проекты, классы, методы, разбор по видам классов, конечные точки и подсчёты ребер.

Получение производится локально по файлу SQLite — детерминировано, оффлайн и отвечает несколькими сотнями токенов. Подробности протокола в specs/codemap-mcp.md; регистрация из исходников и все режимы отказа в docs/troubleshooting.md.

📖 Команды

Команда	Что делает
index []	Анализирует `.sln`/`.csproj` и записывает карту (по умолчанию ./codemap.db).
stats []	Подсчёт сущностей по проекту, unbound/ambiguous шаги, диагностика.
search []	Полнотекстовый поиск по определениям шагов и сценариям.
impact [] --class	--method
report []	Запись автономного HTML-отчета карты.
map []	Запись автономной карты зависимостей проекта (HTML).
validate []	Проверка файла на поддержку TestAtlas map.

Опции и коды возврата

index --output <file> · --config <file> · --include <glob> (повторяемый) · --exclude <glob> (повторяемый) · --verbose · --quiet

search --steps (только определения шагов) · --scenarios (только сценарии)

Коды возврата 0 ok · 1 завершено с предупреждениями · 2 fatal · 3 неверные аргументы

Запуск testatlas --help даёт полный текст справки.

Типичная сессия

# Индекс решения (нет нужды в сборке — проход по синтаксису)
testatlas index YourSolution.sln --output atlas.db

# Прежде чем записать новый шаг — существует ли он уже?
testatlas search atlas.db "add a product to the cart" --steps

# Что произойдет с изменением общего клиента?
testatlas impact atlas.db --class ProductsApiClient

# Делитесь человеко-читаемыми снимками
testatlas report atlas.db --html atlas.html
testatlas map    atlas.db --html atlas-map.html

О встроенном примере (SampleShop)

samples/SampleShop — автономное решение из 8 проектов, сочетающее API-тесты и UI-тесты, поэтому карта содержит множество связанных узлов — реальные клиенты API на базе HttpClient, реальные страницы-объекты Selenium IWebDriver и наборы Reqnroll, управляющие обоими:

┌─▶ 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

🔄 Обновление карты

Ответы детерминированы — но только настолько, насколько актуальна сама карта, поэтому повторная индексация при изменении, а не по расписанию.

Л locally — python scripts/check-map-age.py покажет, что карта устарела; хук Git post-merge может автоматически предупреждать после каждого pull.
В CI (командная модель) — повторная индексация при каждом слиянии в main и публикация .db в общий фид (никогда не коммитьте его — это артефакт сборки). Затем коллеги и агенты локально нуждаются только в TestAtlas.Mcp: загрузите общую карту и укажите TESTATLAS_DB на неё — локальное TestAtlas.Cli и индексация не требуются. (Индексацию выполняйте локально только чтобы учесть ваши незакоммиченные изменения ветки.)

Детали — проверка устаревания, git-хук и инструкции CI (GitHub Actions + Azure DevOps с Universal фидом) — в docs/keeping-the-map-fresh.md.

🧹 Удаление

Две отдельные вещи — удаляйте их в этом порядке, чтобы редактор не запускал сервер, бинарник которого исчез:

Удалить регистрацию MCP — удалите блок testatlas из вашего .mcp.json (<SolutionDir>\.mcp.json или %USERPROFILE%\.mcp.json), затем перезапустите Visual Studio / VS Code. (Или просто отключите её в инструменте агента — это сохранится на потом.)
Удалить инструменты — это глобальные инструменты .NET, а не добавки редактора:

dotnet tool uninstall --global TestAtlas.Mcp
dotnet tool uninstall --global TestAtlas.Cli
dotnet tool list --global            # проверить что их больше нет

(Опционально) удалить файл codemap.db — это просто данные, больше ничего не ссылается на него.

🎯 Принципы дизайна

Без конфигурации — полезная карта для неизвестного решения, без файла конфигурации.
Независимая от решения — эвристическое, переопределяемое обнаружение; никаких корпоративных предположений.
Детерминированная и оффлайн — один и тот же ввод даёт один и тот же смысловой контент; без сети, без ИИ.
Грациозное деградирование — решения без Gherkin всё равно дают полезную карту.
Публичная схема как контракт — версия SQLite-схемы, чтобы downstream-потребители продолжали работать даже если сторонний индексер заменит себя.

Папки проекта используют рабочее имя индекса CodeMap; поставляемые инструменты и пакеты — TestAtlas. Полные спецификации: specs/codemap-indexer.md · specs/codemap-mcp.md. Структура репозитория: CONTRIBUTING.md.

🗺 Дорожная карта

Индексер CLI — индексер на C# + документированная, версионируемая SQLite-схема
HTML-визуализация — автономный отчет + карта проекта, сгенерированные из db
MCP-сервер — testatlas-mcp предоставляет карту AI-агентам через stdio JSON-RPC (11 инструментов)
Второй языковой индексер — та же схема, контрактно-тестируемая

Целенаправленно не планируется (см. принципы дизайна): анализ с помощью LLM внутри индексера, сетевые вызовы на этапах индексации/запроса, создание или тестирование тестов, семантический (с компиляцией) анализ, который потребовал бы восстановления сборки. Выпуски и заметки по версиям размещаются на странице выпусков; текущие каналы распространения — в docs/DISTRIBUTION.md.