@raphaellcs/api-tester

API 测试工具 - 简单的 HTTP 请求测试和验证

🚀 功能

• 简单配置：JSON 文件定义测试
• 多种验证：状态码、响应体、类型检查
• 灵活请求：支持所有 HTTP 方法
• 详细输出：清晰的测试结果和错误信息
• 批量执行：一次执行多个 API 测试
• 环境变量：支持 $VAR 和 ${VAR} 格式（新）
• 数据提取：从前置测试提取数据传递给后续测试（新）
• 重试机制：支持指数退避重试策略（新）
• 测试报告：生成 HTML/JUnit/JSON 格式报告（新）
• 请求延迟：控制请求间隔（新）

📦 安装

npx @claw-dev/api-tester

📖 快速开始

1. 初始化配置

api-test init

生成 api-tests.json 配置文件。

2. 编辑配置

{
  "version": "1.0",
  "baseUrl": "https://api.example.com",
  "requests": [
    {
      "name": "获取用户列表",
      "method": "GET",
      "url": "/users",
      "expectStatus": 200
    }
  ]
}

3. 运行测试

# 执行所有测试
api-test run

# 详细输出
api-test run --verbose

# 只执行特定请求
api-test run --request "获取用户列表"

# 使用自定义配置文件
api-test run --config /path/to/config.json

📋 配置说明

全局配置

| 字段 | 类型 | 说明 | |------|------|------| | version | string | 配置文件版本 | | baseUrl | string | 基础 URL（自动拼接） |

请求配置

| 字段 | 类型 | 必需 | 说明 | |------|------|------|------| | name | string | ❌ | 请求名称 | | method | string | ❌ | HTTP 方法（GET/POST/PUT/DELETE等），默认 GET | | url | string | ✅ | 请求 URL | | headers | object | ❌ | 请求头 | | data | object | ❌ | 请求体（POST/PUT） | | params | object | ❌ | URL 参数 | | timeout | number | ❌ | 超时时间（ms），默认 30000 | | expectStatus | number | ❌ | 期望的状态码 | | expectBody | object | ❌ | 期望的响应体字段 | | schema | object | ❌ | 响应体类型验证 | | validate | function | ❌ | 自定义验证函数 | | disabled | boolean | ❌ | 禁用此测试 | | extract | array | ❌ | 数据提取规则（新） | | retry | object | ❌ | 重试策略（新） |

数据提取配置

| 字段 | 类型 | 说明 | |------|------|------| | name | string | 提取的变量名 | | path | string | 数据路径（点表示法，如 "data.id"） |

重试配置

| 字段 | 类型 | 说明 | |------|------|------| | maxRetries | number | 最大重试次数（默认：3） | | delay | number | 初始延迟毫秒数（默认：1000） | | backoffMultiplier | number | 退避倍数（默认：2） |

🎯 验证方式

1. 状态码验证

{
  "name": "成功请求",
  "url": "/success",
  "expectStatus": 200
}

2. 响应体验证

{
  "name": "创建资源",
  "method": "POST",
  "url": "/users",
  "data": { "name": "John" },
  "expectBody": {
    "success": true,
    "message": "created"
  }
}

3. 类型验证

{
  "name": "返回数组",
  "url": "/users",
  "schema": {
    "data": "array",
    "total": "number"
  }
}

4. 自定义验证

{
  "name": "自定义验证",
  "url": "/data",
  "validate": function(result) {
    return {
      pass: result.data.items.length > 0,
      message: `items 数量: ${result.data.items.length}`
    };
  }
}

5. 环境变量替换

在配置中使用环境变量：

{
  "baseUrl": "$API_BASE_URL",
  "requests": [
    {
      "name": "获取用户",
      "url": "/users/${USER_ID}",
      "headers": {
        "Authorization": "Bearer $API_TOKEN"
      }
    }
  ]
}

运行前设置环境变量：

export API_BASE_URL="https://api.example.com"
export USER_ID="123"
export API_TOKEN="your-token"
api-test run

6. 数据提取和传递

从前置测试提取数据，传递给后续测试：

{
  "requests": [
    {
      "name": "创建用户",
      "method": "POST",
      "url": "/users",
      "data": { "name": "John" },
      "extract": [
        {
          "name": "userId",
          "path": "data.id"
        }
      ]
    },
    {
      "name": "获取用户详情",
      "method": "GET",
      "url": "/users/$userId",
      "expectStatus": 200
    }
  ]
}

7. 重试机制

配置重试策略：

{
  "requests": [
    {
      "name": "可能失败的请求",
      "url": "/unstable",
      "retry": {
        "maxRetries": 3,
        "delay": 1000,
        "backoffMultiplier": 2
      }
    }
  ]
}

• maxRetries: 最大重试次数
• delay: 初始延迟（毫秒）
• backoffMultiplier: 退避倍数（每次重试延迟 = delay * backoffMultiplier^n）

8. 生成测试报告

生成 HTML 报告：

api-test run --report html --output report.html

生成 JUnit 报告（CI/CD 集成）：

api-test run --report junit --output results.xml

生成 JSON 报告：

api-test run --report json --output results.json

💡 使用场景

1. API 集成测试

{
  "requests": [
    { "name": "登录", "method": "POST", "url": "/login", "expectStatus": 200 },
    { "name": "获取用户", "method": "GET", "url": "/me", "expectStatus": 200 },
    { "name": "创建任务", "method": "POST", "url": "/tasks", "expectStatus": 201 }
  ]
}

2. 监控健康检查

{
  "requests": [
    { "name": "API 健康检查", "url": "https://api.example.com/health", "expectStatus": 200 },
    { "name": "数据库检查", "url": "https://api.example.com/db", "expectStatus": 200 }
  ]
}

3. Webhook 测试

{
  "requests": [
    {
      "name": "测试 Webhook",
      "method": "POST",
      "url": "https://webhook.site/xxx",
      "headers": { "Content-Type": "application/json" },
      "data": { "event": "test", "data": "hello" },
      "expectStatus": 200
    }
  ]
}

4. 多环境测试

# 开发环境
api-test run --config api-dev.json

# 测试环境
api-test run --config api-test.json

# 生产环境
api-test run --config api-prod.json

📊 输出示例

成功

GET 获取用户列表
  200 245ms

  ✓ 状态码 = 200
  ✓ body.data type = array
  ✓ body.total type = number

==================================================
总计: 3 | 通过: 3 | 失败: 0

✓ 所有测试通过

失败

POST 创建用户
  500 1200ms

  ✗ 状态码 = 201
    实际: 500
    期望: 201
  ✗ body.success = true
    实际: false
    期望: true

==================================================
总计: 3 | 通过: 2 | 失败: 1

✗ 部分测试失败

🔧 高级功能

环境变量

# 在 shell 中设置
export API_BASE_URL="https://api.example.com"

# 在配置中使用
{
  "baseUrl": "$API_BASE_URL",
  "requests": [...]
}

禁用测试

{
  "name": "暂时禁用",
  "url": "/experimental",
  "disabled": true
}

命名测试

# 只运行特定测试
api-test run --request "健康检查"

🚧 待实现

• [ ] 环境变量替换
• [ ] 数据提取和传递（前置测试结果）
• [ ] 生成测试报告（HTML/JUnit）
• [ ] 并发请求
• [ ] 重试机制
• [ ] 断言库集成

🤝 贡献

欢迎提交 Issue 和 PR！

📄 许可证

MIT © 梦心

Made with 🌙 by 梦心