wecom_it_smart_desk/docs/06-测试质量/00-测试规范/测试方法论指南.md

测试方法论指南

版本: v1.0 | 生效日期: 2026-07-14 | 维护人: Duckula

本规范定义 IT 智能服务台项目的测试策略、方法和流程。

---

1. 测试类型定义

1.1 测试分层模型

层级	测试类型	覆盖范围	工具/方法	产出物
Tier 0	基础设施测试	数据库、缓存、核心服务、工具类	pytest 单元测试	test_*.py
Tier 1	API 层测试	接口正确性、参数校验、权限控制	pytest + curl	test_*.py
Tier 2	集成测试	多模块交互、状态机、事务一致性	pytest	test_*.py
E2E	端到端测试	完整业务流程、用户体验	Playwright 浏览器自动化	测试报告 + 截图

---

2. 测试类型选择标准

2.1 判断决策树

新增功能/代码变更
    │
    ├── 仅修改工具类 / 工具函数 / 算法逻辑
    │   └── 选择：Tier 0 单元测试
    │   └── 判断标准：无外部依赖，纯函数逻辑
    │
    ├── 新增/修改 API 接口
    │   └── 选择：Tier 1 API 测试
    │   └── 判断标准：有 HTTP 端点、需要参数校验
    │
    ├── 多模块交互 / 状态流转 / 事务一致性
    │   └── 选择：Tier 2 集成测试
    │   └── 判断标准：涉及 2+ 服务/模块的数据流转
    │
    └── 核心业务流程 / 用户体验验证
        └── 选择：E2E 测试
        └── 判断标准：需要浏览器真实操作、多端交互

2.2 场景速查表

场景	推荐测试类型	必做级别
新增工具函数（如 TokenCounter）	Tier 0	必须
新增 API 端点	Tier 1	必须
修改数据库模型/迁移脚本	Tier 0 + Tier 1	必须
修改 WebSocket 逻辑	Tier 2	必须
修改前端交互流程	E2E	必须
登录/认证流程变更	E2E + Tier 1	必须
消息发送/AI 回复流程	E2E	必须
知识库/审批流程	Tier 1 + Tier 2	必须
安全/权限控制变更	Tier 1 + E2E	必须

---

3. 产出物标准

3.1 测试用例文档模板

每个功能测试用例文档应包含：

# [功能名称] 测试用例

> **功能模块**: xxx | **测试工程师**: xxx | **日期**: xxx

## 1. 测试范围
- 测试的 API/模块列表

## 2. 前置条件
- 测试账号、环境要求、依赖服务

## 3. 测试用例清单

| TC_ID | 场景 | 前置条件 | 测试步骤 | 预期结果 | 状态 |
|-------|------|---------|---------|---------|------|
| xxx   |      |         |         |         |      |

## 4. 测试数据
- 测试用账号、测试数据构造方式

## 5. 执行记录

| 日期 | 测试人员 | 环境 | 结果 |
|------|---------|------|------|
|      |         |      |      |

## 6. 缺陷记录

| 缺陷ID | 对应TC | 描述 | 严重程度 | 状态 |
|--------|--------|------|----------|------|
|        |        |      |          |      |

3.2 测试报告模板

# [版本/功能] 测试报告

> **测试工程师**: xxx | **日期**: xxx | **状态**: 通过/失败

## 测试概览
- 测试总数、通过数、失败数、跳过数

## 测试明细
| 用例类型 | 数量 | 通过 | 失败 |
|----------|------|------|------|
|          |      |      |      |

## Bug 历程
| Bug ID | 描述 | 影响 | 修复状态 |

## 结论
- 是否可发布
- 风险项

---

4. 流程规范

4.1 新功能上线流程

需求评审通过
    │
    ├── 1. 编写测试用例文档
    │   └── 路径: docs/06-测试质量/03-功能测试用例/
    │   └── 命名: [功能名]-测试用例-YYYYMMDD.md
    │
    ├── 2. 开发代码
    │
    ├── 3. 执行测试
    │   ├── Tier 0/1/2 → pytest
    │   └── E2E → Playwright
    │
    ├── 4. 产出测试报告
    │   └── 路径: docs/06-测试质量/04-版本测试报告/
    │   └── 命名: [功能名]-测试报告-YYYYMMDD.md
    │
    └── 5. 发布

强制要求：

• 测试用例文档必须在代码开发前完成初版
• 测试用例文档必须随功能上线同步更新
• 测试报告是发布的必要前置条件

4.2 故障修复后流程

