docs(admin-service): 添加完整测试执行指南和数据库测试脚本
新增文件: - TEST_EXECUTION_GUIDE.md: 完整的测试执行指南 - 三层测试说明（单元/集成/E2E） - 数据库依赖说明 - 多种测试执行方法（本地/WSL2/Docker） - 常见问题排查 - CI/CD 配置示例 - scripts/test-with-docker-db.sh: WSL2完整测试脚本 - 自动启动PostgreSQL容器 - 运行所有测试层级 - 生成覆盖率报告 - 自动清理 测试层级说明: ✅ 单元测试: 不需要数据库（Value Objects/Entities/Mappers） ✅ 集成测试: 需要数据库（Repository/Handlers） ✅ E2E测试: 需要数据库（Controllers/API） 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Developer
parent
ce1f4ff9f9
commit
1e4e9dc342
|
|
@ -0,0 +1,357 @@
|
|||
# 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`
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
#!/bin/bash
|
||||
|
||||
# 在 WSL2 中运行完整测试（使用 Docker 提供的测试数据库）
|
||||
|
||||
set -e
|
||||
|
||||
BLUE='\033[0;34m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[0;33m'
|
||||
RED='\033[0;31m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
echo -e "${BLUE}=== Admin Service Complete Test Suite ===${NC}"
|
||||
|
||||
# 1. 启动 PostgreSQL 测试数据库容器
|
||||
echo -e "${YELLOW}1. Starting PostgreSQL test database...${NC}"
|
||||
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
|
||||
|
||||
echo -e "${YELLOW}Waiting for database to be ready...${NC}"
|
||||
sleep 5
|
||||
|
||||
# 2. 检查数据库连接
|
||||
echo -e "${YELLOW}2. Checking database connection...${NC}"
|
||||
until docker exec admin-test-db pg_isready -U postgres; do
|
||||
echo "Waiting for database..."
|
||||
sleep 2
|
||||
done
|
||||
echo -e "${GREEN}✓ Database is ready${NC}"
|
||||
|
||||
# 3. 设置环境变量
|
||||
export DATABASE_URL="postgresql://postgres:password@localhost:5433/admin_service_test?schema=public"
|
||||
export NODE_ENV=test
|
||||
|
||||
# 4. 安装依赖（如果需要）
|
||||
if [ ! -d "node_modules" ]; then
|
||||
echo -e "${YELLOW}3. Installing dependencies...${NC}"
|
||||
npm ci
|
||||
fi
|
||||
|
||||
# 5. 生成 Prisma 客户端
|
||||
echo -e "${YELLOW}4. Generating Prisma client...${NC}"
|
||||
npm run prisma:generate
|
||||
|
||||
# 6. 运行数据库迁移
|
||||
echo -e "${YELLOW}5. Running database migrations...${NC}"
|
||||
npx prisma migrate deploy
|
||||
|
||||
# 7. 运行单元测试
|
||||
echo -e "${BLUE}=== Running Unit Tests ===${NC}"
|
||||
npm run test:unit
|
||||
|
||||
# 8. 运行集成测试
|
||||
echo -e "${BLUE}=== Running Integration Tests ===${NC}"
|
||||
npm run test:integration
|
||||
|
||||
# 9. 运行 E2E 测试
|
||||
echo -e "${BLUE}=== Running E2E Tests ===${NC}"
|
||||
npm run test:e2e
|
||||
|
||||
# 10. 生成覆盖率报告
|
||||
echo -e "${BLUE}=== Generating Coverage Report ===${NC}"
|
||||
npm run test:cov
|
||||
|
||||
echo -e "${GREEN}=== All tests completed successfully! ===${NC}"
|
||||
|
||||
# 11. 清理
|
||||
echo -e "${YELLOW}Cleaning up test database...${NC}"
|
||||
docker stop admin-test-db
|
||||
|
||||
echo -e "${GREEN}✓ Test suite finished${NC}"
|
||||
echo -e "${BLUE}Coverage report: ./coverage/lcov-report/index.html${NC}"
|
||||
Loading…
Reference in New Issue