358 lines
8.7 KiB
Markdown
358 lines
8.7 KiB
Markdown
# Admin Service 测试执行指南
|
||
|
||
## 测试层级说明
|
||
|
||
admin-service 包含三个层级的测试，每个层级有不同的依赖要求：
|
||
|
||
### 1. 单元测试（Unit Tests）
|
||
**位置**: `test/unit/`
|
||
**依赖**: ❌ 不需要数据库
|
||
**测试内容**:
|
||
- Value Objects (值对象验证逻辑)
|
||
- Entities (实体业务方法)
|
||
- Mappers (数据转换)
|
||
|
||
**运行命令**:
|
||
```bash
|
||
npm run test:unit
|
||
```
|
||
|
||
### 2. 集成测试（Integration Tests）
|
||
**位置**: `test/integration/`
|
||
**依赖**: ✅ 需要 PostgreSQL 数据库
|
||
**测试内容**:
|
||
- Repository (数据库CRUD操作)
|
||
- Handlers (命令/查询处理器)
|
||
|
||
**运行命令**:
|
||
```bash
|
||
# 需要先设置 DATABASE_URL 环境变量
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npm run test:integration
|
||
```
|
||
|
||
### 3. E2E 测试（End-to-End Tests）
|
||
**位置**: `test/e2e/`
|
||
**依赖**: ✅ 需要 PostgreSQL 数据库
|
||
**测试内容**:
|
||
- Controller (API端点、验证、错误处理)
|
||
|
||
**运行命令**:
|
||
```bash
|
||
# 需要先设置 DATABASE_URL 环境变量
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npm run test:e2e
|
||
```
|
||
|
||
## 完整测试执行流程
|
||
|
||
### 方法1: 使用本地 PostgreSQL
|
||
|
||
#### 步骤1: 安装 PostgreSQL
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo apt install postgresql
|
||
|
||
# macOS
|
||
brew install postgresql
|
||
|
||
# 或使用 Docker
|
||
docker run -d \
|
||
--name admin-test-db \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=password \
|
||
-e POSTGRES_DB=admin_service_test \
|
||
-p 5433:5432 \
|
||
postgres:16-alpine
|
||
```
|
||
|
||
#### 步骤2: 创建测试数据库
|
||
```bash
|
||
# 如果使用本地 PostgreSQL
|
||
createdb admin_service_test
|
||
|
||
# 如果使用 Docker，数据库已自动创建
|
||
```
|
||
|
||
#### 步骤3: 运行 Prisma 迁移
|
||
```bash
|
||
cd backend/services/admin-service
|
||
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npx prisma migrate deploy
|
||
```
|
||
|
||
#### 步骤4: 运行所有测试
|
||
```bash
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npm test
|
||
```
|
||
|
||
### 方法2: 使用 WSL2 + Docker（推荐）
|
||
|
||
#### 一键脚本
|
||
```bash
|
||
# 在 WSL2 中
|
||
cd /mnt/c/Users/dong/Desktop/rwadurian/backend/services/admin-service
|
||
chmod +x scripts/test-with-docker-db.sh
|
||
./scripts/test-with-docker-db.sh
|
||
```
|
||
|
||
该脚本会自动：
|
||
1. 启动 Docker PostgreSQL 容器
|
||
2. 等待数据库就绪
|
||
3. 运行数据库迁移
|
||
4. 执行所有测试（单元 + 集成 + E2E）
|
||
5. 生成覆盖率报告
|
||
6. 清理数据库容器
|
||
|
||
#### 手动步骤
|
||
```bash
|
||
# 1. 启动数据库
|
||
docker run -d --name admin-test-db --rm \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=password \
|
||
-e POSTGRES_DB=admin_service_test \
|
||
-p 5433:5432 \
|
||
postgres:16-alpine
|
||
|
||
# 2. 等待数据库就绪
|
||
sleep 5
|
||
|
||
# 3. 运行迁移
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npx prisma migrate deploy
|
||
|
||
# 4. 运行测试
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npm test
|
||
|
||
# 5. 清理
|
||
docker stop admin-test-db
|
||
```
|
||
|
||
### 方法3: 使用 Docker Compose
|
||
|
||
```bash
|
||
cd backend/services/admin-service
|
||
|
||
# 启动并运行测试
|
||
docker-compose -f docker-compose.test.yml up --build
|
||
|
||
# 清理
|
||
docker-compose -f docker-compose.test.yml down -v
|
||
```
|
||
|
||
## 分类测试执行
|
||
|
||
### 只运行单元测试（无需数据库）
|
||
```bash
|
||
npm run test:unit
|
||
```
|
||
**预期输出**: 所有 Value Object, Entity, Mapper 测试通过
|
||
|
||
### 只运行集成测试（需要数据库）
|
||
```bash
|
||
# 1. 确保数据库运行中
|
||
docker ps | grep admin-test-db
|
||
|
||
# 2. 运行集成测试
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npm run test:integration
|
||
```
|
||
**预期输出**: Repository 和 Handler 测试通过
|
||
|
||
### 只运行 E2E 测试（需要数据库）
|
||
```bash
|
||
# 1. 确保数据库运行中
|
||
docker ps | grep admin-test-db
|
||
|
||
# 2. 运行 E2E 测试
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npm run test:e2e
|
||
```
|
||
**预期输出**: Controller API 端点测试通过
|
||
|
||
## 覆盖率报告
|
||
|
||
### 生成覆盖率报告
|
||
```bash
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npm run test:cov
|
||
```
|
||
|
||
### 查看覆盖率
|
||
```bash
|
||
# HTML 报告
|
||
open coverage/lcov-report/index.html
|
||
|
||
# 或在 WSL 中
|
||
explorer.exe coverage/lcov-report/index.html
|
||
```
|
||
|
||
## 常见问题排查
|
||
|
||
### Q1: 集成/E2E 测试失败 - "Can't reach database server"
|
||
|
||
**原因**: 数据库未运行或连接信息错误
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查数据库是否运行
|
||
docker ps | grep admin-test-db
|
||
|
||
# 如果没有运行，启动数据库
|
||
docker run -d --name admin-test-db --rm \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=password \
|
||
-e POSTGRES_DB=admin_service_test \
|
||
-p 5433:5432 \
|
||
postgres:16-alpine
|
||
|
||
# 验证连接
|
||
docker exec admin-test-db psql -U postgres -d admin_service_test -c "SELECT 1;"
|
||
```
|
||
|
||
### Q2: Prisma 迁移失败
|
||
|
||
**原因**: 数据库schema不匹配
|
||
|
||
**解决**:
|
||
```bash
|
||
# 重置数据库
|
||
docker stop admin-test-db
|
||
docker run -d --name admin-test-db --rm \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=password \
|
||
-e POSTGRES_DB=admin_service_test \
|
||
-p 5433:5432 \
|
||
postgres:16-alpine
|
||
|
||
# 重新运行迁移
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test" \
|
||
npx prisma migrate deploy
|
||
```
|
||
|
||
### Q3: 端口冲突
|
||
|
||
**原因**: 5433 端口已被占用
|
||
|
||
**解决**:
|
||
```bash
|
||
# 查找占用端口的进程
|
||
lsof -i :5433
|
||
|
||
# 或更改数据库端口
|
||
docker run -d --name admin-test-db --rm \
|
||
-e POSTGRES_USER=postgres \
|
||
-e POSTGRES_PASSWORD=password \
|
||
-e POSTGRES_DB=admin_service_test \
|
||
-p 5434:5432 \
|
||
postgres:16-alpine
|
||
|
||
# 更新 DATABASE_URL
|
||
DATABASE_URL="postgresql://postgres:password@localhost:5434/admin_service_test" \
|
||
npm test
|
||
```
|
||
|
||
### Q4: WSL2 中 Docker 不可用
|
||
|
||
**原因**: Docker Desktop 未启动或 WSL2 集成未配置
|
||
|
||
**解决**:
|
||
1. 启动 Docker Desktop
|
||
2. 在 Docker Desktop 设置中启用 WSL2 集成
|
||
3. 在 WSL2 中验证: `docker --version`
|
||
|
||
## 测试结果示例
|
||
|
||
### 成功的测试运行
|
||
```
|
||
PASS test/unit/domain/value-objects/version-code.vo.spec.ts
|
||
PASS test/unit/domain/value-objects/version-name.vo.spec.ts
|
||
PASS test/unit/domain/value-objects/file-size.vo.spec.ts
|
||
PASS test/unit/domain/value-objects/file-sha256.vo.spec.ts
|
||
PASS test/unit/domain/entities/app-version.entity.spec.ts
|
||
PASS test/unit/infrastructure/mappers/app-version.mapper.spec.ts
|
||
PASS test/integration/repositories/app-version.repository.spec.ts
|
||
PASS test/integration/handlers/create-version.handler.spec.ts
|
||
PASS test/e2e/version.controller.spec.ts
|
||
|
||
Test Suites: 9 passed, 9 total
|
||
Tests: ~100 passed, ~100 total
|
||
Coverage: 85%+ (varies by component)
|
||
Time: ~30s
|
||
```
|
||
|
||
## 持续集成（CI）配置
|
||
|
||
### GitHub Actions 示例
|
||
```yaml
|
||
name: Tests
|
||
|
||
on: [push, pull_request]
|
||
|
||
jobs:
|
||
test:
|
||
runs-on: ubuntu-latest
|
||
|
||
services:
|
||
postgres:
|
||
image: postgres:16-alpine
|
||
env:
|
||
POSTGRES_USER: postgres
|
||
POSTGRES_PASSWORD: password
|
||
POSTGRES_DB: admin_service_test
|
||
options: >-
|
||
--health-cmd pg_isready
|
||
--health-interval 10s
|
||
--health-timeout 5s
|
||
--health-retries 5
|
||
ports:
|
||
- 5432:5432
|
||
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- name: Setup Node.js
|
||
uses: actions/setup-node@v3
|
||
with:
|
||
node-version: '20'
|
||
|
||
- name: Install dependencies
|
||
run: npm ci
|
||
|
||
- name: Generate Prisma client
|
||
run: npm run prisma:generate
|
||
|
||
- name: Run migrations
|
||
run: npx prisma migrate deploy
|
||
env:
|
||
DATABASE_URL: postgresql://postgres:password@localhost:5432/admin_service_test
|
||
|
||
- name: Run tests
|
||
run: npm test
|
||
env:
|
||
DATABASE_URL: postgresql://postgres:password@localhost:5432/admin_service_test
|
||
|
||
- name: Upload coverage
|
||
uses: codecov/codecov-action@v3
|
||
with:
|
||
files: ./coverage/lcov.info
|
||
```
|
||
|
||
## 总结
|
||
|
||
| 测试类型 | 需要数据库 | 命令 | 测试文件数 |
|
||
|---------|----------|------|-----------|
|
||
| 单元测试 | ❌ | `npm run test:unit` | 6 |
|
||
| 集成测试 | ✅ | `npm run test:integration` | 2 |
|
||
| E2E测试 | ✅ | `npm run test:e2e` | 1 |
|
||
| 全部测试 | ✅ | `npm test` | 9 |
|
||
| 覆盖率 | ✅ | `npm run test:cov` | 9 |
|
||
|
||
**推荐执行流程**:
|
||
1. 快速验证: `npm run test:unit` (无需数据库，~5秒)
|
||
2. 完整测试: 启动数据库 → `npm test` (~30秒)
|
||
3. 查看覆盖率: `open coverage/lcov-report/index.html`
|