Api Test MCP

🚀 API自动化测试框架

YAML声明式API测试框架，专为AI代码助手优化，该框架将测试逻辑与执行代码分离，能有效减少使用AI编写API测试时的重复工作、降低Token消耗并提高调试效率。

快速开始 | MCP集成 | YAML规范 | 单元测试

为何选择此框架？

在让AI编写API测试时，你可能会遇到以下问题：

场景一：重复工作

每次让AI生成测试时，都需要重新描述项目结构、认证方法和断言风格。对于10个API测试，相同的fixture和设置代码会被生成10次。

场景二：Token黑洞

一个简单的登录API测试会生成200行代码。你发现一个断言错误，让AI修复，它又会生成200行代码。经过3次修改，你消耗了2000多个Token，但最终还是需要手动修复。

场景三：调试死循环

AI生成的测试无法运行。你粘贴错误信息，AI修复后仍然错误。经过5轮对话，问题依旧存在，你已经消耗了5000多个Token。

本框架的解决方案

传统方式：自然语言 -> AI生成完整代码 -> 运行错误 -> 粘贴错误信息 -> AI重新生成 -> 循环...
本框架：自然语言 -> AI生成YAML -> 框架执行 -> 定位问题 -> 修复1行YAML

✨ 主要特性

📦 安装指南

安装uv（如果未安装）

curl -LsSf https://astral.sh/uv/install.sh | sh

安装MCP服务器（推荐：作为工具安装）

uv tool install git+https://github.com/GalaxyXieyu/Api-Test-MCP.git

验证安装

api-auto-test-mcp --help

管理工具

uv tool list
uv tool uninstall api-auto-test   # 使用 `uv tool list` 显示的工具名称

不安装直接运行（uvx）

uvx --from git+https://github.com/GalaxyXieyu/Api-Test-MCP.git api-auto-test-mcp --help

⚠️ 重要提示

uvx install ... 是错误的。uvx 将其后的第一个单词视为工具名称，因此它会尝试解析一个名为 install 的包并失败。

配置编辑器

将以下内容添加到编辑器的MCP设置中：

{
  "mcpServers": {
    "api-auto-test": {
      "command": "api-auto-test-mcp"
    }
  }
}

本地开发

# 推荐使用uv
uv pip install -r requirements.txt

# 或者使用pip
pip install -r requirements.txt

💻 使用示例

创建测试用例

# tests/cases/user_login.yaml
testcase:
  name: user_login
  description: User login API test
  host: http://localhost:8000
  steps:
    - id: login
      path: /api/auth/login
      method: POST
      data:
        username: "test_user"
        password: "123456"
      assert:
        - type: status_code
          expected: 200
        - type: equals
          field: data.code
          expected: 0

生成并运行测试

# 生成pytest脚本
python -m atf.case_generator

# 运行测试
pytest tests/scripts/ -v

# 生成Allure报告
pytest tests/scripts/ --alluredir=tests/allure-results
allure serve tests/allure-results

# 生成pytest-html报告
pytest tests/scripts/ --html=report.html

MCP服务器集成

通过MCP，AI编辑器可以直接调用框架工具来生成和执行测试。

效率对比

测试场景：相同的API测试生成任务（纯咨询/分析对话）

核心优势：

• 成本降低54%：MCP直接调用工具，避免了冗长的代码生成上下文
• API响应速度提升64%：工具调用比自然语言交互更高效
• Token消耗减少59%：只需要必要的参数，无需重复项目结构

可用工具

使用示例

告诉AI：

Create a test for /api/users interface, verify returned user list length > 0

AI将调用 write_testcase 生成YAML和相应的pytest脚本。

📚 详细文档

项目结构

api-auto-test/
├── atf/                    # 框架核心
│   ├── core/               # 请求、断言、变量解析模块
│   ├── mcp/                # MCP服务器实现
│   └── handlers/           # 通知、报告处理程序
├── tests/
│   ├── cases/              # YAML测试用例
│   └── scripts/            # 生成的pytest脚本
├── config.yaml             # 项目配置（环境、数据库、通知）
└── pyproject.toml

YAML测试用例规范

基本结构

testcase:
  name: test_name              # 用例名称，用于文件名
  description: Description     # 可选
  host: http://localhost:8000  # API主机，也可在config.yaml中全局配置
  steps:
    - id: step1                # 步骤ID，用于后续引用
      path: /api/endpoint
      method: POST
      headers:
        Authorization: "Bearer {{ login.data.token }}"  # 引用其他步骤的响应
      data:
        key: value
      assert:
        - type: status_code
          expected: 200
        - type: equals
          field: data.id
          expected: 1

断言类型

变量引用

# 引用其他步骤的响应数据
token: "{{ login.data.token }}"

# 引用全局配置
host: "{{ merchant.host }}"

# 调用内置函数
timestamp: "{{ tools.get_timestamp() }}"
uuid: "{{ tools.generate_uuid() }}"

清理操作

testcase:
  name: create_and_delete_user
  steps:
    - id: create_user
      path: /api/users
      method: POST
      data:
        name: "test_user"
  teardowns:
    - id: delete_user
      operation_type: api
      path: /api/users/{{ create_user.data.id }}
      method: DELETE

单元测试

支持为Python代码编写单元测试，通过MCP工具自动生成测试用例。

单元测试YAML格式

unittest:
  name: UserService Test
  target:
    module: app.services.user_service 
    class: UserService
    function: get_user
  fixtures:
    setup:
      - type: patch
        target: app.services.user_service.UserRepository
        return_value:
          id: 1
          name: "test_user"
  cases:
    - id: test_get_user_success
      description: Test get user success
      inputs:
        args: [1]
        kwargs: {}
      assert:
        - type: equals
          field: result.id
          expected: 1
        - type: equals
          field: result.name
          expected: "test_user"

断言类型

配置文件

# config.yaml
projects:
  merchant:
    test:
      host: http://192.168.1.100:8080
      is_need_login: true
      login:
        url: http://192.168.1.100:8080/login
        method: POST
        data:
          username: admin
          password: "123456"
    online:
      host: https://api.example.com
      is_need_login: true

notifications:
  dingtalk:
    webhook: "https://oapi.dingtalk.com/robot/send?access_token=xxx"
    secret: "SECxxx"

📄 许可证

本项目采用MIT许可证。

链接

• GitHub
• 问题报告