# ptestx 性能基准测试计划

**版本**: v1.1.0  
**日期**: 2026-02-12  
**状态**: 进行中  

---

## 0. CI 环境说明 ⚠️

### 性能目标说明

本测试计划的性能目标基于**本地开发环境**（4核 CPU、16GB 内存）设定。

**CI 环境（如 GitHub Actions）由于资源限制，性能可能下降 2-4 倍**：
- GitHub Actions 标准运行器：2 核共享 CPU、7GB 内存
- 邻居效应（Noisy Neighbors）：宿主机上其他容器的资源竞争
- 性能波动：比本地环境更不稳定

### CI 自适应目标

测试脚本会自动检测 CI 环境并调整目标值：

| 测试项 | 本地目标 | CI 目标（3.5x 缓冲） | 说明 |
|--------|---------|---------------------|------|
| 100K 姓名生成 | < 3s | < 10.5s | 确保 CI 通过率 |
| 10K 邮箱生成 | < 1s | < 3.5s | 确保 CI 通过率 |
| 1M UUID 生成 | < 60s | < 210s | 确保 CI 通过率 |

**注意**：CI 目标值较宽松，主要用于检测性能退化（regression），而非精确性能测量。

---

## 1. 测试目标

### 1.1 总体目标

建立 ptestx 测试框架的性能基准，确保在十万至百万级数据量下仍能保持高性能，为生产环境使用提供性能参考。

### 1.2 具体指标（本地环境）

> **💡 提示**：以下目标值适用于本地开发环境。CI 环境请参见第 0 节的自适应目标。

| 指标类别 | 测试项 | 本地目标 | CI 目标 | 说明 |
|---------|--------|---------|---------|------|
| **数据生成** | 10万条数据生成 | < 3秒 | < 10.5秒 | 批量数据生成能力 |
| **数据生成** | 100万条数据生成 | < 60秒 | < 210秒 | 大规模数据生成能力 |
| **数据生成** | 内存占用 | < 2GB | 100万条数据内存使用 |
| **套件管理** | 1000个用例创建 | < 1秒 | 大套件创建性能 |
| **套件管理** | 10000个用例创建 | < 10秒 | 超大规模套件性能 |
| **并发执行** | 100个用例并行 | < 30秒 | 中等规模并发 |
| **并发执行** | 1000个用例并行 | < 5分钟 | 大规模并发能力 |
| **并发加速比** | 并行 vs 串行 | > 3x | 4核环境 |
| **报告生成** | 1000个结果报告 | < 2秒 | 大报告生成能力 |
| **报告生成** | 10000个结果报告 | < 10秒 | 超大规模报告 |
| **隔离引擎** | 环境创建 | < 1秒 | Basic引擎 |
| **隔离引擎** | 环境创建 | < 5秒 | Virtualenv引擎 |

---

## 2. 测试范围

### 2.1 核心模块测试

```
性能测试覆盖范围:
├── 数据生成 (Data Generation)
│   ├── 10万条数据生成测试
│   ├── 100万条数据生成测试
│   └── 内存使用测试
├── 测试套件管理 (Suite Management)
│   ├── 1000个用例套件操作
│   ├── 10000个用例套件操作
│   └── 依赖关系处理性能
├── 并发执行 (Parallel Execution)
│   ├── 100个用例并发执行
│   ├── 1000个用例并发执行
│   ├── 带依赖的复杂并发
│   └── 加速比测试
├── 报告生成 (Report Generation)
│   ├── 1000个结果报告
│   ├── 10000个结果报告
│   └── HTML渲染性能
└── 隔离引擎 (Isolation Engines)
    ├── Basic引擎性能
    ├── Virtualenv引擎性能
    └── Docker引擎性能（可选）
```

### 2.2 测试数据规模

| 测试级别 | 数据量 | 用例数 | 适用场景 |
|---------|--------|--------|----------|
| **基准级** | 1,000 | 100 | 快速验证、CI测试 |
| **标准级** | 100,000 | 1,000 | 常规性能测试 |
| **压力级** | 1,000,000 | 10,000 | 压力测试、极限验证 |

---

## 3. 测试环境

### 3.1 硬件要求

**标准测试环境**:
- CPU: 4核以上
- 内存: 16GB+
- 磁盘: SSD
- 网络: 千兆网卡

**压力测试环境**:
- CPU: 8核以上
- 内存: 32GB+
- 磁盘: NVMe SSD
- Docker: 支持（用于Docker引擎测试）

### 3.2 软件环境

- Python: 3.12+
- OS: Ubuntu 22.04 / macOS / Windows 11
- Docker: 24.0+（可选）
- pytest: 9.0+

---

## 4. 测试用例设计

### 4.1 数据生成性能测试

