npm package: @raphaellcs/api-tester
Description: API 测试工具 - 环境变量、数据提取、测试报告
Author: 梦心
Latest version: 2.0.0

# @raphaellcs/api-tester
[![npm](https://img.shields.io/npm/v/@raphaellcs/api-tester)](https://www.npmjs.com/package/@raphaellcs/api-tester)
[![downloads](https://img.shields.io/npm/dm/@raphaellcs/api-tester)](https://www.npmjs.com/package/@raphaellcs/api-tester)
[![license](https://img.shields.io/npm/l/@raphaellcs/api-tester)](https://www.npmjs.com/package/@raphaellcs/api-tester)

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

## 🚀 功能

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

## 📦 安装

```bash
npx @claw-dev/api-tester
```

## 📖 快速开始

### 1. 初始化配置

```bash
api-test init
```

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

### 2. 编辑配置

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

### 3. 运行测试

```bash
# 执行所有测试
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. 状态码验证

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

### 2. 响应体验证

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

### 3. 类型验证

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

### 4. 自定义验证

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

### 5. 环境变量替换

在配置中使用环境变量：

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

运行前设置环境变量：

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

### 6. 数据提取和传递

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

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

### 7. 重试机制

配置重试策略：

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

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

### 8. 生成测试报告

生成 HTML 报告：

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

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

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

生成 JSON 报告：

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

## 💡 使用场景

### 1. API 集成测试

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

### 2. 监控健康检查

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

### 3. Webhook 测试

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

### 4. 多环境测试

```bash
# 开发环境
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

✗ 部分测试失败
```

## 🔧 高级功能

### 环境变量

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

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

### 禁用测试

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

### 命名测试

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

## 🚧 待实现

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

## 🤝 贡献

欢迎提交 Issue 和 PR！

## 📄 许可证

MIT © 梦心

---

Made with 🌙 by 梦心