tests/stress/README.md

# PDF 导出压力测试工具

用于测量 PDF 导出后端 (`/api/generate_pdf`) 的并发承载能力（同时能有多少用户导出 PDF）。

## 文件

| 文件 | 说明 |
|------|------|
| `payload-generator.js` | 生成确定性的仿真 PDF HTML 负载（文本 + Shiki 代码块 + base64 图片） |
| `run-stress-test.js` | 主压力测试脚本：按并发梯度打请求，统计成功率/延迟/吞吐 |
| `monitor-docker.js` | 并行监控 docker 容器 CPU/内存，与压力测试结果关联 |
| `verify-pdf-output.js` | 生成一份 PDF 保存到磁盘，验证输出为真实 PDF（`%PDF-1.x` 魔数） |
| `test-widget-batch.js` | 批量 widget 渲染验证（模拟 PDF/DOCX 导出的 `render_charts` 调用） |
| `results/` | 测试报告 JSON + 监控 JSON |

## 用法

```bash
# 基线/优化后对比测试（medium 负载）
node tests/stress/run-stress-test.js \
  --base http://localhost:17861 \
  --concurrency 1,2,4,6,8 \
  --total 8 \
  --profile medium \
  --settle-ms 3000 \
  --tag opt-pool4

# 并行监控 docker 资源（在另一个终端运行）
node tests/stress/monitor-docker.js \
  --containers pdf-test,pdf-prod \
  --interval 2000 \
  --duration 240000 \
  --out tests/stress/results/monitor-x.json

# 校验 PDF 输出质量
node tests/stress/verify-pdf-output.js

# 验证批量 widget 渲染
node tests/stress/test-widget-batch.js
```

## 参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--base` | `http://localhost:17861` | 后端地址（17861=测试容器，7860=生产容器） |
| `--concurrency` | `1,2,4,6,8` | 并发梯度（逗号分隔，每个梯度跑 `--total` 个请求） |
| `--total` | `20` | 每个并发梯度下总请求数 |
| `--profile` | `medium` | 负载规格：`small`(62KB) / `medium`(375KB+3图) / `large`(1.24MB+10图) |
| `--settle-ms` | `10000` | 每个梯度之间的冷却时间，让内存回落 |
| `--tag` | `` | 报告文件名后缀，用于区分基线/优化 |
| `--timeout-ms` | `180000` | 单请求超时 |

## 报告解读

- `throughputPerMin` 基于**墙钟时间**（该梯度内实际完成的请求数/分钟），反映系统真实吞吐。
- `latencyMs` 是每个请求从发起到收到响应的耗时（含排队等待）。
- 失败分类：`500`=服务端错误，`conn/...`=连接层错误。

## 重要提示

1. **本机 docker 不能完全模拟 Hugging Face**：HF 免费版 = 2 vCPU / 16GB；本机 docker 为 16 核。本机测出的并发上限是 HF 的**上界**，HF 上需按 `PDF_POOL_SIZE=2` 部署。
2. 测试前确认 `pdf-test` 容器已用最新代码重建。
3. 机器上还跑着其他系统（如 xianzhi-*），测试不要设置过大的并发，避免干扰。