# 测试方法论指南

> **版本**: 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 测试用例文档模板

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

```markdown
# [功能名称] 测试用例

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

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

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

## 3. 测试用例清单

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

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

## 5. 执行记录

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

## 6. 缺陷记录

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

### 3.2 测试报告模板

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

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

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

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

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

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

---

## 4. 流程规范

### 4.1 新功能上线流程

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

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

### 4.2 故障修复后流程

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

**强制要求**：
- 故障修复后必须补充相关自动化测试
- 测试通过才能宣布故障关闭

### 4.3 历史功能检查流程

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

**强制要求**：
- 缺失测试用例的功能必须补齐
- 废弃功能必须从测试用例目录移除或标注

---

## 5. 目录结构规范

```
docs/03-测试文档/
├── 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 开发环境

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

#### 9.2.2 测试环境

```bash
# .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)

```yaml
# .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)

```yaml
- 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 测试阶段

```yaml
- 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)

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

```python
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-产品需求/`
- 项目管理：`../07-项目管理/`
- 历史归档：`../08-历史归档/`

---

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