故障发现 → 根因分析 → 修复代码
    │
    ├── 1. 定位受影响的测试用例
    │   └── 在 docs/06-测试质量/ 中搜索相关功能
    │
    ├── 2. 编写/更新自动化测试
    │   └── 在 backend/tests/ 中添加/更新 test_*.py
    │
    ├── 3. 执行自动化测试
    │   └── pytest -v
    │
    ├── 4. 如有 E2E 场景，补充 E2E 测试
    │   └── Playwright 浏览器自动化
    │
    └── 5. 更新测试用例文档
        └── 补充故障场景用例

强制要求：

• 故障修复后必须补充相关自动化测试
• 测试通过才能宣布故障关闭

4.3 历史功能检查流程

定期检查（建议每季度）
    │
    ├── 1. 列出所有已上线功能
    │   └── 参考 CHANGELOG.md / 版本发布记录
    │
    ├── 2. 检查是否存在测试用例文档
    │   └── docs/06-测试质量/03-功能测试用例/
    │
    ├── 3. 如缺失，补充测试用例文档
    │   └── 逆向分析功能 → 编写测试用例
    │
    ├── 4. 检查测试用例是否仍有效
    │   ├── 接口路径是否变更
    │   ├── 参数是否变化
    │   └── 功能是否已废弃
    │
    ├── 5. 处理废弃/替换的功能用例
    │   ├── 移动到 docs/11-历史归档/
    │   └── 更新 README.md 中的索引
    │
    └── 6. 产出检查报告

强制要求：

• 缺失测试用例的功能必须补齐
• 废弃功能必须从测试用例目录移除或标注

---

5. 目录结构规范

docs/06-测试质量/
├── 00-测试规范/                    # 本文档
│   └── 测试方法论指南.md
│
├── 01-综合报告/                    # 合并汇总类报告
│   └── QA_COMPREHENSIVE_REPORT.md
│
├── 02-E2E测试/                    # 端到端测试
│   ├── E2E-CHECKLIST-*.md         # 验收清单
│   └── e2e-screenshots/           # 截图证据
│
├── 03-功能测试用例/                # 功能级测试用例文档
│   ├── [功能名]-测试用例-YYYYMMDD.md
│   └── ...
│
├── 04-版本测试报告/                # 按版本/日期的测试报告
│   └── [功能名]-测试报告-YYYYMMDD.md
│
└── README.md                       # 分类索引

---

6. 命名约定

类型	命名格式	示例
测试用例文档	[功能名]-测试用例-YYYYMMDD.md	OTP绑定-测试用例-20260708.md
测试报告	[功能名]-测试报告-YYYYMMDD.md	登录功能-测试报告-20260706.md
E2E 报告	[功能名]-E2E验证报告-YYYYMMDD.md	方案A消息发送延时-E2E验证报告-20260708.md
测试代码文件	test_[模块名].py	test_otp_bind_flow.py

---

7. 质量门禁

7.1 发布门槛

测试类型	通过率要求	备注
Tier 0	100%	基础设施不能有失败
Tier 1	100%	API 必须全部通过
Tier 2	100%	集成测试必须通过
E2E	核心流程 100%	核心用户流程不可失败

7.2 阻断规则

• P0 级别故障：必须通过 E2E 验证才能发布
• 认证/安全变更：必须通过 Tier 1 + E2E 双重验证
• 数据库变更：必须通过 Tier 0 迁移测试

---

8. 测试数据管理规范

8.1 数据分类

数据类型	说明	管理方式
测试账号	坐席员工、管理员测试账号	固定账号，维护在配置文件中
Mock 数据	模拟的会话、消息、审批数据	代码中 fixtures 或独立 seed 文件
生产脱敏数据	从生产导出的脱敏数据	存储在 data/test/ 目录，严格访问控制
临时测试数据	每次测试生成的临时数据	测试用例自行清理，禁用手动清理

8.2 测试数据原则

• 隔离性：每个测试用例使用独立数据，不依赖其他测试的执行结果
• 可重复性：测试数据可重复使用，测试结果一致
• 清理机制：测试完成后自动清理临时数据，不污染环境
• 脱敏要求：从生产导出的数据必须脱敏（手机号、身份证号等）

8.3 测试数据目录结构

data/test/
├── README.md                    # 数据说明
├── accounts.json                # 测试账号配置
├── mock_sessions.json           # Mock 会话数据
└── seed/                       # 数据种子文件
    ├── conversations.json
    └── knowledge.json

8.4 测试账号规范

角色	user_id	用途
管理员	sxn	管理员功能测试
坐席	sxn	坐席功能测试
员工	test_user	员工端功能测试
Mock 用户	E2E_BROWSER	E2E 自动化测试

