# 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`