# jmeter-performance

**Repository Path**: test-dev-qa/jmeter-performance

## Basic Information

- **Project Name**: jmeter-performance
- **Description**: 基于Jmeter的性能工具工程，用于快速搭建压测系统。
- **Primary Language**: Shell
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Jmeter-performance

#### 一、介绍
基于 JMeter 的性能测试工程工程模板，用于快速搭建并统一管理压测脚本与测试结果。通过 Git 管理脚本，支持多人并行开发、版本可追溯，并能生成统一格式的 HTML 报告以供在线查看。

关键字：报告统一格式，脚本版本管控，多人并行开发，在线查看报告

#### 二、软件架构
##### 软件架构说明
（待补充）

##### 涉及工具

| 工具                |
| ------------------- |
| Apache-jmeter-5.6.3 |
| Git                 |
| Python3             |

---

## 快速总览（对新手友好）
这是一个以 `scripts/` 目录为入口的工程：每个业务/套件用一个子目录放置 JMeter 脚本（.jmx）和一个 `config.txt`（用来列出要运行的用例），通过仓库内的脚本生成 `jmeter` 命令并执行，结果保存在 `reports/` 下并可生成 HTML 报告查看。

我会在下面逐步说明：先决条件 -> 环境设置 -> JMeter 插件与配置 -> 仓库结构 -> 新增脚本 -> 生成/执行命令（Linux / Windows）-> 查看报告 -> 常见问题与排查 -> 贡献指南。

---

#### 三、先决条件（Prerequisites）
- 操作系统：Linux / macOS / Windows（PowerShell）
- Apache JMeter >= 5.6.3（仓库内已包含 `bin/apache-jmeter-5.6.3.zip`，可直接解压使用）
- Python 3.6+
- Git
- 建议：浏览器用于查看 HTML 报告

---

#### 四、环境设置（Environment setup）
下面给出常见平台的快速安装与验证命令示例。

- 解压仓库内的 JMeter（Linux/macOS）：

```bash
unzip bin/apache-jmeter-5.6.3.zip -d ~/
# 或使用系统包管理器安装 jmeter
```

- 解压（Windows PowerShell）：

```powershell
Expand-Archive -Path .\bin\apache-jmeter-5.6.3.zip -DestinationPath C:\tools\
```

- 设置环境变量（Linux / macOS）：

```bash
export JMETER_HOME=~/apache-jmeter-5.6.3
export PATH=$JMETER_HOME/bin:$PATH
# 验证
jmeter -v
```

- 设置环境变量（Windows PowerShell）：

```powershell
$Env:JMETER_HOME = 'C:\tools\apache-jmeter-5.6.3'
$Env:Path = $Env:JMETER_HOME + '\\bin;' + $Env:Path
# 验证
jmeter.bat -v
```

---

#### 五、JMeter 插件与配置
1. 下载插件管理器（jmeter-plugins-manager-1.10.jar）并放到 JMeter 的 `lib/ext/` 目录：
   - 下载地址：https://jmeter-plugins.org/get/
   - 放置后重启 JMeter GUI（`jmeter` 或 `jmeter.bat`），打开：Options -> Plugins Manager，安装推荐插件如 `Basic Graphs`、`Additional Graphs`。

2. 为了保证 HTML 报表中有足够维度的数据，建议在 `bin/jmeter.properties` 或 `bin/user.properties` 中添加（或确认）以下配置：

```
jmeter.save.saveservice.bytes=true
jmeter.save.saveservice.label=true
jmeter.save.saveservice.latency=true
jmeter.save.saveservice.response_code=true
jmeter.save.saveservice.response_message=true
jmeter.save.saveservice.successful=true
jmeter.save.saveservice.thread_counts=true
jmeter.save.saveservice.thread_name=true
jmeter.save.saveservice.time=true
jmeter.save.saveservice.timestamp_format=ms
jmeter.save.saveservice.timestamp_format=yyyy/MM/dd HH:mm:ss
```

3. 重新打开 JMeter GUI，确认能正确打开工程下的 demo.jmx（参考工程图片）。

![打开脚本](pic/打开脚本.png)

---

#### 六、仓库结构（重要文件说明）
- `bin/`：可选，包含仓库提供的 JMeter 压缩包 `apache-jmeter-5.6.3.zip`。
- `scripts/`：主入口，按套件/业务目录管理脚本，例如 `scripts/demo/`。
  - 每个套件目录下推荐包含：`*.jmx` 与 `config.txt`。
  - `scripts/run.sh`：Shell 版生成 jmeter 命令（用于 Linux / macOS）。
  - `scripts/run.py`：Python 版生成 jmeter 命令（可跨平台调用，Windows 上常用 `py` / `python` 运行）。
- `reports/`：执行生成的 `.jtl` 与 HTML 报告目录。

示例（本仓库已有 demo）：
- `scripts/demo/demo.jmx`
- `scripts/demo/config.txt`

---

#### 七、如何添加测试脚本（Add test scripts）
1. 在 `scripts/` 下新建目录，例如 `scripts/your_suite/`。
2. 将你的 `*.jmx` 脚本放入该目录。
3. 在该目录下创建或编辑 `config.txt`，每一行写一个要运行的 jmx 文件名或相对路径（不带扩展名也可，按本仓库脚本逻辑会拼接 `.jmx`）。
   - 支持注释：以 `#` 开头的行会被忽略；空行也会被忽略。

