Swagger Testcase MCP

swagger-testcase-mcp

用于 API 测试的 MCP 服务：根据 Swagger/OpenAPI 规范生成测试用例、验证规范、比较版本并创建模拟数据。

输入 API 规范 URL，即可获得结构化、分类的测试用例（正向、负向、边界、认证、安全、幂等性、分页），可直接用于手动测试或导入 TMS。

为什么要用

• 手动编写测试用例很耗时。 一个包含 10 多个参数的端点，可能需要针对正向、负向、边界和安全场景编写 30–50 个测试用例。若有数十个端点，日常工作就会耗费数天，而不是专注于实际测试。
• 负向和边界用例容易被跳过。 截止日期紧迫时，QA 会专注于正常流程。边缘情况、无效输入和安全检查最先被删减，也最容易引发生产事故。
• 规范的变化快于测试文档，内部 API 也容易被忽视。 新端点、重命名字段、变更约束——让测试用例保持同步需要持续投入。VPN 或自定义认证后面的企业 API 更难处理，因为大多数工具都不支持经过身份验证的规范访问。
• 将测试用例导入 TMS 需要额外步骤。 即使编写了出色的测试用例，将其整理成适用于 TestRail、Allure 或 Postman 导入的格式，也是一项繁琐且没有附加价值的工作。

此工具可自动完成基础工作：将任意 Swagger/OpenAPI 规范（公共、内部或 localhost）交给它，几秒内即可获得分类测试用例，并保存为可直接导入 TMS 或测试运行器的文件。你可以专注于业务逻辑和探索性测试，其余工作交给工具处理。

功能

• 解析 Swagger 2.0 和 OpenAPI 3.x — 支持 JSON 和 YAML
• 智能生成测试用例 — 分析参数、架构、约束、响应代码和安全设置，生成相关测试用例
• 8 类测试用例 — 正向、负向、边界、授权、业务逻辑、安全注入、幂等性、分页与排序
• 9 种导出格式 — Markdown、JSON、CSV、Allure CSV、Gherkin、Postman、k6、pytest、TestRail CSV（两种模板：Steps 和 Text）
• 规范验证 — 根据 11 条规则进行质量评分，并提供可执行的建议
• 规范比较 — 对比两个版本并检测破坏性变更
• 模拟数据生成 — 根据架构生成逼真的测试数据，并支持区域设置
• 覆盖率分析 — 找出测试覆盖率中的缺口，并提供优先级建议
• 自动保存到文件 — 导出内容会自动保存到工作目录，无需手动复制粘贴
• 可配置生成 — 按类别、优先级、区域设置和自定义前置条件筛选
• 批量生成 — 按标签、HTTP 方法、路径前缀和弃用状态筛选
• 兼容任意 MCP 客户端 — Claude Desktop、Cursor、VS Code + Cline 等

生成的测试用例类别

安装

npm install -g swagger-testcase-mcp

或使用 npx 直接运行：

npx swagger-testcase-mcp

配置

{
  "mcpServers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "mcpServers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "servers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "swagger-testcase-mcp": {
    "command": "npx",
    "args": ["-y", "swagger-testcase-mcp"]
  }
}

