locust-perf-framework

##它解决什么What it solves

在 Locust 之上加一层面向测试工程落地的组织方式：统一目录边界、命名规范、防覆盖的时间戳产物管理、命令封装，以及把 Locust 原始 CSV 二次加工成可直接汇报的中文 HTML 报告。

An organization layer on top of Locust: unified directory boundaries, naming rules, collision-proof timestamped artifacts, wrapped commands, and turning raw Locust CSV into decision-ready Chinese HTML reports.

$ 一体化命令封装One-command execution

`python -m tools.xxx` 只暴露并发 / 速率 / 时长 / 目标 / 数据等必要参数，自动生成时间戳目录与中文报告。命名 / 执行 / 报告一键完成

`python -m tools.xxx` exposes only essential params (users, rate, time, target, data) and auto-generates timestamped dirs and reports.Name / run / report in one shot

$ 防覆盖，可追溯Collision-proof, traceable

每次执行自动生成时间戳目录，目标已存在自动追加序号，杜绝重跑覆盖历史产物。

Every run gets a timestamped directory; existing targets auto-append a sequence number, so re-runs never overwrite history.

$ 中文 HTML 报告Chinese HTML reports

解析 Locust CSV + 失败明细，输出含 TPS / RT / 错误率趋势、请求级瓶颈、调用链热图的可汇报报告。

Parses Locust CSV + failure details into reports with TPS / RT / error-rate trends, per-request bottlenecks, and call-chain heatmaps.

$ LLM 辅助分析LLM-assisted analysis

经 `config/ai_apiclient.py`（OpenAI 兼容封装）为报告追加 AI 摘要，遵守「证据链 / 反证法 / 药方+复验」排查纪律。

Appends an AI summary via `config/ai_apiclient.py` (OpenAI-compatible), following evidence-chain / falsification / remedy-and-reverify discipline.

##快速开始Quick start

需要 Python ≥ 3.11，推荐 uv。

Requires Python ≥ 3.11; uv recommended.

# 安装

# Install

uv sync --extra dev
# 或 pip install -e .[dev]

# 跑一个示例：健康检查基准（headless）

# Run an example: health-check baseline (headless)

uv run locust -f locustfiles/locust_demo_health_baseline.py \
  --headless -u 1 -r 1 -t 10s

# 一体化入口：生成时间戳目录 + 中文报告

# One-command entry: timestamped dir + Chinese report

uv run python -m tools.report_builder \
  --scenario demo_health --test-type baseline \
  --stats-csv reports/raw/demo_health/<timestamp>/stats_stats.csv \
  --overview "示例：健康检查接口基准摸底" \
  --users 1 --spawn-rate "1 user/s" --run-time "10s" \
  --host "https://example.com"

# 监管入口：测试 / 校验 / 构建发布产物

# Governance entrypoints: test / validate / build

make test        # pytest + ruff
make code-clean  # 清理 + 校验 + uv build 产物
make code-clean  # clean + validate + uv build

##AI 对话协作AI-agent collaboration

内置「规划 → 脚本开发 → 报告分析」三 Agent 协作规则，Codex / Claude Code / DSH 等工具打开项目即可用自然语言驱动全流程压测。

Built-in three-agent rules (plan → script development → report analysis); Codex / Claude Code / DSH can drive the whole load-test flow in natural language.

Agent	Agent	职责	Responsibility
规划	Planning	确认背景 / 接口 / 类型 / 并发 / 指标 / 熔断	Confirm context / API / type / concurrency / metrics / circuit-break
脚本开发	Script dev	按方案生成 Locust 脚本与脱敏数据	Generate Locust scripts + sanitized data per plan
报告分析	Report analysis	多指标证据链归因，输出决策级中文报告	Multi-metric attribution; decision-grade Chinese report

##常见问题FAQ

需要 LLM 凭据吗？

Do I need an LLM credential?

不需要。LLM 分析是可选的；未配置环境变量不会真正调用，可加 `--no-llm-analysis` 跳过。请勿在仓库提交真实密钥。

No. LLM analysis is optional; without env config it never calls out (add `--no-llm-analysis` to skip). Never commit real credentials.

会覆盖历史报告吗？

Will it overwrite old reports?

不会。每次执行生成新时间戳目录，目标已存在自动追加序号，杜绝重跑覆盖。

No. Every run gets a fresh timestamped dir; existing targets auto-append a sequence number.

真实数据会上传到仓库吗？

Does real data get committed?

不会。`.gitignore` 默认忽略 `data/` 下的真实 txt/json/csv 与 `reports/`、`logs/` 产物，只保留脱敏示例。

No. `.gitignore` excludes real data under `data/` and all `reports/`/`logs/` artifacts; only sanitized examples are kept.

如何选测试类型？

How to pick a test type?

基准（建基线）/ 负载（正常负载）/ 压力（找崩溃点）/ 稳定性（长跑）/ 峰值（突发流量），按目标选择。

Baseline (baseline) / Load (normal) / Stress (find breaking point) / Stability (soak) / Peak (burst), chosen by goal.

通用性能测试框架A generic performance-testing framework▮