---

9. 测试环境配置标准

9.1 环境分类

环境	用途	数据库	特点
开发环境	本地开发调试	SQLite 内存	快速启动，无持久化
测试环境	自动化测试	PostgreSQL	与生产结构一致
预发布环境	上线前验证	生产数据副本	接近生产
生产环境	正式运行	PostgreSQL	真实数据

9.2 环境配置要求

9.2.1 开发环境

# .env 配置示例
DEV_MODE=true
DATABASE_URL=sqlite:///./test_dev.db
REDIS_URL=redis://localhost:6379
# 使用 Mock 服务，无需真实企微/Dify

9.2.2 测试环境

# .env 配置示例
DEV_MODE=false
DATABASE_URL=postgresql://test:test@localhost:5432/wecom_it_test
REDIS_URL=redis://localhost:6379/1
# 使用测试用企微应用/测试用 Dify
WECOM_APP_ID=xxx
DIFY_API_KEY=xxx

9.3 环境切换规则

场景	使用环境	理由
单元测试 (Tier 0)	开发环境 (SQLite)	快速、独立
API 测试 (Tier 1)	测试环境	验证真实数据库
集成测试 (Tier 2)	测试环境	多模块交互
E2E 测试	测试/预发布环境	接近生产
上线前验证	预发布环境	最终确认

9.4 环境健康检查

每次测试执行前必须检查：

• 数据库连接正常
• Redis 连接正常
• 后端服务可访问
• 依赖服务（Dify、RAGFlow 等）可用

---

10. CI/CD 集成测试规范

10.1 流水线阶段

代码提交 → 静态检查 → 单元测试 → 构建 → 集成测试 → E2E测试 → 部署
                              ↓           ↓         ↓
                           Tier 0     Tier 1/2   需要时

10.2 各阶段要求

10.2.1 静态检查阶段

检查项	工具	失败处理
Python 类型检查	mypy	阻断
代码格式	ruff / black	阻断
安全扫描	bandit	阻断

10.2.2 单元测试阶段 (Tier 0)

# .github/workflows/test.yml 示意
- name: Run Tier 0 tests
  run: |
    pytest backend/tests/test_*.py -v --tb=short
  timeout-minutes: 10

要求：

• 必须通过
• 覆盖率不做强制要求，但核心模块应覆盖

10.2.3 集成测试阶段 (Tier 1/2)

- name: Run Tier 1/2 tests
  run: |
    pytest backend/tests/test_api_*.py -v --tb=short
  timeout-minutes: 20
  services:
    postgres:
      image: postgres:15
      env:
        POSTGRES_DB: wecom_it_test
    redis:
      image: redis:7

要求：

• 使用独立的测试数据库
• 测试完成后清理数据

10.2.4 E2E 测试阶段

- name: Run E2E tests
  run: |
    pytest tests/e2e/ -v --tb=short
  timeout-minutes: 30
  conditions: ${{ github.event_name == 'pull_request' }}

要求：

• 仅在 PR 时执行
• 生产部署后可通过手动触发

10.3 分支策略

分支	执行测试	部署目标
feature/*	Tier 0 + Tier 1	不自动部署
bugfix/*	Tier 0 + Tier 1	不自动部署
main	全部 Tier	自动部署到测试环境
release/*	全部 Tier + E2E	预发布环境

10.4 失败处理

失败类型	处理方式
Tier 0 失败	阻断合并
Tier 1/2 失败	阻断合并
E2E 失败	警告，可选择是否阻断
超时	重试 1 次，仍失败则阻断

---

11. 附录

11.1 测试工具清单

用途	工具	配置
Python 单元/集成测试	pytest + pytest-asyncio	conftest.py
浏览器自动化	Playwright	Python binding
HTTP 测试	curl / httpx	直接调用 API
数据库测试	直接 SQL / SQLAlchemy	迁移脚本验证

11.2 配置文件模板

11.2.1 测试配置 (pytest.ini)

[pytest]
testpaths = backend/tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
asyncio_mode = auto
addopts = -v --tb=short

11.2.2 E2E 配置 (playwright.config.py)

import pytest

@pytest.fixture(scope="session")
def browser_type_launch_args(browser_type_launch_args):
    return {
        **browser_type_launch_args,
        "headless": True,
    }

11.3 相关文档

• 技术架构：../03-技术架构/
• 产品需求：../02-产品需求/
• 项目管理：../10-项目管理/
• 历史归档：../11-历史归档/

---

修订记录

版本	日期	变更内容	修改人
v1.0	2026-07-14	初始版本，整合测试方法、数据、环境、CI/CD规范	Duckula