#### TEST-DG-001: 10万条数据生成
```yaml
目标: 测试大批量数据生成性能
数据量: 100,000条
数据类型: name, email, uuid, address
期望时间: < 5秒
内存限制: < 500MB
```

#### TEST-DG-002: 100万条数据生成
```yaml
目标: 测试超大规模数据生成能力
数据量: 1,000,000条
数据类型: name
期望时间: < 60秒
内存限制: < 2GB
输出格式: CSV（流式写入，避免内存溢出）
```

#### TEST-DG-003: 内存使用测试
```yaml
目标: 监控大规模数据生成时的内存使用
数据量: 100,000条
监控项: 峰值内存、平均内存
期望: 无内存泄漏
```

### 4.2 套件管理性能测试

#### TEST-SM-001: 1000个用例套件创建
```yaml
目标: 测试大套件创建性能
用例数: 1,000个
依赖关系: 无
期望时间: < 1秒
```

#### TEST-SM-002: 1000个用例带依赖创建
```yaml
目标: 测试复杂依赖套件创建
用例数: 1,000个
依赖关系: 链式依赖（每10个一组）
期望时间: < 2秒
```

#### TEST-SM-003: 10000个用例套件创建
```yaml
目标: 测试超大规模套件
用例数: 10,000个
依赖关系: 简单依赖
期望时间: < 10秒
内存限制: < 1GB
```

#### TEST-SM-004: 拓扑排序性能
```yaml
目标: 测试依赖解析性能
用例数: 10,000个
依赖复杂度: 高
期望时间: < 5秒
```

### 4.2b 实际工程场景测试

> **说明**: 以上测试基于 `CaseRef` 模型（1 CaseRef = 1 场景），以下测试基于实际工程实践

#### 场景说明

| 场景类型 | 实际案例 | 用例密度 | 环境共享 |
|---------|---------|---------|---------|
| **脚本内多方法** | `test_login.py` 包含 10 个测试方法 | 高 | 类级别 setup |
| **SQL批量验证** | `test_db.sql` 包含 1000 条验证 SQL | 极高 | 单 DB 连接 |
| **集成测试** | `test_order_flow.py` 包含 50 个步骤 | 高 | 模块级别 env |

#### TEST-SM-005: 高密度用例脚本（100 Cases/文件）
```yaml
目标: 模拟普通测试文件包含多个用例方法
场景: 一个 Python 文件包含 100 个测试方法
环境: 共享 class-level setup（1 次初始化）
用例数: 100 Cases
期望时间: < 0.5秒（不含环境初始化）
说明: 类似 pytest 的 test class 包含多个 test method
```

#### TEST-SM-006: 大型集成测试脚本（500 Cases/文件）
```yaml
目标: 模拟大型集成测试文件
场景: 一个测试脚本包含 500 个测试步骤
环境: 共享 module-level setup（1 次初始化）
用例数: 500 Cases
期望时间: < 2秒
说明: 复杂业务流程测试，如电商下单全流程
```

#### TEST-SM-007: SQL批量验证脚本（1000 SQL/文件）
```yaml
目标: 模拟数据库批量验证场景
场景: 单个 SQL 文件包含 1000 条验证语句
连接: 复用 1 个 DB 连接
SQL数: 1000 条
期望时间: < 3秒
说明: 数据库迁移验证、数据质量检查等
```

#### TEST-SM-008: 版本迭代用例冗余模拟
```yaml
目标: 模拟多版本迭代后的用例管理性能
场景: 
  - v1.0: 功能A（100 Cases）
  - v2.0: 功能B依赖A（新增 100 Cases，其中 30 个重复测试A）
  - v3.0: 功能C依赖A+B（新增 100 Cases，其中 50 个重复测试）
总用例数: 300 Cases（有效覆盖约 200 Cases）
期望时间: < 3秒
说明: 测试框架在存在冗余用例时的性能表现
```

### 4.3 并发执行性能测试

#### TEST-PE-001: 100个用例串行执行
```yaml
目标: 基准串行性能
用例数: 100个
每个用例耗时: 50ms（模拟）
期望时间: ~5秒
```

#### TEST-PE-002: 100个用例并行执行
```yaml
目标: 测试中等规模并发
用例数: 100个
工作线程: 4个
期望时间: < 2秒
加速比: > 2x
```

#### TEST-PE-003: 1000个用例并行执行
```yaml
目标: 测试大规模并发能力
用例数: 1,000个
工作线程: 8个
每个用例耗时: 10ms
期望时间: < 5秒
加速比: > 3x
```

#### TEST-PE-004: 复杂依赖并发
```yaml
目标: 测试依赖处理下的并发性能
用例数: 500个
依赖关系: 多层级依赖树
工作线程: 4个
期望时间: < 10秒
```

