meteor_detection_system/TESTING.md

# 🧪 集成测试指南 - Meteor 全栈项目

## 📋 测试架构概览

本项目实现了完整的三层测试架构：

### 🏗️ 测试环境组件
- **PostgreSQL (测试库)**: 端口 5433
- **LocalStack**: AWS S3/SQS 模拟 (端口 4566)
- **后端服务**: NestJS API (端口 3000)
- **前端服务**: Next.js App (端口 3001)

### 🎯 测试类型覆盖
1. **单元测试**: 组件和服务逻辑
2. **API集成测试**: 后端完整工作流
3. **E2E测试**: 前端用户交互
4. **全栈集成测试**: 端到端业务流程

## 🚀 快速开始

### 前置条件
```bash
# 安装必要工具
npm install -g @playwright/test
docker --version  # 需要 Docker
aws --version     # 需要 AWS CLI (用于LocalStack)
```

### 一键启动测试环境
```bash
# 初始化并启动所有测试服务
./test-setup.sh

# 或手动步骤
docker-compose -f docker-compose.test.yml up -d
npm run setup:test
```

## 🔧 测试命令大全

### 单独运行测试
```bash
# 前端单元测试
cd meteor-frontend && npm run test

# 前端E2E测试 
cd meteor-frontend && npm run test:e2e

# 后端单元测试
cd meteor-web-backend && npm run test

# 后端集成测试
cd meteor-web-backend && npm run test:integration
```

### 组合测试流程
```bash
# 运行所有测试（推荐）
npm run test:fullstack

# 仅前端测试
npm run test:frontend

# 仅后端测试  
npm run test:backend

# 快速开发测试
npm run test
```

### 开发模式
```bash
# Watch模式运行前端测试
cd meteor-frontend && npm run test:watch

# Playwright UI模式运行E2E
cd meteor-frontend && npm run test:e2e:ui

# 后端Watch模式
cd meteor-web-backend && npm run test:watch
```

## 📊 测试数据管理

### 自动化测试数据生成
```javascript
// test-data/seed-test-data.js 生成的数据包括：
const testData = {
  users: [
    {
      email: 'gallery-test@meteor.dev',
      password: 'TestPassword123',
      displayName: 'Gallery Test User'
    }
  ],
  devices: ['TEST_DEVICE_001', 'TEST_DEVICE_002'],
  events: [
    {
      eventType: 'meteor',
      location: 'Test Location 1',
      confidence: 0.95
    }
  ]
}
```

### 手动创建测试数据
```bash
# 运行数据生成脚本
node test-data/seed-test-data.js

# 检查生成的数据
cat test-data/generated-test-data.json
```

## 🎪 Gallery页面测试详解

### E2E测试场景
```typescript
// e2e/gallery.spec.ts 涵盖：
✅ 未认证用户重定向到登录页
✅ 认证后显示Gallery页面
✅ 空状态展示
✅ 加载状态处理
✅ 事件卡片展示
✅ 无限滚动功能
✅ 响应式设计（移动端）
✅ API错误处理
```

### 集成测试工作流
```typescript
// test/integration.e2e-spec.ts 验证：
✅ 完整用户注册→登录→创建设备→上传事件→Gallery展示流程
✅ 多用户数据隔离
✅ 分页和游标功能
✅ 并发请求处理
✅ 性能和负载测试
```

## 🏗️ 测试环境配置

### Docker Compose 服务配置
```yaml
# docker-compose.test.yml
services:
  test-postgres:    # 测试数据库
  localstack:       # AWS服务模拟
  test-backend:     # 后端API
  test-frontend:    # 前端应用
```

### 环境变量
```bash
# 测试环境变量
TEST_DATABASE_URL=postgresql://meteor_test:meteor_test_pass@localhost:5433/meteor_test
AWS_ENDPOINT_URL=http://localhost:4566
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
S3_BUCKET_NAME=meteor-test-bucket
```

## 🔍 常见测试场景

### 1. Gallery 完整工作流测试
```bash
# 启动测试环境
./test-setup.sh

# 运行完整集成测试
npm run test:integration

# 验证涵盖的场景：
# - 用户注册和登录
# - 设备注册和关联  
# - 事件上传和处理
# - Gallery API查询
# - 前端展示和交互
```

### 2. 前端组件E2E测试
```bash
# 运行Playwright E2E测试
npm run test:e2e

# 测试场景：
# - 登录流程
# - Gallery页面导航
# - 事件卡片交互
# - 无限滚动
# - 响应式布局
```

### 3. API性能和负载测试
```bash
# 后端压力测试
cd meteor-web-backend && npm run test:integration

# 验证场景：
# - 并发API请求处理
# - 大数据集分页性能
# - 数据库查询优化
# - 内存使用和响应时间
```

## 🚨 故障排除

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

#### 1. Docker服务启动失败
```bash
# 检查端口占用
lsof -i :5433 -i :4566 -i :3000 -i :3001

# 清理并重启
docker-compose -f docker-compose.test.yml down -v
./test-setup.sh
```

#### 2. LocalStack连接失败
```bash
# 检查LocalStack健康状态
curl http://localhost:4566/_localstack/health

# 重新初始化AWS服务
aws --endpoint-url=http://localhost:4566 s3 mb s3://meteor-test-bucket
```

#### 3. 数据库迁移问题
```bash
# 手动运行迁移
cd meteor-web-backend
npm run migrate:up

# 检查数据库连接
node scripts/test-db-connection.js
```

#### 4. 前端E2E测试失败
```bash
# 安装Playwright浏览器
npx playwright install

# 调试模式运行
npm run test:e2e:ui

# 检查前端服务状态
curl http://localhost:3001
```

## 📈 测试覆盖率报告

### 查看覆盖率
```bash
# 前端覆盖率
cd meteor-frontend && npm run test:cov

# 后端覆盖率  
cd meteor-web-backend && npm run test:cov

# 生成HTML报告
open coverage/lcov-report/index.html
```

### 目标覆盖率指标
- **单元测试**: > 80%
- **集成测试**: > 70%
- **E2E测试**: 关键用户路径 100%

## 🔄 CI/CD 集成

### GitHub Actions 示例
```yaml
name: Full Stack Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Test Environment
        run: ./test-setup.sh
      - name: Run Full Stack Tests
        run: npm run test:fullstack
```

## 📚 最佳实践

### 1. 测试数据管理
- ✅ 每个测试独立的数据集
- ✅ 测试后自动清理
- ✅ 真实业务场景数据

### 2. 测试稳定性
- ✅ 明确的等待条件
- ✅ 合理的超时设置
- ✅ 网络请求Mock

### 3. 性能优化
- ✅ 并行执行无关测试
- ✅ 数据库事务回滚
- ✅ 服务复用

## 🎯 下一步计划

### 即将添加的测试功能
- [ ] 视觉回归测试
- [ ] 移动端自动化测试
- [ ] API接口契约测试
- [ ] 性能基准测试
- [ ] 安全渗透测试

---

## 🤝 贡献指南

提交测试相关PR时，请确保：
1. 新功能包含对应测试
2. 所有测试通过
3. 覆盖率不降低
4. 更新相关文档

**快速验证**: `npm run test:fullstack`

---

*📝 最后更新: 2025-01-31*  
*🚀 版本: 1.0.0*