api-tester

API 测试器

概述

通过发送 HTTP 请求、验证响应并报告结果来测试 API 端点。支持 REST 和 GraphQL API，以及身份验证、自定义标头、请求正文，以及针对状态代码、标头和响应负载的结构化断言。

说明

当用户要求你测试或调试 API 端点时，请按以下步骤操作：

步骤 1：收集端点详情

根据用户提供的信息或代码库确定：

• URL：完整的端点 URL
• 方法：GET、POST、PUT、PATCH、DELETE
• 标头：Content-Type、Authorization、自定义标头
• 正文：JSON 负载、表单数据或查询参数
• 身份验证：Bearer 令牌、API 密钥、基本身份验证
• 预期响应：状态代码、响应结构、特定值

步骤 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 流程

用户请求：“测试 users 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 秒的响应应标记为缓慢。
• 测试身份验证流程时，同时测试正常情况和常见失败场景（令牌过期、凭据错误、权限缺失）。
• 对于 GraphQL，请使用 POST，并将 {"query": "...", "variables": {...}} 作为 JSON 正文。GraphQL 服务即使在失败时通常也会返回 200，因此请检查 errors 是否不存在或为空，并单独验证 data。
• 将令牌保存在环境变量中，不要放在会写入 shell 历史记录或报告的命令中。
• 如果端点返回分页结果，请测试第一页并说明总数。
• 始终设置超时时间（30 秒），以避免在无响应的端点上挂起。