api-tester

API テスター

概要

HTTP リクエストを送信して API エンドポイントをテストし、レスポンスを検証して結果を報告します。認証、カスタムヘッダー、リクエストボディ、ステータスコード・ヘッダー・レスポンスペイロードに対する構造化アサーションを含む、REST API と GraphQL API をサポートします。

手順

ユーザーから API エンドポイントのテストまたはデバッグを依頼された場合は、次の手順に従います。

ステップ 1：エンドポイントの詳細を確認する

ユーザーまたはコードベースから、次の情報を確認します。

• URL：エンドポイントの完全な URL
• メソッド：GET、POST、PUT、PATCH、DELETE
• ヘッダー：Content-Type、Authorization、カスタムヘッダー
• ボディ：JSON ペイロード、フォームデータ、またはクエリパラメーター
• 認証：Bearer トークン、API キー、Basic 認証
• 期待するレスポンス：ステータスコード、レスポンスの形式、特定の値

ステップ 2：リクエストを送信する

curl を使用する場合（簡単なテストに推奨）：

# GET request
curl -s --max-time 30 -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  -H "Authorization: Bearer $NORTHWIND_API_TOKEN" \
  "https://api.northwind-shop.dev/v2/users?page=1"

# POST request with JSON
curl -s --max-time 30 -w "\nHTTP Status: %{http_code}\nTime: %{time_total}s\n" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NORTHWIND_API_TOKEN" \
  -d '{"name": "Jane Alvarez", "email": "[email protected]"}' \
  "https://api.northwind-shop.dev/v2/users"

# Add --fail-with-body (curl 7.76+) to get a non-zero exit code on 4xx/5xx while still printing the error body

Python を使用する場合（複雑なフロー向け）：

import requests
import json
import time

def test_endpoint(method, url, headers=None, body=None, expected_status=200):
    start = time.time()
    response = requests.request(method, url, headers=headers, json=body, timeout=30)
    elapsed = time.time() - start

    result = {
        "status": response.status_code,
        "time_ms": round(elapsed * 1000),
        "headers": dict(response.headers),
        "body": response.json() if response.headers.get("content-type", "").startswith("application/json") else response.text,
    }

    passed = response.status_code == expected_status
    print(f"{'PASS' if passed else 'FAIL'} | {method} {url} | {response.status_code} | {result['time_ms']}ms")
    return result, passed

ステップ 3：レスポンスを検証する

次の順序で確認します。

1. ステータスコードが期待どおりか（200、201、204、400、401、404 など）
2. レスポンス時間が許容範囲内か（2 秒を超える場合は警告）
3. Content-Type ヘッダーが期待する形式と一致するか
4. レスポンスボディの構造が期待するスキーマと一致するか
5. 特定の値がアサーションに一致するか

def validate_response(result, assertions):
    failures = []
    body = result["body"]

    for field, expected in assertions.items():
        actual = body
        for key in field.split("."):
            if isinstance(actual, dict):
                actual = actual.get(key)
            elif isinstance(actual, list) and key.isdigit():
                actual = actual[int(key)]
            else:
                actual = None
                break

        if actual != expected:
            failures.append(f"  {field}: expected {expected!r}, got {actual!r}")

    return failures

ステップ 4：結果を報告する

わかりやすいテストレポートとして、次の形式でまとめます。

API Test Results
================
Endpoint: POST /api/users
Status:   201 Created (expected 201) -- PASS
Time:     142ms
Body:     Valid JSON, 3 fields

Assertions:
  [PASS] body.id is present
  [PASS] body.name == "Jane Alvarez"
  [PASS] body.email == "[email protected]"
  [FAIL] body.role expected "admin", got "user"

Result: 3/4 assertions passed

例

例 1：CRUD フローをテストする

ユーザーの依頼：「ユーザー API をテストしてください。作成、読み取り、更新、削除をお願いします」

出力：

API Test Suite: Users CRUD
==========================

1. POST /api/users
   Status: 201 Created -- PASS
   Time:   156ms
   Body:   {"id": 42, "name": "Jane Alvarez", "email": "[email protected]"}

2. GET /api/users/42
   Status: 200 OK -- PASS
   Time:   38ms
   Body:   {"id": 42, "name": "Jane Alvarez", "email": "[email protected]"}

3. PUT /api/users/42
   Status: 200 OK -- PASS
   Time:   89ms
   Body:   {"id": 42, "name": "Jane Alvarez-Reyes", "email": "[email protected]"}

4. DELETE /api/users/42
   Status: 204 No Content -- PASS
   Time:   45ms

5. GET /api/users/42 (verify deletion)
   Status: 404 Not Found -- PASS
   Time:   22ms

Result: 5/5 PASSED

例 2：失敗するリクエストをデバッグする

ユーザーの依頼：「POST /api/orders で 401 が返ってきます。原因を調べてもらえますか？」

出力：

Debugging POST /api/orders
===========================

Test 1: No auth header
  Status: 401 -- Missing Authorization header (expected)

Test 2: With Bearer token
  Status: 401 -- Response: {"error": "Token expired"}
  Note: Token exp claim is 2026-01-15T00:00:00Z (expired)

Test 3: With refreshed token
  Status: 201 Created -- PASS

Root cause: Your Bearer token has expired.
Fix: Refresh the token using POST /api/auth/refresh

ガイドライン

• ユーザーが明示的に確認しない限り、本番 API にリクエストを送信してはいけません。まず確認してください。
• 機密情報（トークン、パスワード、API キー）は出力でマスクします。末尾 4 文字だけを表示します。
• 依存関係のあるリクエストを連続して実行する場合（作成してから読み取りなど）は、最初のリクエストのレスポンスを使って 2 つ目のリクエストを作成します。
• レポートにはレスポンス時間を含めます。2 秒を超えるレスポンスには遅いと警告します。
• 認証フローをテストするときは、正常系とよくある失敗パターン（期限切れのトークン、誤った認証情報、権限不足）の両方をテストします。
• GraphQL では、{"query": "...", "variables": {...}} を JSON ボディとして使用し、POST で送信します。GraphQL サーバーは失敗時も 200 を返すことがよくあるため、errors が存在しないか空であることを確認し、data も個別に検証します。
• トークンは環境変数に保存し、シェルの履歴やレポートに残るコマンドには含めないでください。
• エンドポイントがページネーションを返す場合は、最初のページをテストし、合計件数に言及します。
• 応答しないエンドポイントで処理が停止しないよう、必ずタイムアウト（30 秒）を設定します。