forked from datawhale/whale-town-front
docs：添加完整的项目文档体系
- 添加Web部署完整指南和更新日志 - 创建网络管理器配置文档 - 完善项目设置和测试指南 - 添加API更新日志和清理总结 - 更新脚本使用说明文档
This commit is contained in:
312
docs/testing_guide.md
Normal file
312
docs/testing_guide.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# 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. 增强测试结果可读性的想法
|
||||
|
||||
---
|
||||
|
||||
**测试愉快！🎉**
|
||||
Reference in New Issue
Block a user