jmeter-script-generator

name	jmeter-script-generator
description	用于生成可执行的 JMeter 压测资产，包括 .jmx 测试计划、CLI 执行脚本和结果目录规范。用户提到 JMeter、jmx、压测、load testing、stress testing、并发、ramp-up、RPS/QPS、throughput、SLA、性能基线，或要求为 HTTP API 创建/调整压测脚本时使用。

JMeter 脚本生成器

概述

生成可直接执行、可复查的端到端 JMeter 压测资产：

1. .jmx 测试计划
2. 运行脚本（run.sh）
3. 标准化结果目录与命令示例
4. 基于接口文档自动解析并批量生成接口压测配置

优先输出可复现、可参数化的测试计划，避免一次性硬编码脚本。 当用户提供接口文档（OpenAPI/Swagger/Postman/Markdown/API 网页说明）时，优先走“自动解析 -> 批量生成”流程。

必要输入

生成资产前，先收集以下信息（若缺失则合理推断并明确写出假设）：

• 目标环境：protocol、host、port、base path
• 测试目标：baseline / stress / spike / soak
• 接口集合：method、path、请求体模板、headers、鉴权方式
• 负载模型：并发用户、ramp-up、保压时长、循环/调度
• 断言与 SLA：状态码、p95/p99 上限、错误率阈值
• 数据策略：固定请求体 / CSV 数据集 / 动态变量
• 输出要求：JTL 路径、HTML 报告路径、日志详细程度
• 接口文档来源：本地文件路径 / URL / 贴文本（OpenAPI、Postman collection、Markdown）

如果关键字段缺失，先简洁提问；如果用户偏向快速产出，则使用显式默认值继续。

接口文档自动解析（新增能力）

当用户要求“根据接口文档自动生成 jmx”时，执行以下流程：

1. 识别文档类型（OpenAPI/Swagger、Postman、Markdown、普通文本）
2. 批量抽取接口信息（可多接口）：
   • URL（含 base path + endpoint path）
   • 请求方式（GET/POST/PUT/DELETE/PATCH）
   • 请求头（含鉴权头）
   • 请求参数（path/query/body/form-data）
   • 响应格式（JSON/文本/状态码约束）
3. 生成统一变量层（host、token、公共 header、公共参数）
4. 为每个接口生成命名清晰的 HTTP Sampler，并自动挂载断言
5. 一次性输出完整 .jmx（可直接导入 JMeter），同时生成 run.sh + README.md
6. 输出“微调建议清单”，确保导入后仅需少量修改即可执行

批量解析规则

• 支持一次解析多个接口，并按“业务分组 / 标签(tag) / 路径前缀”组织 Sampler。
• 默认保留接口调用顺序；若文档有依赖关系（如先登录再访问），需构建基础链路顺序。
• 对缺失字段采用保守默认值，并在 README 的“假设项”中逐条说明。
• 对无法确定的数据结构，使用占位变量（如 ${token}、${user_id}、${payload_json}）。

输出约定

始终产出以下文件，并在回复中说明路径：

1. performance/<scenario>/test-plan.jmx
2. performance/<scenario>/run.sh
3. performance/<scenario>/README.md
4. performance/<scenario>/parsed-apis.md（记录解析到的接口清单与映射关系）

结果目录使用以下结构：

• performance/<scenario>/results/jtl/
• performance/<scenario>/results/report/
• performance/<scenario>/logs/
• performance/<scenario>/data/（使用 CSV 时）
• performance/<scenario>/docs/（存放原始接口文档或解析快照）

生成规则

1) .jmx 测试计划

生成合法且可运行的 JMeter 测试计划，至少包含：

• Test Plan + 一个 Thread Group（除非用户明确要求多个）
• HTTP Request Defaults（复用 host/protocol/port）
• HTTP Header Manager（默认 Content-Type: application/json）
• 在需要会话真实性时加入 Cookie Manager 与 Cache Manager
• 命名清晰的采样器（如 POST /api/login）
• 支持批量接口自动生成采样器（每个接口单独命名，且可追溯到原文档）
• 仅在用户要求拟真流量时添加 Timer（默认确定性负载）
• 断言：
  • 响应状态码符合预期
  • 用户指定业务校验时，可增加 JSON/body 断言
• 监听器：
  • CI 模式保持轻量
  • 主要结果通过 JTL + HTML 报告输出

.jmx 兼容性约束（避免 GUI 无法打开）

为避免出现“XML 可解析但 JMeter GUI 打不开”的问题，必须遵守：

• HTTPSamplerProxy 内参数节点使用：
  • elementProp name="HTTPSampler.Arguments" elementType="Arguments"
  • 并带 guiclass="HTTPArgumentsPanel"、testclass="Arguments"
• 不要使用错误或混用键名（如 HTTPsampler.Arguments 这种大小写/拼写变体）。
• ResponseAssertion 必须使用 Assertion.test_strings，不要写成拼写错误字段。
• 若存在 HTTP Request Defaults，字段名需与 JMeter 标准保持一致；不确定时可直接把域名/端口/协议写入每个 sampler，优先保证可导入。
• 生成后必须进行“可导入性优先”检查：宁可结构保守，也不要使用高风险写法。

