@ri-lab/api-test-engine

汎用 API 自動テストエンジン。
テスト仕様 JSON を渡すだけで HTTP リクエストを実行し、期待値と比較した結果（差分と証跡ログを含む）を JSON で返します。

特長

• fetch/axios などのコード生成に依存せず、固定ロジックで安定動作
• GET/POST/PUT/DELETE に対応
• ネスト対応の JSON 一致判定（オブジェクトは「部分一致（subset）」で比較、配列は同順・同数で比較）
• 期待値と実際値の差分を返却（bodyDiff）
• タイムアウト・JSON パース失敗などのエラーハンドリング
• 証跡（evidence）出力：リクエスト/レスポンス/トレースログをJSONで返却

インストール（任意）

MCP から npx 実行する場合はインストール不要です。ローカルに導入する場合のみ以下を使用してください。

npm install @ri-lab/api-test-engine

テスト仕様 JSON 例

MCP経由で実行する場合は、テストケースの配列を渡します。単一のテストケースでも配列形式で指定してください。

[
  {
    "name": "ユーザー取得APIのテスト",
    "testCaseId": "user-get-001",
    "__meta": {
      "sourceFileName": "user-api-tests.json"
    },
    "request": {
      "method": "GET",
      "url": "https://example.com/api/user/123",
      "headers": {
        "Authorization": "Bearer token"
      },
      "timeout": 10000
    },
    "expected": {
      "status": 200,
      "body": {
        "id": 123,
        "name": "John"
      }
    }
  },
  {
    "name": "ユーザー作成APIのテスト",
    "testCaseId": "user-post-001",
    "__meta": {
      "sourceFileName": "user-api-tests.json"
    },
    "request": {
      "method": "POST",
      "url": "https://example.com/api/user",
      "body": {
        "name": "John"
      },
      "timeout": 10000
    },
    "expected": {
      "status": 201,
      "body": {
        "name": "John"
      }
    }
  }
]

注意: 単一のテストケースでも配列形式（[{ ... }]）で指定する必要があります。

テストケース仕様

必須フィールド

• __meta.sourceFileName: 元のJSONファイル名（必須）。出力ディレクトリの生成に使用されます
• request.url: リクエスト URL（必須）

任意フィールド

• testCaseId: テストケースID（省略可、自動生成されます）
• name: テストケース名（任意）

リクエスト仕様

• method: GET|POST|PUT|DELETE（省略可、既定は GET）
• url: リクエスト URL（必須）
• headers: 任意ヘッダー
• params: クエリパラメータ（オブジェクト）
• body: リクエストボディ（POST/PUT などで使用）
• timeout: タイムアウト ms（省略可、既定 10000）

期待値仕様

• status: 期待する HTTP ステータスコード（数値）
• body: 期待するレスポンス JSON
  • オブジェクトは「部分一致（subset）」比較：expected.body に含まれるキーがすべて一致すれば OK。実際値に余分なキーがあっても無視
  • 配列は同順・同数で比較

実行結果

出力ファイル

テスト実行後、以下のファイルが生成されます：

1. result.html: 日本語化されたPostman風のHTMLレポート

   • タブ形式でリクエスト/レスポンス/アサーション結果を表示
   • 統計情報（総テスト数、成功数、失敗数、実行時間）を表示
   • 各テストケースの詳細情報を視覚的に表示

2. log.md: 実行ログ（Markdown形式）

   • 実行開始/終了時刻
   • 各テストケースのリクエスト/レスポンス/検証結果
   • トレース情報

出力ディレクトリ

テスト結果は以下のディレクトリに保存されます：

{API_TEST_OUTPUT_BASEまたはprocess.cwd()}/mcp-results/{ファイル名}/{yyyyMMdd-HHmm}/

例: C:\api-test-engine\mcp-results\user-api-tests\20251124-1438\

実行結果の形式（MCP返却値）

MCP経由で実行した場合、以下の形式で結果が返却されます：

{
  "startedAt": "2025-11-24T14:38:00.000Z",
  "finishedAt": "2025-11-24T14:38:05.123Z",
  "durationMs": 5123,
  "totalCount": 2,
  "passedCount": 2,
  "failedCount": 0,
  "testCases": [
    {
      "testCaseId": "user-get-001",
      "name": "ユーザー取得APIのテスト",
      "request": { ... },
      "expected": { ... },
      "actual": { ... },
      "passed": true,
      "bodyDiff": [],
      "evidence": { ... }
    }
  ]
}

passed が false の場合、差分（bodyDiff）に path / expected / actual が列挙されます。
ネットワークエラー時は details.error に code・message が入り、evidence.trace に request.error が記録されます。

MCP 連携

settings.json などに以下を設定:

{
  "mcpServers": {
    "apiTestEngine": {
      "command": "npx",
      "args": ["-y", "@ri-lab/api-test-engine"],
      "env": {
        "API_TEST_OUTPUT_BASE": "C:\\api-test-engine"
      }
    }
  }
}

環境変数

• API_TEST_OUTPUT_BASE（任意）: テスト結果ファイルの保存先ベースディレクトリを指定します。
  • 指定しない場合: process.cwd()（Cursorが起動したディレクトリ）が使用されます
  • 指定した場合: そのディレクトリ配下の mcp-results/{ファイル名}/{yyyyMMdd-HHmm}/ に保存されます
  • 例: "API_TEST_OUTPUT_BASE": "C:\\api-test-engine" と設定すると、C:\api-test-engine\mcp-results\user-api-tests\20251124-1438\ に保存されます

使用方法

Cursor から tool runApiTest に spec（テストケースの配列）を渡すだけで実行可能です。

注意: npx にパッケージ名を渡すだけで起動します。サブコマンドの指定は不要です。

終了コード

• 成功: 0
• 失敗（アサーション不一致/エラー）: 非 0

推奨バージョン

• Node.js: 18 以上（LTS 推奨: 18.x / 20.x）
• npm: 8 以上（npx 利用のため）

ライセンス

MIT