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. 全栈集成测试: 端到端业务流程

🚀 快速开始

前置条件

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

一键启动测试环境

# 初始化并启动所有测试服务
./test-setup.sh

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

🔧 测试命令大全

单独运行测试

# 前端单元测试
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

组合测试流程

# 运行所有测试（推荐）
npm run test:fullstack

# 仅前端测试
npm run test:frontend

# 仅后端测试  
npm run test:backend

# 快速开发测试
npm run test

开发模式

# 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

📊 测试数据管理

自动化测试数据生成

// 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
    }
  ]
}

手动创建测试数据

# 运行数据生成脚本
node test-data/seed-test-data.js

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

🎪 Gallery页面测试详解

E2E测试场景

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

集成测试工作流

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

🏗️ 测试环境配置

Docker Compose 服务配置

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

环境变量

# 测试环境变量
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 完整工作流测试

# 启动测试环境
./test-setup.sh

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

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

2. 前端组件E2E测试

# 运行Playwright E2E测试
npm run test:e2e

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

3. API性能和负载测试

# 后端压力测试
cd meteor-web-backend && npm run test:integration

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

🚨 故障排除

常见问题及解决方案

1. Docker服务启动失败

# 检查端口占用
lsof -i :5433 -i :4566 -i :3000 -i :3001

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

2. LocalStack连接失败

# 检查LocalStack健康状态
curl http://localhost:4566/_localstack/health

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

3. 数据库迁移问题

# 手动运行迁移
cd meteor-web-backend
npm run migrate:up

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

4. 前端E2E测试失败

# 安装Playwright浏览器
npx playwright install

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

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

📈 测试覆盖率报告

查看覆盖率

# 前端覆盖率
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 示例

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