### 4.4 报告生成性能测试

#### TEST-RG-001: 1000个结果报告
```yaml
目标: 测试大报告生成
结果数: 1,000个
通过率: 70%
包含附件: 是
期望时间: < 2秒
```

#### TEST-RG-002: 10000个结果报告
```yaml
目标: 测试超大规模报告
结果数: 10,000个
通过率: 80%
图表类型: 全部
期望时间: < 10秒
内存限制: < 1GB
```

#### TEST-RG-003: 历史报告加载
```yaml
目标: 测试历史报告系统
历史报告数: 100个
当前报告: 1000个结果
期望时间: < 3秒
```

### 4.5 隔离引擎性能测试

#### TEST-IE-001: Basic引擎基准
```yaml
目标: Basic引擎性能基准
操作: 创建、激活、执行命令
循环次数: 100次
期望: 平均 < 10ms/次
```

#### TEST-IE-002: Virtualenv引擎
```yaml
目标: Virtualenv引擎性能
操作: 创建环境、安装包、执行命令
循环次数: 10次
期望: 平均 < 5秒/次
```

---

## 5. 测试执行计划

### 5.1 执行频率

| 测试类型 | 执行时机 | 说明 |
|---------|----------|------|
| **快速基准** | 每次CI | 1,000数据量，快速验证 |
| **标准基准** | 每日/PR合并 | 10万数据量，标准测试 |
| **压力测试** | 每周/发布前 | 100万数据量，极限验证 |
| **全量测试** | 每月/大版本 | 全量级测试 |

### 5.2 CI/CD集成

```yaml
# .github/workflows/benchmark.yml
触发条件:
  - push: [main]
  - pull_request: [main]
  - workflow_dispatch: 手动触发
  - schedule: 每周日凌晨2点

执行步骤:
  1. 检出代码
  2. 设置Python 3.12环境
  3. 安装依赖
  4. 运行基准测试套件
  5. 上传结果报告
  6. 对比历史数据
  7. PR评论（性能变化）
```

---

## 6. 结果分析与报告

### 6.1 报告格式

**JSON报告**:
```json
{
  "metadata": {
    "version": "1.1.0",
    "timestamp": "2026-02-12T10:00:00Z",
    "python_version": "3.12.3",
    "cpu_count": 4,
    "memory_gb": 16
  },
  "results": {
    "data_generation": {
      "100k_names": {"value": 2.5, "unit": "s", "status": "pass"},
      "1m_names": {"value": 45.2, "unit": "s", "status": "pass"}
    }
  },
  "summary": {
    "total_tests": 20,
    "passed": 20,
    "failed": 0
  }
}
```

**Markdown报告**:
- 执行摘要
- 详细结果表格
- 性能趋势图
- 改进建议

### 6.2 性能回归检测

```python
# 回归检测逻辑
if current_value > baseline_value * 1.2:
    status = "regression"  # 性能下降 > 20%
elif current_value < baseline_value * 0.8:
    status = "improvement"  # 性能提升 > 20%
else:
    status = "stable"  # 性能稳定
```

---

## 7. 优化目标

### 7.1 短期目标（v1.2.0）

- [ ] 数据生成器支持流式生成（100万+数据）
- [ ] 套件管理优化（10,000用例 < 5秒）
- [ ] 报告生成优化（10,000结果 < 5秒）
- [ ] 内存使用优化（减少30%）

### 7.2 中期目标（v1.3.0）

- [ ] 支持分布式执行
- [ ] 数据库后端支持（大规模套件存储）
- [ ] 增量报告生成
- [ ] 智能缓存机制

### 7.3 长期目标（v2.0）

- [ ] 百万级用例管理
- [ ] 实时性能监控
- [ ] 自适应并发控制
- [ ] GPU加速（可选）

---

## 8. 执行命令

```bash
# 运行所有基准测试
python tests/performance/run_benchmarks.py

# 运行特定测试
pytest tests/performance/ -v -k "test_100k"

# 生成报告
python tests/performance/run_benchmarks.py --output-format=html

# 对比历史结果
python tests/performance/compare_benchmarks.py --baseline=2026-02-01.json
```

---

## 9. 附录

### 9.1 相关文档

- [性能测试实现](run_benchmarks.py)
- [CI工作流](../../.github/workflows/benchmark.yml)
- [测试结果目录](../../../benchmark_results/)

### 9.2 历史数据

基准结果保存在 `benchmark_results/` 目录：
- `benchmark_YYYYMMDD_HHMMSS.json` - 原始数据
- `benchmark_YYYYMMDD_HHMMSS.md` - 可读报告
- `benchmark_trend.csv` - 趋势数据

---

**维护者**: cp  
**最后更新**: 2026-02-12  
**文档版本**: 1.0
