whale-town-front/tests/api/README.md

# API接口测试

本目录包含用于测试whaleTown项目API接口的测试脚本。

## 测试脚本说明

### 1. `quick_test.py` - 快速测试（推荐）
快速验证API接口的基本功能，适合日常检查。

**使用方法：**
```bash
python tests/api/quick_test.py
```

**测试内容：**
- ✅ 应用状态检查
- ✅ 发送邮箱验证码
- ✅ 发送验证码（无效邮箱）
- ✅ 用户登录
- ✅ 用户注册（无邮箱）
- ✅ 发送登录验证码

### 2. `api_client_test.py` - 完整测试套件
全面的API接口测试，包含所有业务流程和错误场景。

**使用方法：**
```bash
python tests/api/api_client_test.py
```

**测试内容：**
- 🔄 完整的邮箱验证流程
- 🔄 用户注册流程（带邮箱验证）
- 🔄 用户登录流程（密码+验证码）
- 🔄 密码重置流程
- 🔄 错误场景测试
- 🔄 频率限制测试

### 3. `simple_api_test.py` - 简化版测试
快速验证API接口的基本连通性和功能。

**使用方法：**
```bash
# 使用默认服务器地址
python tests/api/simple_api_test.py

# 使用自定义服务器地址
python tests/api/simple_api_test.py http://localhost:3000
```

**测试内容：**
- ✅ 应用状态检查 (`GET /`)
- ✅ 发送邮箱验证码 (`POST /auth/send-email-verification`)
- ✅ 用户注册 (`POST /auth/register`)
- ✅ 用户登录 (`POST /auth/login`)
- ✅ 无效登录测试
- ✅ 管理员登录测试

### 4. `api_test.py` - 完整版测试
全面的API接口测试，包括边界条件和错误处理。

**使用方法：**
```bash
# 基础测试
python tests/api/api_test.py

# 详细日志
python tests/api/api_test.py --verbose

# 自定义参数
python tests/api/api_test.py --base-url http://localhost:3000 --test-email custom@example.com
```

**测试内容：**
- 应用状态接口测试
- 用户认证功能测试
- 管理员功能测试
- 用户状态管理测试
- 错误处理测试
- 频率限制测试

## 测试结果示例

### 成功的测试输出
```
[18:28:55] 🚀 开始基础API测试...
[18:28:55] 测试目标: https://whaletownend.xinghangee.icu
[18:28:55] ✅ 应用状态检查
[18:28:55]    状态码: 200
[18:28:55]    响应: Pixel Game Server is running!
[18:28:55] ✅ 发送邮箱验证码
[18:28:55]    状态码: 200
[18:28:55] 📧 获取到验证码: 046189
[18:28:55] ✅ 用户注册
[18:28:55]    状态码: 201
[18:28:55] 🎯 基础测试完成！
```

### API接口验证结果

根据测试结果，以下接口已验证可用：

#### ✅ 可用接口
1. **应用状态** - `GET /`
   - 状态码: 200
   - 响应: "Pixel Game Server is running!"

2. **发送邮箱验证码** - `POST /auth/send-email-verification`
   - 状态码: 200
   - 功能: 正常发送验证码
   - 频率限制: 1分钟内限制重复发送

3. **用户注册** - `POST /auth/register`
   - 状态码: 201 (成功) / 400 (参数错误)
   - 需要邮箱验证码
   - 支持完整的参数验证

4. **用户登录** - `POST /auth/login`
   - 状态码: 200
   - 支持用户名/邮箱登录
   - 正确的错误处理

#### ❌ 不可用接口
1. **管理员登录** - `POST /admin/auth/login`
   - 状态码: 404
   - 错误: "Cannot POST /admin/auth/login"
   - 可能的原因: 路径不正确或功能未实现

## 测试发现的问题

### 1. 管理员接口路径问题
- 文档中的 `/admin/auth/login` 返回404
- 需要确认正确的管理员登录路径

### 2. 频率限制功能正常
- 验证码发送有1分钟的频率限制
- 错误消息清晰："请等待 XX 秒后再试"

### 3. 参数验证严格
- 注册时必须提供邮箱验证码
- 错误消息准确："提供邮箱时必须提供邮箱验证码"

## 建议的测试流程

### 开发环境测试
1. 运行简化版测试验证基本功能
2. 检查所有接口的连通性
3. 验证错误处理是否正确

### 生产环境测试
1. 使用完整版测试进行全面验证
2. 测试所有边界条件
3. 验证安全功能（频率限制、权限控制）

## 扩展测试

### 添加新的测试用例
1. 在对应的测试脚本中添加新的测试方法
2. 遵循现有的测试模式
3. 添加适当的错误处理

### 自定义测试参数
```python
# 修改测试配置
tester = SimpleAPITester("http://your-server.com")
tester.run_basic_tests()
```

## 注意事项

1. **频率限制**: 测试时注意API的频率限制，避免被限制
2. **测试数据**: 使用时间戳生成唯一的测试数据
3. **网络超时**: 设置合适的请求超时时间
4. **错误处理**: 测试脚本包含完整的错误处理逻辑

## 依赖要求

### 安装依赖
```bash
# 安装Python依赖
pip install -r tests/api/requirements.txt

# 或者手动安装
pip install requests
```

### 依赖包说明
- **requests** - HTTP请求库，用于发送API请求
- **json** - JSON数据处理（Python标准库）
- **time** - 时间处理（Python标准库）
- **sys** - 系统功能（Python标准库）

测试脚本主要使用Python标准库和requests库，依赖最小化。