npm package: @ri-lab/api-test-engine
Description: Generic API test engine that executes HTTP requests from JSON specs and returns structured results.
Latest version: 0.4.4

# @ri-lab/api-test-engine

汎用 API 自動テストエンジン。  
テスト仕様 JSON を渡すだけで HTTP リクエストを実行し、期待値と比較した結果（差分と証跡ログを含む）を JSON で返します。

## 特長
- fetch/axios などのコード生成に依存せず、固定ロジックで安定動作
- GET/POST/PUT/DELETE に対応
- ネスト対応の JSON 一致判定（オブジェクトは「部分一致（subset）」で比較、配列は同順・同数で比較）
- 期待値と実際値の差分を返却（`bodyDiff`）
- タイムアウト・JSON パース失敗などのエラーハンドリング
- 証跡（evidence）出力：リクエスト/レスポンス/トレースログをJSONで返却

## インストール（任意）
MCP から `npx` 実行する場合はインストール不要です。ローカルに導入する場合のみ以下を使用してください。

```bash
npm install @ri-lab/api-test-engine
```



## テスト仕様 JSON 例

MCP経由で実行する場合は、**テストケースの配列**を渡します。単一のテストケースでも配列形式で指定してください。

```json
[
  {
    "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経由で実行した場合、以下の形式で結果が返却されます：

```json
{
  "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` などに以下を設定:

```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