2) run.sh

生成可移植 shell 脚本，要求：

• set -euo pipefail
• 支持环境变量覆盖：JMETER_BIN、JMX_FILE、RESULT_DIR、THREADS、RAMP_UP、DURATION
• 自动创建缺失目录
• 使用 non-GUI 模式执行
• 自动生成 HTML 报告
• 输出最终产物路径

3) README

README 至少包含：

• 快速开始命令
• 参数表（每个环境变量含义）
• 命令示例：
  • 本地烟测（smoke）
  • 中等压力测试
  • CI 执行
• 故障排查（常见 JMeter 报错与修复）
• 接口文档解析摘要（文档来源、解析总接口数、成功/失败项）

4) parsed-apis.md

需要包含：

• 接口总览表：序号、方法、路径、说明、是否已映射到 Sampler
• 参数映射：path/query/body/header 到 JMeter 变量的映射
• 响应断言映射：状态码断言、JSON 字段断言（如有）
• 未完全解析项与建议手工补充点

默认参数策略

用户未指定参数时，默认值为：

• threads=50
• ramp_up=30s
• duration=300s
• 请求超时 connect=3000ms、response=10000ms
• SLA 占位值需明确标注为“假设”

不要隐含默认值，必须在 README 中明确列出。

运行时环境约束（Java 版本）

本地基于 JMeter 5.6.x 时，默认按 Java 11 生成和执行脚本（兼容性优先）。

• 生成的 run.sh 应支持显式注入 JAVA_HOME。
• 若用户未设置 JAVA_HOME，推荐优先尝试：/usr/libexec/java_home -v 11（macOS）。
• 在 README 中明确提示：
  • JMeter GUI/CLI 推荐使用 Java 11。
  • 如果系统默认是更高版本（如 21/26）导致 Groovy/插件异常，需切换到 Java 11。

推荐执行方式示例（macOS）：

JAVA_HOME="$("/usr/libexec/java_home" -v 11)" JMETER_BIN="/path/to/jmeter" bash performance/<scenario>/run.sh

安全与真实性

• 在生成高风险负载（极高并发）前先给出风险提示。
• 不要在 .jmx 中直接写死密钥或凭证，改用变量/env 占位。
• host/token/path 尽量参数化，避免硬编码。
• 对需要鉴权的 API，若用户未提供登录接口，给出 token 占位流程。
• 对接口文档中的敏感字段（如密钥、签名）默认脱敏并转占位变量。

质量检查清单（回复前执行）

• .jmx 是符合 JMeter 语法的有效 XML
• .jmx 关键节点名符合 JMeter GUI 兼容写法（尤其 HTTPSampler.Arguments、Assertion.test_strings）
• 所有引用路径均与目录结构一致
• run.sh 可直接执行（包含 chmod +x 提示）
• run.sh 与 README 明确 Java 11 兼容要求及 JAVA_HOME 设置方式
• JTL 与报告输出路径保持一致
• README 至少包含 3 条可执行示例命令
• 所有假设已显式列出
• 多接口解析结果与 .jmx 中 Sampler 数量一致
• parsed-apis.md 可追溯每个接口的生成来源

失败处理策略

如果用户反馈“JMX 打不开”或出现属性解析异常：

1. 优先判断为兼容性问题（不是用户操作问题）。
2. 先输出一个“最小可打开版本”（1 个 Thread Group + 1 个 HTTP Sampler + 1 个断言）。
3. 让用户确认可打开后，再逐步恢复签名脚本、参数化、断言增强。
4. 将修复点回写到 skill 的兼容性约束中，避免同类问题复发。

响应格式

技能被调用时，按以下顺序回复：

1. 假设与输入
2. 接口解析结果（总接口数、成功数、失败数、失败原因）
3. 生成产物（路径 + 每个文件用途）
4. 执行命令
5. 下一步调优建议（threads/ramp/duration/assertions/变量替换）
6. 风险与说明

回复风格保持简洁、可执行、偏操作指令。

最小命令示例

示例命令可使用：

• bash performance/api-baseline/run.sh
• THREADS=200 RAMP_UP=120 DURATION=600 bash performance/api-baseline/run.sh
• JMETER_BIN=/opt/jmeter/bin/jmeter bash performance/api-baseline/run.sh

扩展资源（按需读取）

当任务需要更细粒度规则时，按以下指引读取对应文件：

• OpenAPI/Swagger/Postman/Markdown 文档解析细则：references/parsing-strategies.md
• 接口字段到 JMeter 组件映射规范：references/jmeter-mapping-rules.md
• 批量解析结果文档模板：templates/parsed-apis.template.md
• 解析摘要校验脚本：scripts/validate_parsed_apis.py
• 输入示例：examples/openapi-input.md、examples/postman-input.md