Api Test MCP

🚀 API自動テストフレームワーク

YAML宣言型APIテストフレームワーク、AIコーディングアシスタントに最適化

このフレームワークは、AIにAPIテストを生成させる際の問題を解決します。YAML宣言型のテスト方式を採用し、AIが生成するのは構造化データのみで、テストの実行コードと分離されています。

クイックスタート | MCP統合 | YAMLテストケース仕様 | 単体テスト

なぜこのフレームワークなのか？

AIにAPIテストを書かせる際、以下のような問題に遭遇することがあります。

シナリオ1: 重複作業

AIにテストを生成させるたびに、プロジェクト構造、認証方法、アサーションスタイルを再度説明する必要があります。10個のAPIテストを生成する場合、同じフィクスチャとセットアップコードが10回生成されます。

シナリオ2: トークンブラックホール

単純なログインAPIテストで200行のコードが生成されます。アサーションが間違っていることに気づき、AIに修正してもらうと、また200行のコードが生成されます。3回の修正で2000以上のトークンを消費し、結局手動で修正することになります。

シナリオ3: デバッグの無限ループ

AIが生成したテストが実行できない場合、エラーメッセージを貼り付けてAIに修正してもらっても、依然として間違っています。5回の会話の後も問題は解決せず、5000以上のトークンを消費します。

このフレームワークの解決策

従来: 自然言語 -> AIが完全なコードを生成 -> 実行エラー -> エラーを貼り付け -> AIが再生成 -> ループ...
このフレームワーク: 自然言語 -> AIがYAMLを生成 -> フレームワークが実行 -> 問題を特定 -> 1行のYAMLを修正

✨ 主な機能

🚀 クイックスタート

インストール

# 1. uvをインストールする（未インストールの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 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%向上: ツール呼び出しは自然言語対話よりも効率的です。
• トークン消費量59%削減: 必要なパラメータのみを指定すればよく、プロジェクト構造を繰り返し説明する必要がありません。

利用可能なツール

使用例

AIに以下を伝えます。

/api/usersインターフェースのテストを作成し、返されるユーザーリストの長さが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
• 問題報告