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

API接口测试

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

测试脚本说明

1. quick_test.py - 快速测试（推荐）

快速验证API接口的基本功能，适合日常检查。

使用方法：

python tests/api/quick_test.py

测试内容：

• ✅ 应用状态检查
• ✅ 发送邮箱验证码
• ✅ 发送验证码（无效邮箱）
• ✅ 用户登录
• ✅ 用户注册（无邮箱）
• ✅ 发送登录验证码

2. api_client_test.py - 完整测试套件

全面的API接口测试，包含所有业务流程和错误场景。

使用方法：

python tests/api/api_client_test.py

测试内容：

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

3. simple_api_test.py - 简化版测试

快速验证API接口的基本连通性和功能。

使用方法：

# 使用默认服务器地址
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接口测试，包括边界条件和错误处理。

使用方法：

# 基础测试
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. 添加适当的错误处理

自定义测试参数

# 修改测试配置
tester = SimpleAPITester("http://your-server.com")
tester.run_basic_tests()

注意事项

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

依赖要求

安装依赖

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

# 或者手动安装
pip install requests

依赖包说明

• requests - HTTP请求库，用于发送API请求
• json - JSON数据处理（Python标准库）
• time - 时间处理（Python标准库）
• sys - 系统功能（Python标准库）

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