forked from datawhale/whale-town-end
docs: 重构文档结构和组织
- 重新组织docs目录结构，按功能模块分类 - 新增deployment和development目录 - 更新API文档结构 - 添加客户端README文档 - 移除过时的文档文件
This commit is contained in:
moyin
276
docs/development/TESTING.md
Normal file
276
docs/development/TESTING.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# 测试指南
|
||||
|
||||
本项目支持**无数据库和无邮件服务器**的测试模式，让你可以快速验证所有功能！
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 1. 环境配置
|
||||
|
||||
```bash
|
||||
# 复制环境配置文件
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
默认配置已经设置为测试模式，无需修改即可使用。
|
||||
|
||||
### 2. 启动服务
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
npm install
|
||||
|
||||
# 启动开发服务器
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 3. 运行测试
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
.\test-api.ps1
|
||||
```
|
||||
|
||||
**Linux/macOS:**
|
||||
```bash
|
||||
./test-api.sh
|
||||
```
|
||||
|
||||
**自定义参数:**
|
||||
```bash
|
||||
# Windows
|
||||
.\test-api.ps1 -BaseUrl "http://localhost:3000" -TestEmail "custom@example.com"
|
||||
|
||||
# Linux/macOS
|
||||
./test-api.sh "http://localhost:3000" "custom@example.com"
|
||||
```
|
||||
|
||||
## 🧪 测试功能
|
||||
|
||||
### API功能测试
|
||||
测试脚本会验证以下核心功能：
|
||||
|
||||
**用户认证模块：**
|
||||
- ✅ **邮箱验证码发送** - 生成6位数验证码，测试模式输出到控制台
|
||||
- ✅ **邮箱验证码验证** - 验证码校验和自动清理
|
||||
- ✅ **用户注册** - 完整的用户注册流程，包含邮箱验证
|
||||
- ✅ **用户登录** - 支持用户名/邮箱/手机号多种方式登录
|
||||
|
||||
**系统状态测试：**
|
||||
- ✅ **应用状态检查** - 验证服务器运行状态和系统信息
|
||||
- ✅ **Redis文件存储** - 验证验证码存储和读取功能
|
||||
- ✅ **内存数据库** - 验证用户数据存储功能
|
||||
|
||||
### 单元测试覆盖
|
||||
|
||||
**核心服务测试（7个测试套件，140个测试用例）：**
|
||||
|
||||
1. **LoginCoreService** - 登录核心服务（15个测试）
|
||||
- 用户登录成功/失败场景
|
||||
- 用户注册功能测试
|
||||
- GitHub OAuth登录测试
|
||||
- 密码重置和修改功能
|
||||
- 用户状态验证（active、inactive、locked等）
|
||||
|
||||
2. **AdminService** - 管理员服务测试
|
||||
- 管理员登录认证
|
||||
- 用户列表管理
|
||||
- 用户密码重置
|
||||
- 日志管理功能
|
||||
|
||||
3. **VerificationService** - 验证码服务测试
|
||||
- 验证码生成和验证
|
||||
- 频率限制机制
|
||||
- Redis存储操作
|
||||
- 错误处理和边界条件
|
||||
|
||||
4. **EmailService** - 邮件服务测试
|
||||
- 邮件发送功能（测试模式和生产模式）
|
||||
- 验证码邮件模板
|
||||
- 连接验证和错误处理
|
||||
- SMTP配置测试
|
||||
|
||||
5. **UsersService** - 用户数据服务测试
|
||||
- 用户CRUD操作
|
||||
- 用户查询功能
|
||||
- 数据验证和约束
|
||||
|
||||
6. **AdminCoreService** - 管理员核心服务测试
|
||||
- 管理员认证逻辑
|
||||
- 权限验证
|
||||
- 管理员引导创建
|
||||
|
||||
7. **LoggerService** - 日志服务测试
|
||||
- 日志记录功能
|
||||
- 敏感信息过滤
|
||||
- 日志级别控制
|
||||
|
||||
### E2E端到端测试
|
||||
|
||||
**登录功能完整流程测试：**
|
||||
- 用户注册 → 邮箱验证 → 登录验证
|
||||
- GitHub OAuth登录流程
|
||||
- 密码重置完整流程
|
||||
- 错误处理和边界条件测试
|
||||
|
||||
## 🔧 测试模式特性
|
||||
|
||||
- 🗄️ **Redis 文件存储** - 使用 `redis-data/redis.json` 存储验证码
|
||||
- 📧 **邮件测试模式** - 邮件内容输出到控制台，无需真实SMTP
|
||||
- 💾 **内存用户存储** - 无需数据库，用户数据存储在内存中
|
||||
- 🔄 **自动切换** - 根据配置自动选择存储模式
|
||||
|
||||
## 📊 单元测试
|
||||
|
||||
### 运行测试命令
|
||||
|
||||
```bash
|
||||
# 运行所有单元测试
|
||||
npm test
|
||||
|
||||
# 监听模式（开发时使用）
|
||||
npm run test:watch
|
||||
|
||||
# 生成覆盖率报告
|
||||
npm run test:cov
|
||||
|
||||
# 运行特定测试文件
|
||||
npm test -- src/core/login_core/login_core.service.spec.ts
|
||||
```
|
||||
|
||||
### 测试覆盖情况
|
||||
|
||||
**测试统计：**
|
||||
- 测试套件：7个
|
||||
- 测试用例：140个
|
||||
- 覆盖率：100%通过
|
||||
|
||||
**测试文件列表：**
|
||||
```
|
||||
src/core/login_core/login_core.service.spec.ts # 登录核心服务
|
||||
src/business/admin/admin.service.spec.ts # 管理员服务
|
||||
src/core/utils/verification/verification.service.spec.ts # 验证码服务
|
||||
src/core/utils/email/email.service.spec.ts # 邮件服务
|
||||
src/core/db/users/users.service.spec.ts # 用户数据服务
|
||||
src/core/admin_core/admin_core.service.spec.ts # 管理员核心服务
|
||||
src/core/utils/logger/logger.service.spec.ts # 日志服务
|
||||
test/business/login.e2e-spec.ts # E2E端到端测试
|
||||
```
|
||||
|
||||
### 测试场景覆盖
|
||||
|
||||
**正常流程测试：**
|
||||
- 用户注册、登录、密码管理
|
||||
- 邮箱验证码发送和验证
|
||||
- 管理员认证和用户管理
|
||||
- 系统状态和日志功能
|
||||
|
||||
**异常情况测试：**
|
||||
- 无效输入和参数验证
|
||||
- 网络连接失败处理
|
||||
- 权限验证和访问控制
|
||||
- 频率限制和安全防护
|
||||
|
||||
**边界条件测试：**
|
||||
- 密码强度验证
|
||||
- 验证码过期处理
|
||||
- 用户状态变更
|
||||
- 数据库连接异常
|
||||
|
||||
## 🌐 生产环境配置
|
||||
|
||||
要切换到生产环境，编辑 `.env` 文件：
|
||||
|
||||
```bash
|
||||
# 启用数据库（取消注释并填入真实数据）
|
||||
DB_HOST=your_mysql_host
|
||||
DB_PORT=3306
|
||||
DB_USERNAME=your_db_username
|
||||
DB_PASSWORD=your_db_password
|
||||
DB_NAME=your_db_name
|
||||
|
||||
# 启用真实Redis（取消注释并设置）
|
||||
USE_FILE_REDIS=false
|
||||
REDIS_HOST=your_redis_host
|
||||
REDIS_PORT=6379
|
||||
REDIS_PASSWORD=your_redis_password
|
||||
|
||||
# 启用邮件服务（取消注释并填入真实数据）
|
||||
EMAIL_HOST=smtp.gmail.com
|
||||
EMAIL_PORT=587
|
||||
EMAIL_USER=your_email@gmail.com
|
||||
EMAIL_PASS=your_app_password
|
||||
EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>
|
||||
|
||||
# 生产环境设置
|
||||
NODE_ENV=production
|
||||
LOG_LEVEL=info
|
||||
```
|
||||
|
||||
## 🔍 故障排除
|
||||
|
||||
### 服务启动失败
|
||||
- **端口占用**：检查端口3000是否被占用，使用 `netstat -ano | findstr :3000` 查看
|
||||
- **Node.js版本**：确认Node.js版本 >= 18.0.0，使用 `node --version` 检查
|
||||
- **依赖问题**：运行 `npm install` 或 `pnpm install` 重新安装依赖
|
||||
- **权限问题**：确保有足够的文件读写权限
|
||||
|
||||
### 测试脚本执行失败
|
||||
- **服务器状态**：确认服务器正在运行，访问 http://localhost:3000 检查
|
||||
- **网络连接**：检查防火墙设置，确保端口3000可访问
|
||||
- **脚本权限**：在Linux/macOS上确保脚本有执行权限：`chmod +x test-api.sh`
|
||||
- **PowerShell策略**：Windows上可能需要设置执行策略：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
|
||||
|
||||
### 单元测试失败
|
||||
- **依赖冲突**：清理node_modules并重新安装：`rm -rf node_modules && npm install`
|
||||
- **TypeScript错误**：运行 `npm run build` 检查编译错误
|
||||
- **环境变量**：确保测试环境变量配置正确
|
||||
- **数据库连接**：测试模式下应该使用内存数据库，检查配置
|
||||
|
||||
### Redis文件存储问题
|
||||
- **目录权限**：检查 `redis-data` 目录的读写权限
|
||||
- **配置设置**：确认 `USE_FILE_REDIS=true` 设置正确
|
||||
- **文件锁定**：确保redis.json文件没有被其他进程锁定
|
||||
- **磁盘空间**：检查磁盘空间是否充足
|
||||
|
||||
### 邮件测试模式问题
|
||||
- **配置检查**：确认邮件配置为注释状态（测试模式）
|
||||
- **控制台输出**：检查服务器控制台是否有邮件内容输出
|
||||
- **日志级别**：确保日志级别设置为info或debug以查看详细输出
|
||||
|
||||
### 常见错误解决
|
||||
|
||||
**EADDRINUSE错误：**
|
||||
```bash
|
||||
# 查找占用端口的进程
|
||||
netstat -ano | findstr :3000
|
||||
# 结束进程（Windows）
|
||||
taskkill /PID <进程ID> /F
|
||||
```
|
||||
|
||||
**权限错误：**
|
||||
```bash
|
||||
# Linux/macOS设置权限
|
||||
chmod +x test-api.sh
|
||||
chmod 755 redis-data/
|
||||
```
|
||||
|
||||
**模块未找到错误：**
|
||||
```bash
|
||||
# 清理并重新安装
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## 📝 测试数据
|
||||
|
||||
测试完成后，你可以查看：
|
||||
|
||||
- `redis-data/redis.json` - 验证码存储数据
|
||||
- 服务器控制台 - 邮件内容输出
|
||||
- 测试脚本输出 - API响应结果
|
||||
|
||||
## 🎯 下一步
|
||||
|
||||
- 查看 [API 文档](http://localhost:3000/api-docs) 了解更多接口
|
||||
- 阅读 [开发规范](./docs/backend_development_guide.md) 开始开发
|
||||
- 使用 [AI 辅助指南](./docs/AI辅助开发规范指南.md) 提高开发效率
|
||||
Reference in New Issue
Block a user