{
  "servers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

{
  "mcpServers": {
    "swagger-testcase-mcp": {
      "command": "npx",
      "args": ["-y", "swagger-testcase-mcp"]
    }
  }
}

快速开始

1. "Load the spec from https://petstore3.swagger.io/api/v3/openapi.json"
2. "Generate test cases for POST /pet"
3. "Export as Postman collection"

以下是生成结果的示例（Markdown 导出）：

## Positive Tests (1)

### TC-001: POST /pet — happy path with required fields only

- **Priority:** high
- **Preconditions:** Valid authentication credentials are available
- **Steps:**
  1. Send POST request to /pet
  2. Include only required parameters/fields with valid values
  3. Verify response status and body
- **Input:** `{"name":"Buddy","photoUrls":["https://example.com/photo.jpg"]}`
- **Expected Result:** Returns success response with expected data
- **Expected Status:** 200

## Negative Tests (2)

### TC-002: POST /pet — missing required field "name"

- **Priority:** high
- **Preconditions:** Valid authentication credentials are available
- **Steps:**
  1. Send POST request to /pet
  2. Omit required field "name"
  3. Verify error response
- **Input:** `{"_omit":"name"}`
- **Expected Result:** Returns validation error indicating "name" is required
- **Expected Status:** 422

### TC-003: POST /pet — invalid type for "name"

- **Priority:** medium
- **Preconditions:** Valid authentication credentials are available
- **Steps:**
  1. Send POST request to /pet
  2. Set "name" to invalid type value: 12345
  3. Verify error response
- **Input:** `{"name":12345}`
- **Expected Result:** Returns validation error for invalid type of "name"
- **Expected Status:** 422

生成器会生成涵盖 8 个类别的测试用例（正向、负向、边界、身份验证、业务逻辑、安全、幂等性、分页）——上面的示例只展示了其中一小部分。使用 generate_test_cases_batch 一次覆盖整个 API。

如需查看每种工具和工作流的详细示例，请参阅 EXAMPLES.md。

可用工具

生成配置

所有生成工具都接受可选的 config 参数：

{
  "config": {
    "categories": ["positive", "negative", "security"],
    "priorityFilter": ["high"],
    "maxFieldsForNegative": 15,
    "locale": "ru",
    "customPreconditions": ["Database seeded with test data"],
    "skipDeprecated": true
  }
}

导出到文件

所有导出内容都会自动保存到工作目录。文件名根据端点和格式生成：

test-cases_POST__pet_postman.json
test-cases_GET__users_testrail_csv.csv
test-cases_POST__orders_k6.js

你也可以指定自定义路径：

"Export as postman to /path/to/my-collection.json"

局限性

该工具根据 OpenAPI 规范中描述的内容生成测试用例，包括参数、架构、约束、响应代码和安全定义。它不涵盖以下内容：

• 业务逻辑 — 例如“非管理员用户的折扣不能超过 50%”或“订单至少需要一件有库存的商品”等规则不属于规范的一部分，因此不会自动生成测试用例
• 端点间依赖关系 — 该工具会单独处理每个端点，不会生成“创建用户 → 创建订单 → 检查状态”这类调用链
• 自定义验证规则 — 不会检测 OpenAPI 不支持的约束（例如条件字段要求、跨字段验证）

**补救方法：**由于该工具在 MCP 客户端（Claude、Cursor 等）中运行，你可以在聊天中描述业务规则，并让大模型扩展或调整生成的测试用例。该工具提供基线，大模型补充上下文。

**提示：**OpenAPI 规范越完善（约束、枚举、示例、描述），生成的测试用例就越切合实际。使用 validate_spec 检查规范质量并获取改进建议。

支持的来源

适用于任何 Swagger/OpenAPI 规范——公共规范、企业内网规范、本地主机上的规范或本地文件。

公共和本地规范

"Load the spec from https://petstore3.swagger.io/api/v3/openapi.json"
"Load the spec from /path/to/swagger.json"
"Load the spec from ./api-spec.yaml"
"Load the spec from http://localhost:8080/v3/api-docs"

企业内部 API

访问 VPN、SSO 或内网中经过身份验证的规范：

"Load the spec from https://internal-api.company.com/docs/swagger.json with auth_header Bearer eyJhbGci..."

{
  "source": "https://internal-api.company.com/docs/swagger.json",
  "auth_header": "Bearer eyJhbGciOiJIUzI1NiIs..."
}

{
  "source": "https://internal-api.company.com/docs/swagger.json",
  "auth_header": "Basic dXNlcjpwYXNz"
}

{
  "source": "https://internal-api.company.com/docs/swagger.json",
  "headers": { "X-API-Key": "abc123" }
}

**提示：**如果规范位于企业 VPN 后，请确保 MCP 服务进程可以访问内部 URL。服务在本地运行，因此你计算机上的 VPN 或代理设置会自动生效。

与 TMS 集成

Allure TestOps

1. 生成测试用例，并导出为 allure_csv
2. 使用 Allure TestOps 迁移工具导入（配置 fieldMapping，使其与下方列匹配）
3. 列：名称、描述、前置条件、步骤、预期结果、层级、标签
4. 或与 Allure TestOps MCP 服务结合，直接通过 API 创建测试用例

**注意：**从 25.3.4 版本开始，Allure TestOps UI 已移除 CSV 导入功能。请改用迁移工具或 API 集成。

"Generate test cases for POST /pet"
"Export as allure_csv"

TestRail

提供两种导出格式：

• testrail_csv — 步骤模板（每个步骤一行）。预期结果会附加到每个测试用例的最后一步；中间步骤的预期结果为空。
• testrail_csv_text — 文本模板（所有步骤放在一个字段中）。更简单，适用于任何 TestRail 配置。

步骤模板（推荐）：

1. 导出为 testrail_csv
2. 在 TestRail 中，前往 测试用例 → 从 CSV 导入
3. 选择“测试用例（步骤）”模板
4. 映射列：标题、部分、类型、优先级、前置条件、步骤、预期结果

"Generate test cases for all endpoints tagged 'users'"
"Export as testrail_csv"

文本模板：

"Export as testrail_csv_text"

通用 CSV（Qase、Zephyr、TestLink 等）

大多数 TMS 平台都支持 CSV 导入。使用 csv 格式，并在导入过程中将列映射到 TMS 字段。

• Qase — 映射 title、preconditions、steps、expected_result、priority
• Zephyr Scale — 映射 Name、Precondition、Test Script (Plain Text)、Priority、Folder
• TestLink — 使用标准 CSV 导入向导

"Generate test cases for GET /users"
"Export as csv"

使用 Postman

导入为 Postman 集合

生成测试用例，并导出为 Postman Collection v2.1，可直接导入 Postman，或通过 Newman 在 CI 中运行：

"Load the spec from https://internal-api.company.com/docs/swagger.json with auth_header Bearer eyJ..."
"Generate test cases for POST /users"
"Export as postman"

导出的集合包括：

• 按测试类别整理的文件夹（正向、负向、安全等）
• 为每个测试用例预先配置的 HTTP 方法、URL、标头和请求正文
• 自动生成的测试脚本，其中包含预期状态代码断言

导入到 Postman

1. 打开 Postman → 导入 → 拖入导出的 JSON 文件
2. 集合中会显示每个端点对应的文件夹
3. 设置一个环境，并将 baseUrl 变量指向你的 API

使用 Newman 运行（CI）

newman run exported-collection.json \
  --environment env.json \
  --reporters cli,junit

开发

git clone https://github.com/eyaushev/swagger-testcase-mcp.git
cd swagger-testcase-mcp
npm install
npm run build
npm test
npm start

许可证

MIT