dingdanquanliucheng/TESTING_GUIDE.md

# 订单全流程管理系统 - 自动化测试指南

## 📋 目录

1. [测试概览](#测试概览)
2. [环境准备](#环境准备)
3. [后端测试](#后端测试)
4. [前端 E2E 测试](#前端-e2e-测试)
5. [测试覆盖率](#测试覆盖率)
6. [CI/CD 集成](#cicd-集成)
7. [常见问题](#常见问题)

---

## 测试概览

### 测试架构

```
测试金字塔
┌─────────────────────────────────────────────┐
│          E2E 测试 (Playwright)              │  10%
│     web-admin / web-sales 前端页面测试       │
├─────────────────────────────────────────────┤
│          API 集成测试 (pytest)               │  30%
│     后端接口 + 数据库 + 状态流转测试         │
├─────────────────────────────────────────────┤
│          单元测试 (pytest)                   │  60%
│     Service/Repository 层业务逻辑测试        │
└─────────────────────────────────────────────┘
```

### 测试用例统计

| 模块 | 文件 | 用例数 | P0 | P1 | P2 |
|------|------|--------|----|----|-----|
| 登录鉴权 | test_auth.py | 18 | 12 | 6 | 0 |
| 订单管理 | test_orders.py | 22 | 14 | 8 | 0 |
| 订单取消 | test_order_cancel.py | 12 | 10 | 2 | 0 |
| 司机任务 | test_logistics.py | 16 | 12 | 3 | 1 |
| 客户管理 | test_customers.py | 10 | 4 | 4 | 2 |
| 产品管理 | test_products.py | 10 | 2 | 6 | 2 |
| 供应商管理 | test_suppliers.py | 7 | 3 | 3 | 1 |
| 系统管理 | test_system.py | 18 | 10 | 8 | 0 |
| 提醒中心 | test_reminders.py | 10 | 5 | 5 | 0 |
| 报表统计 | test_reports.py | 8 | 0 | 8 | 0 |
| 配置管理 | test_configs.py | 10 | 3 | 7 | 0 |
| 审计日志 | test_audit.py | 10 | 4 | 6 | 0 |
| 文件管理 | test_files.py | 6 | 0 | 5 | 1 |
| AI 识别 | test_ai.py | 6 | 0 | 5 | 1 |
| 端到端 | test_e2e.py | 12 | 10 | 2 | 0 |
| **合计** | **15 个文件** | **175** | **89** | **73** | **8** |

---

## 环境准备

### 1. 后端环境

```bash
# 进入后端目录
cd backend

# 安装依赖
pip install -r requirements.txt

# 安装测试依赖
pip install pytest pytest-asyncio httpx pytest-cov
```

### 2. 前端 E2E 环境

```bash
# 进入 E2E 测试目录
cd e2e

# 安装依赖
npm install

# 安装 Playwright 浏览器
npx playwright install chromium
```

### 3. 环境变量配置

创建 `backend/.env.test` 文件：

```env
APP_ENV=test
SECRET_KEY=test-secret-key-for-testing
JWT_EXPIRE_MINUTES=60
MYSQL_DATABASE=:memory:
AI_PROVIDER=mock
```

---

## 后端测试

### 运行全部测试

```bash
cd backend
python -m pytest tests/ -v
```

### 按优先级运行

```bash
# 只运行 P0 测试（关键路径）
python -m pytest tests/ -v -m "p0"

# 只运行 P1 测试
python -m pytest tests/ -v -m "p1"

# 运行 P0 和 P1 测试
python -m pytest tests/ -v -m "p0 or p1"
```

### 按模块运行

```bash
# 登录鉴权测试
python -m pytest tests/test_auth.py -v

# 订单管理测试
python -m pytest tests/test_orders.py -v

# 订单取消测试
python -m pytest tests/test_order_cancel.py -v

# 司机任务测试
python -m pytest tests/test_logistics.py -v

# 端到端测试
python -m pytest tests/test_e2e.py -v
```

### 生成测试覆盖率报告

```bash
# 生成覆盖率报告
python -m pytest tests/ --cov=app --cov-report=html

# 查看报告
# 打开 htmlcov/index.html
```

### 测试输出示例

```
============================= test session starts =============================
platform win32 -- Python 3.10.0, pytest-7.4.0
collected 175 items

tests/test_auth.py::TestLoginSuccess::test_admin_login_success PASSED      [  5%]
tests/test_auth.py::TestLoginSuccess::test_salesman_login_success PASSED    [ 11%]
tests/test_auth.py::TestLoginFailure::test_wrong_password PASSED            [ 17%]
...

======================== 175 passed in 45.23s ================================
```

---

## 前端 E2E 测试

### 运行全部测试

```bash
cd e2e
npx playwright test
```

### 运行特定测试文件

```bash
# 登录测试
npx playwright test tests/admin-login.spec.js

# 订单管理测试
npx playwright test tests/admin-orders.spec.js

# 业务员创建订单测试
npx playwright test tests/sales-order-create.spec.js
```

### 有头模式运行（可视化）

```bash
npx playwright test --headed
```

### 调试模式

```bash
npx playwright test --debug
```

### UI 模式（交互式）

```bash
npx playwright test --ui
```

### 查看测试报告

```bash
npx playwright show-report
```

---

## 测试覆盖率

### 后端覆盖率目标

| 模块 | 目标覆盖率 | 当前状态 |
|------|------------|----------|
| API 路由层 | 90% | 待测试 |
| Service 层 | 85% | 待测试 |
| Repository 层 | 80% | 待测试 |
| Model 层 | 95% | 待测试 |

### 生成覆盖率报告

```bash
cd backend
python -m pytest tests/ --cov=app --cov-report=html --cov-report=term-missing
```

### 查看未覆盖代码

```bash
python -m pytest tests/ --cov=app --cov-report=term-missing | grep "TOTAL"
```

---

## CI/CD 集成

### GitHub Actions 示例

创建 `.github/workflows/test.yml`：

```yaml
name: 自动化测试

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  backend-tests:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          
      - name: Install dependencies
        run: |
          cd backend
          pip install -r requirements.txt
          pip install pytest pytest-cov
                    
      - name: Run tests
        run: |
          cd backend
          python -m pytest tests/ -v --cov=app --cov-report=xml
                    
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          file: backend/coverage.xml

  frontend-e2e:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: |
          cd e2e
          npm install
          npx playwright install chromium
                    
      - name: Run E2E tests
        run: |
          cd e2e
          npx playwright test
                    
      - name: Upload test results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: playwright-report
          path: e2e/playwright-report/
```

### GitLab CI 示例

创建 `.gitlab-ci.yml`：

```yaml
stages:
  - test

backend-tests:
  stage: test
  image: python:3.10
  script:
    - cd backend
    - pip install -r requirements.txt
    - pip install pytest pytest-cov
    - python -m pytest tests/ -v --cov=app
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: backend/coverage.xml

frontend-e2e:
  stage: test
  image: mcr.microsoft.com/playwright:v1.40.0-jammy
  script:
    - cd e2e
    - npm install
    - npx playwright test
  artifacts:
    when: always
    paths:
      - e2e/playwright-report/
```

---

## 常见问题

### Q1: 测试数据库连接失败

**问题**: `pytest` 报错 `ModuleNotFoundError: No module named 'backend'`

**解决**: 确保在项目根目录运行测试，或设置 `PYTHONPATH`：

```bash
# 方法 1: 在 backend 目录运行
cd backend
python -m pytest tests/

# 方法 2: 设置 PYTHONPATH
set PYTHONPATH=D:\work\python\coding\dingdanquanliucheng
python -m pytest backend/tests/
```

### Q2: Playwright 浏览器未安装

**问题**: `Error: browserType.launch: Executable doesn't exist`

**解决**:

```bash
cd e2e
npx playwright install chromium
```

### Q3: 前端服务未启动

**问题**: `page.goto: net::ERR_CONNECTION_REFUSED`

**解决**: 确保前端开发服务器已启动：

```bash
# 启动 web-admin
cd frontend/web-admin
npm run dev

# 启动 web-sales
cd frontend/web-sales
npm run dev
```

### Q4: 测试数据污染

**问题**: 测试之间数据相互影响

**解决**: 测试使用 SQLite 内存数据库，每个测试函数独立事务，测试结束后自动回滚。如果仍有问题，检查 `conftest.py` 中的 fixture 配置。

### Q5: 如何添加新的测试用例

**步骤**:

1. 在 `backend/tests/` 目录创建或编辑测试文件
2. 使用 `@pytest.mark` 添加测试标记（p0, p1, p2 等）
3. 使用 fixtures（如 `client`, `admin_headers`, `make_order`）简化测试代码
4. 运行测试验证：`python -m pytest tests/test_your_file.py -v`

**示例**:

```python
import pytest

@pytest.mark.p0
class TestYourFeature:
    def test_your_case(self, client, admin_headers):
        """测试用例描述。"""
        resp = client.get("/api/your-endpoint", headers=admin_headers)
        assert resp.status_code == 200
        data = resp.json()
        assert data["code"] == 0
```

---

## 测试用例清单

### P0 关键路径（必须通过）

- [ ] AUTH-001: 正常登录
- [ ] AUTH-002: 密码错误
- [ ] AUTH-003: 角色不匹配
- [ ] AUTH-004: 停用用户登录
- [ ] AUTH-005: 无 token 访问
- [ ] ORD-001: 创建草稿订单
- [ ] ORD-002: 新客户自动入库
- [ ] ORD-003: 利润计算
- [ ] ORD-007: 提交审核成功
- [ ] ORD-009: 管理层审批通过
- [ ] ORD-010: 管理层审批退回
- [ ] CAN-001: 草稿订单取消
- [ ] CAN-002: 待审核订单取消
- [ ] CAN-003: 已审批订单取消申请
- [ ] CAN-005: 取消审批通过
- [ ] TASK-001: 创建司机任务
- [ ] TASK-004: 司机接单
- [ ] TASK-006: 司机揽货
- [ ] TASK-008: 司机送达
- [ ] E2E-001: 完整订单流程
- [ ] E2E-008: 草稿取消流程
- [ ] E2E-009: 已通过取消流程

### P1 核心功能

- [ ] 客户 CRUD
- [ ] 产品 CRUD
- [ ] 供应商 CRUD
- [ ] 系统用户/角色/菜单管理
- [ ] 提醒中心
- [ ] 报表统计
- [ ] 配置管理
- [ ] 审计日志

---

## 联系方式

如有测试相关问题，请联系开发团队。

---

**最后更新**: 2026-06-10