config.txt 示例：

```
# demo config
demo.jmx
# subdir/my_test.jmx
```

4. 提交代码前在本地先用 `run.sh` / `run.py` 生成并验证要执行的命令。

---

#### 八、如何生成并运行 JMeter 命令（Linux / Windows）
仓库提供的 `scripts/run.sh` 与 `scripts/run.py` 仅用于“生成并打印”可执行的 `jmeter` 命令，目的是避免直接在开发机器上误执行并便于人工检查命令正确性。使用流程通常是：先生成命令 -> 检查命令 -> 在目标环境（或本地）执行命令。

- 生成命令（Linux / macOS）：

```bash
cd jmeter-performance
sh scripts/run.sh demo
```

- 生成命令（跨平台 Python，推荐在 Windows 上使用）：

```bash
cd jmeter-performance
python3 scripts/run.py demo
# 或在 Windows PowerShell 上
py .\scripts\run.py demo
```

示例输出（脚本会打印类似）：

```
jmeter -n -t ./demo/demo.jmx -l ./reports/demo/demo_YYYYMMDD_HHMMSS.jtl -e -o ./reports/demo/demo_YYYYMMDD_HHMMSS
```

- 在 Linux 上执行打印出的命令：直接复制粘贴到 shell 中并运行（确保 PATH 中有 `jmeter` 或使用 `$JMETER_HOME/bin/jmeter` 的完整路径）。

- 在 Windows PowerShell 上：请把 `jmeter` 替换为 `jmeter.bat` 或使用完整路径，例如：

```powershell
jmeter.bat -n -t .\demo\demo.jmx -l .\reports\demo\demo_YYYYMMDD_HHMMSS.jtl -e -o .\reports\demo\demo_YYYYMMDD_HHMMSS
```

注意：脚本不会自动替换为 `jmeter.bat`，Windows 环境请手动调整或在 PowerShell 中把 `jmeter` 的可执行路径加入 PATH。

---

#### 九、查看 HTML 报告（View HTML report）
生成的报告目录通常位于：`reports/<suite>/<testname>_YYYYMMDD_HHMMSS/`，目录内有 `index.html`。

- 在仓库根目录启动临时 HTTP 服务查看（Linux / Windows 都适用）:

```bash
# Linux / macOS / Windows (使用 Python 3)
python3 -m http.server 8889
# 或在部分 Windows 环境中使用
python -m http.server 8889
```

在浏览器中访问：

```
http://127.0.0.1:8889/reports/<suite>/<testname>_YYYYMMDD_HHMMSS/
```

你也可以直接用浏览器用文件协议打开 `reports/.../index.html`，但某些浏览器对本地文件的 JS/CSS 可能有限制，推荐使用临时 HTTP 服务查看。

![HTML报告](pic/HTML报告.png)

---

#### 十、常见问题与排查（Troubleshooting）
- File config.txt not found：
  - 确认你在仓库根目录或正确路径下运行 `scripts/run.sh <suite>` 或 `scripts/run.py <suite>`，并且 `scripts/<suite>/config.txt` 存在。
- jmeter: command not found：
  - 确认 `JMETER_HOME/bin` 已加入 PATH，或在命令中使用完整路径：`$JMETER_HOME/bin/jmeter`（Windows 使用 `jmeter.bat`）。
- 插件缺失导致报表或图表不可用：
  - 确保已把 `jmeter-plugins-manager` 放到 `lib/ext` 并通过 GUI 安装需要的插件。
- 报告为空或无样本数据：
  - 检查生成的 `.jtl` 文件是否存在且有数据，检查 `jmeter.properties` 中的保存字段是否按第 5 节所示开启。
- 权限或磁盘问题：
  - 确保执行用户对 `reports/` 有写权限，必要时预先 `mkdir -p reports/<suite>` 并调整权限。

---

#### 十一、命名约定与最佳实践
- 套件目录：`scripts/<suite_name>/`
- 配置文件：`scripts/<suite_name>/config.txt`（每行一个待运行的 jmx 路径或文件名）
- 报告目录：`reports/<suite>/<testname>_YYYYMMDD_HHMMSS/`（自动生成）
- 分支命名：`feat/<short-desc>`、`fix/<short-desc>`、`chore/<short-desc>`
- 提交前：在本地生成命令并手动检查，确保脚本路径、参数正确。

---

#### 十二、参与贡献（Contribution）
欢迎贡献！基本流程：
1. Fork 本仓库。
2. 新建分支（例如 `feat/<desc>`）。
3. 提交你的脚本或文档更改。
4. 发起 Pull Request。

PR 检查清单（可复制到 PR 描述中）：
- [ ] 新增或修改的脚本已放在 `scripts/<suite>/`。
- [ ] `config.txt` 已正确更新并包含示例条目。
- [ ] README 中已说明如何运行和验证。
- [ ] 若更改 JMeter 配置或依赖（插件），在 PR 描述中说明如何复现环境。

---

#### 附：快速示例（Linux）
1. 生成命令：

```bash
cd jmeter-performance
sh scripts/run.sh demo
```

2. 复制并执行输出的 jmeter 命令，等待结束后在 `reports/demo/` 下查看生成报告目录。

---

更多信息或问题请在 Issue 中提问，或者直接在 PR 中说明你的改动与验证步骤。祝压测顺利！