TestAtlas

 TestAtlas

以一个 SQLite 文件构建可查询的 .NET 测试自动化解决方案语义地图，并通过 MCP 提供给你的 AI Agent。

零配置  ·  无 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 Agent 都是如此。面对自动化新故事的任务时，Agent 无法看出哪些步骤已经存在、相似代码在哪里，或解决方案遵循哪些约定，因此会重复创建步骤并将代码放错位置。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))

……或者让你的 Agent 通过 MCP 提问。这里，Agent 会检查即将编写的步骤是否已经存在——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 报告（功能、场景、绑定、类类型、端点） · 依赖关系图（将八个项目分层展示——点击项目即可查看它使用了什么、哪些项目依赖它，以及变更可能影响哪些测试）。 _{（GitHub 会将 .html 作为源文件提供，因此链接会通过 htmlpreview.github.io 跳转；也可以从 docs/ 下载并在本地打开。）}

你将获得什么

TestAtlas 会静态分析解决方案并生成 codemap.db——其中包含项目及其依赖边、Gherkin 功能/场景/步骤、步骤定义及其绑定状态（已绑定 / 未绑定 / 有歧义）、页面对象、API 客户端、辅助工具、测试类，以及连接它们的调用/使用边——然后将这张图谱转化为答案：

所有功能都离线运行、结果确定且可复现——相同输入，每次都会生成相同图谱。

🚀 快速开始

需要 .NET SDK 8.0+。如果在公司电脑上运行 dotnet tool install 时出现 401 错误，请参阅 docs/troubleshooting.md。

1 — 安装 CLI（如果要连接 Agent，也安装 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        # writes codemap.html
testatlas map           # writes codemap-map.html

……若要将其提供给 AI Agent，请继续阅读 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 Agent 使用（MCP）

TestAtlas 附带 MCP 服务 testatlas-mcp，可通过 stdio JSON-RPC 将图谱提供给任何支持 MCP 的客户端 （Visual Studio / VS Code Copilot、Claude Code 等）。Agent 提出精确问题后，就能直接从 .db 获得准确、结构化的答案，而无需将源文件塞进上下文窗口。

前提条件：已安装这两个工具并建立图谱——即快速开始的第 1–2 步。然后注册服务：

Visual Studio / VS Code（GitHub Copilot Agent 模式）——将以下内容添加到 .mcp.json （%USERPROFILE%\.mcp.json 或 <SolutionDir>\.mcp.json）：

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

明确指定图谱路径（如上所示，或通过 TESTATLAS_DB 环境变量指定）——大多数 Agent 会从自己的工作目录启动服务，而不是从你的解决方案文件夹启动，因此依赖自动发现会导致服务找不到图谱：服务会启动并列出工具，但每次调用都会返回错误，说明如何指定图谱（0.1.11 之前的版本则会以 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 — 作为插件（服务、用于说明何时使用哪个工具的技能、/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 — 单个服务，无需插件：

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 客户端会在会话启动时加载服务 — 如果你在会话中途注册，请重启 Agent 会话，然后 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 端点，每项包含方法、路由和场景影响范围（按影响范围从高到低排列）。
• project_dependencies — 推断出的项目依赖关系图（依赖于 / 被依赖于），例如 “哪些项目依赖 Party 项目？”。
• stats — 汇总计数：项目、类、方法、类类型细分、端点和边的统计。

检索在本地针对 SQLite 文件运行 — 结果确定、离线，每个答案只需数百个 token。协议详情见 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

🔄 保持映射最新

查询结果是确定性的，但前提是映射足够新鲜，因此应在发生更改时重新索引，而不是定时执行。 完整重新索引只需一次静态扫描（几秒钟），其耗时取决于解决方案的大小，而不是更改的范围：

• 本地 — python scripts/check-map-age.py 会提示映射何时已过时；设置受版本控制的 post-merge git 钩子，即可在每次拉取后自动发出警告。
• 在 CI 中（团队模式） — 每次合并到 main 时重新索引，并将 .db 发布到共享源 （切勿提交该文件——它是构建产物）。这样，队友和 Agent 只需在本地安装 TestAtlas.Mcp： 下载共享映射并将 TESTATLAS_DB 指向它即可——无需本地安装 TestAtlas.Cli，也无需索引。 （仅在需要包含自己尚未提交的分支更改时，才在本地进行索引。）

详细信息——过时检查器、git 钩子，以及可直接复制粘贴的 CI 配置示例（GitHub Actions + Azure DevOps 搭配 Universal 源）——请参阅 docs/keeping-the-map-fresh.md。

🧹 卸载

需要分别处理两项内容——请按以下顺序移除，以免编辑器启动一个可执行文件刚被删除的服务：

1. 移除 MCP 注册 — 从 .mcp.json（<SolutionDir>\.mcp.json 或 %USERPROFILE%\.mcp.json）中 删除 testatlas 块，然后重启 Visual Studio / VS Code。 （或者，在 Agent 的工具/扳手选择器中将其关闭，以便以后继续使用。）
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 Agent 提供映射（11 个工具）
• 第二种语言的索引器 — 使用相同的架构，并通过契约测试

有意不纳入计划的内容（参见设计原则）：在索引器中借助大模型进行分析、在索引或查询时发起网络调用、运行或生成测试，以及需要还原构建的语义（基于编译）分析。版本发布和各版本说明见发布页面；当前分发渠道见 docs/DISTRIBUTION.md。

📄 许可证

MIT © 2026 Karthik Kalaiyarasu