Karzone/TestAtlas
GitHub: Karzone/TestAtlas
TestAtlas 是一个将 .NET 测试自动化解决方案静态分析为可查询 SQLite 语义映射图的工具，帮助人类和 AI 代理精准导航测试代码并分析变更影响。
Stars: 2 | Forks: 0
TestAtlas
将您的 .NET 测试自动化解决方案转化为一个可查询的语义映射图——全部封装在一个 SQLite 文件中，并通过 MCP 提供给您的 AI 代理。
零配置 · 无需 AI · 无需网络 · 结果确定
MCP 工具
stats · impact · search_steps · search_scenarios · list_endpoints
快速开始 ·
命令 ·
MCP ·
示例 ·
保持最新 ·
路线图
## ⚡ 添加到您的 AI 代理
```
dotnet tool install --global TestAtlas.Mcp # the MCP server (and TestAtlas.Cli to build maps)
```
通过 `.mcp.json` 将您的代理指向它——**Visual Studio**、**VS Code / Copilot** 或 **Claude Code**：
```
{ "servers": { "testatlas": { "type": "stdio", "command": "testatlas-mcp" } } }
```
首先运行 `testatlas index
`，以便生成可供使用的 `codemap.db`。完整的设置——包括代理注册、映射图自动发现以及从源码运行——请参见
**[从 AI 代理中使用](#-use-it-from-an-ai-agent-mcp)**。
## 功能简介
TestAtlas 对 .NET 测试自动化解决方案进行静态分析，并生成一份**语义映射图**——
`codemap.db`，一个单独的 SQLite 文件——其中包含：
- **项目**及其依赖关系边
- **Gherkin** 的功能、场景和步骤
- **步骤定义**及其绑定状态（已绑定 / 未绑定 / 模糊不清）
- **页面对象、API 客户端、辅助类和测试类**
- 连接它们的**调用和使用关系边**
……并将该映射图转化为精准的答案：
| | 功能 | 您将获得 |
|:--:|---|---|
| 🔍 | **搜索** | 对步骤定义和场景进行 FTS5 全文检索——*“是否已存在针对此操作的步骤？”* |
| 💥 | **影响分析** | 爆炸半径——修改类、方法、步骤或 endpoint 后受影响的场景 |
| 📊 | **报告** | 整个映射图的自包含 HTML 深度分析报告 |
| 🕸️ | **映射图** | 自包含的项目依赖关系图 (HTML) |
| 🔌 | **MCP** | 通过 stdio 将映射图提供给 AI 代理——无需填充上下文 |
| 📈 | **统计** | 实体计数、类类别细分、绑定覆盖率、诊断信息 |
所有操作均**离线、确定且可重现**——相同的输入，每次都能得到相同的映射图。
## 为什么需要它
大型测试自动化解决方案对人类*和* AI 代理来说都难以导航。当被要求实现一个新故事时，代理无法看到类似代码的位置、已存在哪些步骤，或者解决方案遵循什么规范。因此，它会重复创建步骤并错误地放置代码。
TestAtlas 只需对解决方案进行**一次**索引，就能为人和代理提供一个结构化的映射图，从而
确定性地回答这些问题——无需依赖模型或进行网络调用。
## 🚀 快速开始
从 NuGet 将 CLI 作为全局 .NET 工具安装：
```
dotnet tool install --global TestAtlas.Cli
```
……然后，从任何目录运行：
```
# 索引 solution → 生成 ./codemap.db
testatlas index path/to/YourSolution.sln
# 探索它
testatlas stats
testatlas search "login"
testatlas report # writes codemap.html
testatlas map # writes codemap-map.html
```
不带路径运行 `index`——或将其指向一个**文件夹**——TestAtlas 将自动发现其中的单个
`.sln`/`.csproj`。映射图将以原子方式写入 `./codemap.db`。
或者从源码运行（无需安装）
```
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
```
## 🛠️ 故障排除
在公司机器上执行 dotnet tool install 失败并提示 401 Unauthorized
如果您的机器配置了私有的、需要身份验证的 NuGet 源（例如 Azure DevOps Artifacts），
`dotnet` 将在安装过程中查询**每个**已注册的源，并在私有源上失败并提示 **401**
——即使 TestAtlas 已发布在公共的 nuget.org 上。
请仅使用 nuget.org 进行安装。创建一个最小化的 `public.config`：
```
```
……然后在安装时指向它：
```
dotnet tool install --global TestAtlas.Cli --configfile ./public.config
dotnet tool install --global TestAtlas.Mcp --configfile ./public.config
```
`` 会丢弃所有继承的源（包括私有源），因此 `dotnet` 只会看到
nuget.org。这是一个一次性覆盖——它不会更改您机器的 NuGet 配置，也不会影响其他项目的私有源。
## 📖 命令
| 命令 | 功能 |
| --- | --- |
| `index []` | 分析 `.sln`/`.csproj` 并写入映射图（默认为 `./codemap.db`）。 |
| `stats []` | 每个项目的实体计数、未绑定/模糊步骤、诊断信息。 |
| `search [] ` | 对步骤定义和场景进行 FTS5 全文检索。 |
| `impact [] --class\|--method\|--step\|--endpoint ` | 爆炸半径：修改实体后受影响的场景。 |
| `report []` | 生成映射图的自包含 HTML 深度分析报告。 |
| `map []` | 生成自包含的项目依赖关系图 (HTML)。 |
| `validate []` | 检查文件是否为受支持的 TestAtlas 映射图。 |
选项 & 退出代码
**`index`** `--output ` · `--config ` · `--include ` (可重复) · `--exclude ` (可重复) · `--verbose` · `--quiet`
**`search`** `--steps` (仅步骤定义) · `--scenarios` (仅场景)
**退出代码** `0` 成功 · `1` 完成但有警告 · `2` 致命错误 · `3` 参数错误
运行 `testatlas --help` 获取完整的用法说明。
## 🧭 示例工作流
```
# 1. （可选）构建 solution — 参见下方的说明；无论哪种方式，生成的 map 都是相同的
dotnet build YourSolution.sln
# 2. 索引它
testatlas index YourSolution.sln --output atlas.db
# 3. 在编写新步骤之前 — 是否已经存在？
testatlas search atlas.db "add a product to the cart" --steps
# 4. 准备更改 shared client — 它会影响到什么？
testatlas impact atlas.db --class ProductsApiClient
# 5. 共享人类可读的 snapshot
testatlas report atlas.db --html atlas.html
# 6. 查看 projects 之间如何相互依赖
testatlas map atlas.db --html atlas-map.html
```
## 🔌 从 AI 代理中使用 (MCP)
TestAtlas 内置了一个 MCP 服务器——`testatlas-mcp`——它可以通过 stdio JSON-RPC 将映射图提供给任何支持 MCP 的客户端
（Claude Code 和其他代理）。代理提出精确的问题，并直接从 `.db` 获得准确、结构化的答案——而无需将源文件硬塞进其
上下文窗口。
它作为 **MCP-server 包** (`TestAtlas.Mcp`) 发布在 NuGet 上，因此支持 MCP 的编辑器可以
发现并启动它。映射图路径是**可选的**——服务器会自动发现当前工作目录下的 `codemap.db`
（或 `atlas.db`），或者读取 `TESTATLAS_DB` 环境变量。
**Visual Studio / VS Code**（GitHub Copilot 代理模式）——添加到您的 `.mcp.json` (`%USERPROFILE%\.mcp.json`
或 `\.mcp.json`)：
```
{
"servers": {
"testatlas": {
"type": "stdio",
"command": "dnx",
"args": ["TestAtlas.Mcp", "--yes"]
}
}
}
```
`dnx`（来自 .NET 10 SDK）会按需获取并运行服务器——无需预安装。从包含 `codemap.db` 的文件夹启动它，
它会自动被识别；否则，将路径作为最后一个参数附加。在 Visual Studio 中，您也可以使用
**Tools picker → `+` → Add custom MCP server** 来为您写入此条目。
**Claude Code**——安装全局工具并注册它：
```
dotnet tool install --global TestAtlas.Mcp
claude mcp add testatlas -- testatlas-mcp # run where a codemap.db lives, or append a path
claude mcp list # the testatlas row should read: ✔ Connected
```
默认情况下，服务器会为**当前项目**注册（`--scope local`）。添加
`--scope user` 可使其在您机器上的每个项目中均可用，或者使用 `--scope project` 通过提交的
`.mcp.json` 与您的团队共享注册信息。
或者从源码运行（无需安装）
```
dotnet build src/CodeMap.Mcp -c Release
# 在 Windows 上，二进制文件是 TestAtlas.Mcp.exe；在 macOS/Linux 上是 TestAtlas.Mcp
claude mcp add testatlas -- src/CodeMap.Mcp/bin/Release/net8.0/TestAtlas.Mcp.exe path/to/codemap.db
```
**暴露的工具：**
- `stats` — 汇总计数：项目、类、方法、类类别细分、endpoint 以及关系边统计。
- `impact` — 修改的爆炸半径：受给定类、方法、步骤定义或 endpoint 影响的场景。
- `search_steps` — 对步骤定义进行全文检索（表达式文本 + 方法 + 类名）。
- `search_scenarios` — 对场景进行全文检索（功能 + 场景名称 + 步骤文本 + 标签）。
- `list_endpoints` — 测试套件调用的 HTTP endpoint，包含动词、路由以及场景爆炸半径（按影响范围从大到小排序）。
## 🔎 在真实示例中查看
该仓库附带了一个自包含的示例解决方案——[`samples/SampleShop`](samples/SampleShop)——一个
包含 **8 个项目**的真实布局，混合了 **API 测试和 UI 测试**，因此映射图拥有大量
相连的节点，并同时演练了 API 客户端映射（真实的 `HttpClient` 客户端）和页面对象映射（真实的 Selenium `IWebDriver` 页面）：
```
┌─▶ Api.Catalog ──┐
Tests.Api ────────────┼─▶ Api.Cart ──┤
Tests.E2E ──┬─────────┴─▶ Api.Identity ──┼─▶ Core (ApiClientBase : HttpClient)
└─▶ Ui.Pages ─────────────────┘ (PageBase : IWebDriver)
Tests.Ui ────▶ Ui.Pages ──────────────────▶ Core
```
| 项目 | 角色 |
|---|---|
| **Core** | 每个客户端/页面继承的基础类型（入度最高 → 节点最大） |
| **Api.Catalog / Api.Cart / Api.Identity** | 基于 `HttpClient` 的 API 客户端 |
| **Ui.Pages** | Selenium 页面对象 (Login / Checkout / Product) |
| **Tests.Api / Tests.Ui / Tests.E2E** | 步骤驱动客户端和页面的 Reqnroll 测试套件 |
由该工具从该解决方案生成的两个已提交输出——映射图显示了 **8 个项目和
11 个依赖关系**：
📊 **[示例报告](https://htmlpreview.github.io/?https://github.com/Karzone/TestAtlas/blob/main/docs/sample-report.html)** — 功能、场景、步骤绑定、类类别、API endpoint
🕸️ **[示例依赖关系图](https://htmlpreview.github.io/?https://github.com/Karzone/TestAtlas/blob/main/docs/sample-map.html)** — 这八个项目及它们之间的边
亲自重现它们
```
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
```
## 🔄 保持映射图最新
TestAtlas 的答案是确定的——但其新鲜度仅取决于映射图。每当源代码发生更改时，请重新索引，
这样查询就永远不会返回*确定的过期*答案。
### 检查映射图是否过期
```
python scripts/check-map-age.py [path/to/map.db] # defaults to ./codemap.db, then ./atlas.db
```
它会读取映射图的 `generated_utc` + `solution_path`，然后扫描**已编写**的源代码
(`*.cs` / `*.feature`) 以查找之后被修改的内容——同时忽略生成的文件
(`*.feature.cs`, `*.g.cs`, `*.designer.cs`)、`bin`/`obj` 以及任何嵌套的解决方案。
| 退出代码 | 含义 |
|:--:|---|
| `0` | **最新** — 自映射图构建以来没有源代码更改 |
| `1` | **过期** — 重新运行 `testatlas index` |
| `2` | **无映射图** — 没有可检查的内容 |
*(需要 Python 3，仅使用标准库——可在 Windows、macOS、Linux 上运行。)*
### 每次拉取后自动发出警告 (git hook)
受版本控制的 `post-merge` hook 会在每次合并 / `git pull` 之后运行检查——它只会
打印信息，绝不会阻塞操作：
```
git config core.hooksPath scripts/hooks # enable once, per clone
```
该 hook 会自动检测仓库根目录下的 `codemap.db` / `atlas.db`，或者通过
`export TESTATLAS_DB=/path/to/your/map.db` 显式指定。
### 重新索引的频率
完全重新索引只是一次静态遍历——只需**几秒钟**——其成本与**解决方案大小成正比，
而与更改的多少无关**。因此，应在*发生更改时*重新索引，而不是定时执行：
- **在本地**——hook 会告诉您映射图何时发生偏移；发生偏移时请运行 `testatlas index`。
- **在 CI 中**——每次合并到主分支时都进行重新索引，并将映射图作为构建产物发布
（不要提交二进制 `.db` 文件）。
### 在 CI 中重新索引（适用于任何提供商）
三个步骤：**安装工具 → 运行 `testatlas index` → 发布 `.db` 产物。**
GitHub Actions — .github/workflows/testatlas.yml
Azure DevOps — azure-pipelines.yml
```
trigger:
branches:
include: [ main ]
pool:
vmImage: ubuntu-latest
steps:
- task: UseDotNet@2
inputs:
packageType: sdk
version: '8.0.x'
- script: dotnet tool install --global TestAtlas.Cli
displayName: Install TestAtlas
- script: testatlas index YourSolution.sln --output codemap.db
displayName: Index solution
- publish: codemap.db
artifact: testatlas-map
```
任何其他 CI（GitLab CI、Jenkins、TeamCity、CircleCI）均遵循相同的三个步骤。
## 📁 项目布局
```
TestAtlas/
├─ src/
│ ├─ CodeMap.Core/ # analysis engine, model, SQLite storage, HTML builders
│ ├─ CodeMap.Cli/ # thin CLI wrapper — packs as the `testatlas` dotnet tool
│ └─ CodeMap.Mcp/ # MCP server — packs as `testatlas-mcp`
├─ tests/
│ ├─ CodeMap.Tests/ # unit / integration tests
│ └─ fixtures/ # synthetic Reqnroll / SpecFlow / broken-solution shims
├─ samples/ # real projects to point the tool at (SampleShop, ReqnrollLoginDemo)
├─ docs/ # committed sample report + dependency map (HTML)
├─ scripts/ # check-map-age.py + git hooks (map freshness / staleness)
├─ specs/ # codemap-indexer.md, codemap-mcp.md — the full specifications
└─ TestAtlas.sln
```
完整规范请参见 [`specs/codemap-indexer.md`](specs/codemap-indexer.md)：
实体模型、分类启发式算法、CLI 界面、SQLite 架构契约、性能
目标以及验收标准。
## 🎯 设计原则
- **零配置**——无需配置文件，即可对未知解决方案生成有用的映射图。
- **解决方案无关**——启发式、可覆盖的检测；没有针对特定公司的假设。
- **确定性且离线**——相同的输入 ⇒ 字节等价的逻辑内容；无需网络，无需 AI。
- **优雅降级**——没有 Gherkin 的解决方案仍然可以产生有用的映射图。
- **公开架构作为契约**——版本化的 SQLite 架构，即使第三方更换了自己的索引器，下游消费者依然可以正常工作
## 🗺️ 路线图
- [x] **索引器 CLI** — C# 索引器 + 已记录并版本化的 SQLite 架构 *(v0.1)*
- [x] **HTML 可视化** — 从数据库生成自包含报告和项目映射图
- [x] **MCP 服务器** — `testatlas-mcp` 通过 stdio JSON-RPC 向 AI 代理暴露映射图
- [ ] **第二语言索引器** — 相同架构，经过契约测试
## 📄 许可证
[MIT](LICENSE) © 2026 Karthik Kalaiyarasu 标签：MCP, SQLite, 云安全监控, 代码分析, 凭证管理, 威胁情报, 开发者工具, 静态分析