dingdanquanliucheng/TESTING_GUIDE.md

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

📋 目录

1. 测试概览
2. 环境准备
3. 后端测试
4. 前端 E2E 测试
5. 测试覆盖率
6. CI/CD 集成
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. 后端环境

# 进入后端目录
cd backend

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

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

2. 前端 E2E 环境

# 进入 E2E 测试目录
cd e2e

# 安装依赖
npm install

# 安装 Playwright 浏览器
npx playwright install chromium

3. 环境变量配置

创建 backend/.env.test 文件：

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

---

后端测试

运行全部测试

cd backend
python -m pytest tests/ -v

按优先级运行

# 只运行 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"

按模块运行

# 登录鉴权测试
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

生成测试覆盖率报告

# 生成覆盖率报告
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 测试

运行全部测试

cd e2e
npx playwright test

运行特定测试文件

# 登录测试
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

有头模式运行（可视化）

npx playwright test --headed

调试模式

npx playwright test --debug

UI 模式（交互式）

npx playwright test --ui

查看测试报告

npx playwright show-report

---

测试覆盖率

后端覆盖率目标

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

生成覆盖率报告

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

查看未覆盖代码

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

---

CI/CD 集成

GitHub Actions 示例

创建 .github/workflows/test.yml：

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：

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：

# 方法 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

解决:

cd e2e
npx playwright install chromium

Q3: 前端服务未启动

问题: page.goto: net::ERR_CONNECTION_REFUSED

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

# 启动 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

示例:

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