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测试（推荐）

安装依赖

cd tests/api
pip install -r requirements.txt

运行快速测试

# Windows
run_tests.bat

# Linux/Mac
./run_tests.sh

# 或直接运行
python quick_test.py

2. Godot测试

运行API测试脚本

# 在Godot中运行
var api_test = preload("res://scripts/network/ApiTestScript.gd").new()
add_child(api_test)

运行UI测试

# 打开Godot项目
# 运行 tests/auth/auth_ui_test.tscn 场景

---

📊 测试类型详解

1. 快速测试 (quick_test.py)

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

python tests/api/quick_test.py

测试内容:

• ✅ 服务器状态检查
• ✅ 邮箱验证码发送
• ✅ 用户登录/注册
• ✅ 基础错误处理

2. 完整测试 (api_client_test.py)

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

python tests/api/api_client_test.py

测试内容:

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

3. Godot内置测试

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

API测试脚本

# 文件: scripts/network/ApiTestScript.gd
# 功能: 验证NetworkManager和ResponseHandler

UI测试场景

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

---

🔧 测试配置

API服务器配置

# 默认配置
API_BASE_URL = "https://whaletownend.xinghangee.icu"

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

测试数据配置

# 测试用户信息
TEST_EMAIL = "test@example.com"
TEST_USERNAME = "testuser"
TEST_PASSWORD = "password123"

超时配置

DEFAULT_TIMEOUT = 30  # 秒

---

📈 测试结果解读

成功标志

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

警告标志

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

错误标志

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

示例输出解读

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

解读:

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

---

🐛 故障排除

常见问题及解决方案

1. 连接失败

症状: ❌ 连接失败 或 网络连接异常

解决方案:

# 检查网络连接
ping whaletownend.xinghangee.icu

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

# 检查防火墙设置

2. 频率限制

症状: ⏰ 请求过于频繁 或 429状态码

解决方案:

• 等待冷却时间（通常1分钟）
• 使用不同的测试邮箱
• 检查API频率限制配置

3. 验证码错误

症状: 验证码错误或已过期

解决方案:

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

4. 参数验证失败

症状: 400状态码 或 参数验证失败

解决方案:

• 检查请求参数格式
• 确认必填字段都已提供
• 验证邮箱、用户名格式是否正确

5. Python依赖问题

症状: ModuleNotFoundError: No module named 'requests'

解决方案:

# 安装依赖
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接口说明
• API更新日志 - 最新的API变更记录
• 项目结构说明 - 项目整体架构
• 网络管理器设置 - Godot网络配置

---

🤝 贡献指南

添加新测试

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

报告问题

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

改进建议

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

---

测试愉快！🎉