whale-town-front/docs/testing_guide.md

# API接口测试指南

**更新日期**: 2025-12-25  
**适用版本**: API v1.1.1

---

## 🎯 测试概述

本指南提供了完整的API接口测试方案，包括Godot内置测试和独立的Python测试脚本，确保在不同环境下都能有效验证API功能。

---

## 📋 测试工具对比

| 测试工具 | 适用场景 | 优势 | 使用难度 |
|----------|----------|------|----------|
| **Python快速测试** | 日常检查 | 快速、简单 | ⭐ |
| **Python完整测试** | 全面验证 | 覆盖全面、详细 | ⭐⭐ |
| **Godot内置测试** | 引擎环境 | 真实环境、UI测试 | ⭐⭐⭐ |
| **简单连接测试** | 基础检查 | 最小依赖 | ⭐ |

---

## 🚀 快速开始

### 1. Python测试（推荐）

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

#### 运行快速测试
```bash
# Windows
run_tests.bat

# Linux/Mac
./run_tests.sh

# 或直接运行
python quick_test.py
```

### 2. Godot测试

#### 运行API测试脚本
```gdscript
# 在Godot中运行
var api_test = preload("res://scripts/network/ApiTestScript.gd").new()
add_child(api_test)
```

#### 运行UI测试
```bash
# 打开Godot项目
# 运行 tests/auth/auth_ui_test.tscn 场景
```

---

## 📊 测试类型详解

### 1. 快速测试 (`quick_test.py`)

**用途**: 日常开发中的快速验证  
**时间**: 约30秒  
**覆盖**: 基础API端点

```bash
python tests/api/quick_test.py
```

**测试内容**:
- ✅ 服务器状态检查
- ✅ 邮箱验证码发送
- ✅ 用户登录/注册
- ✅ 基础错误处理

### 2. 完整测试 (`api_client_test.py`)

**用途**: 发布前的全面验证  
**时间**: 约2-3分钟  
**覆盖**: 所有业务流程

```bash
python tests/api/api_client_test.py
```

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

### 3. Godot内置测试

**用途**: 引擎环境下的真实测试  
**时间**: 根据测试场景而定  
**覆盖**: UI交互和网络请求

#### API测试脚本
```gdscript
# 文件: scripts/network/ApiTestScript.gd
# 功能: 验证NetworkManager和ResponseHandler
```

#### UI测试场景
```gdscript
# 文件: tests/auth/auth_ui_test.tscn
# 功能: 测试认证界面的各种响应情况
```

---

## 🔧 测试配置

### API服务器配置
```python
# 默认配置
API_BASE_URL = "https://whaletownend.xinghangee.icu"

# 本地开发配置
API_BASE_URL = "http://localhost:3000"
```

### 测试数据配置
```python
# 测试用户信息
TEST_EMAIL = "test@example.com"
TEST_USERNAME = "testuser"
TEST_PASSWORD = "password123"
```

### 超时配置
```python
DEFAULT_TIMEOUT = 30  # 秒
```

---

## 📈 测试结果解读

### 成功标志
- ✅ **测试通过** - 功能正常
- 🧪 **测试模式** - 开发环境，验证码在响应中返回
- 🔑 **获取验证码** - 成功获取到测试验证码

### 警告标志
- ⚠️ **资源冲突** - 409状态码，用户名/邮箱已存在
- ⏰ **频率限制** - 429状态码，请求过于频繁

### 错误标志
- ❌ **测试失败** - 功能异常，需要检查
- 🔌 **连接失败** - 网络问题或服务器不可用
- 📊 **状态码异常** - HTTP状态码不符合预期

### 示例输出解读
```
🧪 测试: 发送邮箱验证码
📡 POST https://whaletownend.xinghangee.icu/auth/send-email-verification
📦 数据: {"email": "test@example.com"}
📊 状态码: 206
🧪 测试模式响应
🔑 验证码: 123456
✅ 测试通过
```

**解读**:
- 请求成功发送到正确的端点
- 返回206状态码表示测试模式
- 成功获取验证码123456
- 整体测试通过

---

## 🐛 故障排除

### 常见问题及解决方案

#### 1. 连接失败
**症状**: `❌ 连接失败` 或 `网络连接异常`

**解决方案**:
```bash
# 检查网络连接
ping whaletownend.xinghangee.icu

# 检查服务器状态
curl https://whaletownend.xinghangee.icu

# 检查防火墙设置
```

#### 2. 频率限制
**症状**: `⏰ 请求过于频繁` 或 `429状态码`

**解决方案**:
- 等待冷却时间（通常1分钟）
- 使用不同的测试邮箱
- 检查API频率限制配置

#### 3. 验证码错误
**症状**: `验证码错误或已过期`

**解决方案**:
- 确保使用最新获取的验证码
- 检查验证码是否在5分钟有效期内
- 在测试模式下使用响应中返回的验证码

#### 4. 参数验证失败
**症状**: `400状态码` 或 `参数验证失败`

**解决方案**:
- 检查请求参数格式
- 确认必填字段都已提供
- 验证邮箱、用户名格式是否正确

#### 5. Python依赖问题
**症状**: `ModuleNotFoundError: No module named 'requests'`

**解决方案**:
```bash
# 安装依赖
pip install requests

# 或使用requirements.txt
pip install -r tests/api/requirements.txt

# 检查Python版本
python --version
```

---

## 📝 测试最佳实践

### 1. 测试前准备
- 确认API服务器正常运行
- 检查网络连接稳定
- 准备测试数据（邮箱、用户名等）

### 2. 测试执行
- 按照从简单到复杂的顺序执行测试
- 记录测试结果和异常情况
- 对失败的测试进行重试验证

### 3. 测试后分析
- 分析测试结果，识别问题模式
- 更新测试用例覆盖新发现的场景
- 文档化测试发现的问题和解决方案

### 4. 持续集成
- 将测试脚本集成到CI/CD流程
- 设置自动化测试触发条件
- 建立测试结果通知机制

---

## 🔄 测试流程建议

### 开发阶段
1. **快速测试** - 每次代码修改后运行
2. **功能测试** - 新功能开发完成后运行
3. **回归测试** - 修复bug后运行

### 测试阶段
1. **完整测试** - 每日构建后运行
2. **压力测试** - 定期运行频率限制测试
3. **兼容性测试** - 不同环境下运行测试

### 发布阶段
1. **预发布测试** - 生产环境部署前运行
2. **冒烟测试** - 生产环境部署后运行
3. **监控测试** - 生产环境持续监控

---

## 📚 相关文档

- [API文档](api-documentation.md) - 完整的API接口说明
- [API更新日志](api_update_log.md) - 最新的API变更记录
- [项目结构说明](project_structure.md) - 项目整体架构
- [网络管理器设置](network_manager_setup.md) - Godot网络配置

---

## 🤝 贡献指南

### 添加新测试
1. 在对应的测试文件中添加新的测试方法
2. 遵循现有的测试模式和命名规范
3. 添加适当的错误处理和结果验证
4. 更新相关文档

### 报告问题
1. 提供详细的错误信息和复现步骤
2. 包含测试环境信息（Python版本、操作系统等）
3. 附上相关的日志和截图

### 改进建议
1. 提出测试覆盖的改进建议
2. 优化测试执行效率的方案
3. 增强测试结果可读性的想法

---

**测试愉快！🎉**