mirror of
https://github.com/httprunner/httprunner.git
synced 2026-05-13 04:30:41 +08:00
339 lines
13 KiB
Markdown
339 lines
13 KiB
Markdown
# 开发扩展
|
||
|
||
HttpRunner 除了作为命令行工具使用外，还可以作为软件包集成到你自己的项目中。
|
||
|
||
简单来说，HttpRunner 提供了运行 YAML/JSON 格式测试用例的能力，并能返回详细的测试结果信息。
|
||
|
||
## HttpRunner class
|
||
|
||
### TL;DR
|
||
|
||
HttpRunner 以 `类（class）` 的形式对外提供调用支持，类名为 `HttpRunner`。使用方式如下：
|
||
|
||
```python
|
||
from httprunner.api import HttpRunner
|
||
|
||
runner = HttpRunner(
|
||
failfast=True,
|
||
save_tests=True,
|
||
log_level="INFO",
|
||
log_file="test.log"
|
||
)
|
||
summary = runner.run(path_or_tests)
|
||
```
|
||
|
||
### 初始化参数说明
|
||
|
||
通常情况下，初始化 `HttpRunner` 时的参数有如下几个：
|
||
|
||
- `failfast`（可选）: 设置为 True 时，测试在首次遇到错误或失败时会停止运行；默认值为 False
|
||
- `save_tests`（可选）: 设置为 True 时，会将运行过程中的状态（loaded/parsed/summary）保存为 JSON 文件，存储于 logs 目录下；默认为 False
|
||
- `log_level`（可选）: 设置日志级别，默认为 "INFO"
|
||
- `log_file`（可选）: 设置日志文件路径，指定后将同时输出日志文件；默认不输出日志文件
|
||
|
||
### 调用方法说明
|
||
|
||
在 `HttpRunner` 中，对外提供了一个 `run` 方法，用于运行测试用例。
|
||
|
||
run 方法有三个参数：
|
||
|
||
- `path_or_tests`（必传）: 指定要运行的测试用例；支持传入两类参数
|
||
- str: YAML/JSON 格式测试用例文件路径
|
||
- dict: 标准的测试用例结构体
|
||
- `dot_env_path`（可选）: 指定加载环境变量文件（.env）的路径，默认值为当前工作目录（PWD）中的 `.env` 文件
|
||
- `mapping`（可选）: 变量映射，可用于对传入测试用例中的变量进行覆盖替换。
|
||
|
||
#### 传入测试用例文件路径
|
||
|
||
指定测试用例文件路径支持三种形式：
|
||
|
||
- YAML/JSON 文件路径，支持绝对路径和相对路径
|
||
- 包含 YAML/JSON 文件的文件夹，支持绝对路径和相对路径
|
||
- 文件路径和文件夹路径的混合情况（list/set）
|
||
|
||
```python
|
||
# 文件路径
|
||
runner.run("docs/data/demo-quickstart-2.yml")
|
||
|
||
# 文件夹路径
|
||
runner.run("docs/data/")
|
||
|
||
# 混合情况
|
||
runner.run(["docs/data/", "files/demo-quickstart-2.yml"])
|
||
```
|
||
|
||
如需指定加载环境变量文件（.env）的路径，或者需要对测试用例中的变量进行覆盖替换，则可使用 `dot_env_path` 和 `mapping` 参数。
|
||
|
||
```python
|
||
# dot_env_path
|
||
runner.run("docs/data/demo-quickstart-2.yml", dot_env_path="/path/to/.env")
|
||
|
||
# mapping
|
||
override_mapping = {
|
||
"device_sn": "XXX"
|
||
}
|
||
runner.run("docs/data/demo-quickstart-2.yml", mapping=override_mapping)
|
||
```
|
||
|
||
#### 传入标准的测试用例结构体
|
||
|
||
除了传入测试用例文件路径，还可以直接传入标准的测试用例结构体。
|
||
|
||
以 [demo-quickstart-2.yml](/data/demo-quickstart-2.yml) 为例，对应的数据结构体如下所示：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"config": {
|
||
"name": "testcase description",
|
||
"request": {
|
||
"base_url": "",
|
||
"headers": {
|
||
"User-Agent": "python-requests/2.18.4"
|
||
}
|
||
},
|
||
"variables": [],
|
||
"output": ["token"],
|
||
"path": "/abs-path/to/demo-quickstart-2.yml",
|
||
"refs": {
|
||
"env": {},
|
||
"debugtalk": {
|
||
"variables": {
|
||
"SECRET_KEY": "DebugTalk"
|
||
},
|
||
"functions": {
|
||
"gen_random_string": <function gen_random_string at 0x108596268>,
|
||
"get_sign": <function get_sign at 0x1085962f0>,
|
||
"get_user_id": <function get_user_id at 0x108596378>,
|
||
"get_account": <function get_account at 0x108596400>,
|
||
"get_os_platform": <function get_os_platform at 0x108596488>
|
||
}
|
||
},
|
||
"def-api": {},
|
||
"def-testcase": {}
|
||
}
|
||
},
|
||
"teststeps": [
|
||
{
|
||
"name": "/api/get-token",
|
||
"request": {
|
||
"url": "http://127.0.0.1:5000/api/get-token",
|
||
"method": "POST",
|
||
"headers": {"Content-Type": "application/json", "app_version": "2.8.6", "device_sn": "FwgRiO7CNA50DSU", "os_platform": "ios", "user_agent": "iOS/10.3"},
|
||
"json": {"sign": "9c0c7e51c91ae963c833a4ccbab8d683c4a90c98"}
|
||
},
|
||
"extract": [
|
||
{"token": "content.token"}
|
||
],
|
||
"validate": [
|
||
{"eq": ["status_code", 200]},
|
||
{"eq": ["headers.Content-Type", "application/json"]},
|
||
{"eq": ["content.success", true]}
|
||
]
|
||
},
|
||
{
|
||
"name": "/api/users/1000",
|
||
"request": {"url": "http://127.0.0.1:5000/api/users/1000", "method": "POST", "headers": {"Content-Type": "application/json", "device_sn": "FwgRiO7CNA50DSU", "token": "$token"},
|
||
"json": {"name": "user1", "password": "123456"}},
|
||
"validate": [
|
||
{"eq": ["status_code", 201]},
|
||
{"eq": ["headers.Content-Type", "application/json"]},
|
||
{"eq": ["content.success", true]},
|
||
{"eq": ["content.msg", "user created successfully."]}
|
||
]
|
||
}
|
||
]
|
||
},
|
||
{...} # another testcase
|
||
]
|
||
```
|
||
|
||
传入测试用例结构体时，支持传入单个结构体（dict），或者多个结构体（list of dict）。
|
||
|
||
```python
|
||
# 运行单个结构体
|
||
runner.run(testcase)
|
||
|
||
# 运行多个结构体
|
||
runner.run([testcase1, testcase2])
|
||
```
|
||
|
||
### 加载 `debugtalk.py` && `.env`
|
||
|
||
通过传入测试用例文件路径运行测试用例时，HttpRunner 会自动以指定测试用例文件路径为起点，向上搜索 `debugtalk.py` 文件，并将 `debugtalk.py` 文件所在的文件目录作为当前工作目录（PWD）。
|
||
|
||
同时，HttpRunner 会在当前工作目录（PWD）下搜索 `.env` 文件，以及 `api` 和 `testcases` 文件夹，并自动进行加载。
|
||
|
||
最终加载得到的存储结构如下所示：
|
||
|
||
```json
|
||
{
|
||
"env": {},
|
||
"debugtalk": {
|
||
"variables": {
|
||
"SECRET_KEY": "DebugTalk"
|
||
},
|
||
"functions": {
|
||
"gen_random_string": <function gen_random_string at 0x108596268>,
|
||
"get_sign": <function get_sign at 0x1085962f0>,
|
||
"get_user_id": <function get_user_id at 0x108596378>,
|
||
"get_account": <function get_account at 0x108596400>,
|
||
"get_os_platform": <function get_os_platform at 0x108596488>
|
||
}
|
||
},
|
||
"def-api": {},
|
||
"def-testcase": {}
|
||
}
|
||
```
|
||
|
||
其中，`env` 对应的是 `.env` 文件中的环境变量，`debugtalk` 对应的是 `debugtalk.py` 文件中定义的变量和函数，`def-api` 对应的是 `api` 文件夹下定义的接口描述，`def-testcase` 对应的是 `testcases` 文件夹下定义的测试用例。
|
||
|
||
通过传入标准的测试用例结构体执行测试时，传入的数据应包含所有信息，包括 `debugtalk.py`、`.env`、依赖的 api 和 测试用例等；因此也无需再使用 `dot_env_path` 和 `mapping` 参数，所有信息都要通过 `refs` 传入。
|
||
|
||
## 返回详细测试结果数据
|
||
|
||
运行完成后，通过 `run()` 方法的返回结果可获取详尽的运行结果数据。
|
||
|
||
```python
|
||
summary = runner.run(path_or_tests)
|
||
```
|
||
|
||
其数据结构为：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"stat": {
|
||
"testsRun": 2,
|
||
"failures": 0,
|
||
"errors": 0,
|
||
"skipped": 0,
|
||
"expectedFailures": 0,
|
||
"unexpectedSuccesses": 0,
|
||
"successes": 2
|
||
},
|
||
"time": {
|
||
"start_at": 1538449655.944404,
|
||
"duration": 0.03181314468383789
|
||
},
|
||
"platform": {
|
||
"httprunner_version": "1.5.14",
|
||
"python_version": "CPython 3.6.5+",
|
||
"platform": "Darwin-17.6.0-x86_64-i386-64bit"
|
||
},
|
||
"details": [
|
||
{
|
||
"success": true,
|
||
"name": "testcase description",
|
||
"base_url": "",
|
||
"stat": {"testsRun": 2, "failures": 0, "errors": 0, "skipped": 0, "expectedFailures": 0, "unexpectedSuccesses": 0, "successes": 2},
|
||
"time": {"start_at": 1538449655.944404, "duration": 0.03181314468383789},
|
||
"records": [
|
||
{
|
||
"name": "/api/get-token",
|
||
"status": "success",
|
||
"attachment": "",
|
||
"meta_data": {
|
||
"request": {
|
||
"url": "http://127.0.0.1:5000/api/get-token",
|
||
"method": "POST",
|
||
"headers": {"User-Agent": "python-requests/2.18.4", "Accept-Encoding": "gzip, deflate", "Accept": "*/*", "Connection": "keep-alive", "Content-Type": "application/json", "app_version": "2.8.6", "device_sn": "FwgRiO7CNA50DSU", "os_platform": "ios", "user_agent": "iOS/10.3", "Content-Length": "52"},
|
||
"start_timestamp": 1538449655.944801,
|
||
"json": {"sign": "9c0c7e51c91ae963c833a4ccbab8d683c4a90c98"},
|
||
"body": b'{"sign": "9c0c7e51c91ae963c833a4ccbab8d683c4a90c98"}'
|
||
},
|
||
"response": {
|
||
"status_code": 200,
|
||
"headers": {"Content-Type": "application/json", "Content-Length": "46", "Server": "Werkzeug/0.14.1 Python/3.6.5+", "Date": "Tue, 02 Oct 2018 03:07:35 GMT"},
|
||
"content_size": 46,
|
||
"response_time_ms": 12.87,
|
||
"elapsed_ms": 6.955,
|
||
"encoding": null,
|
||
"content": b'{"success": true, "token": "CcQ7dBjZZbjIXRkG"}',
|
||
"content_type": "application/json",
|
||
"ok": true,
|
||
"url": "http://127.0.0.1:5000/api/get-token",
|
||
"reason": "OK",
|
||
"cookies": {},
|
||
"text": '{"success": true, "token": "CcQ7dBjZZbjIXRkG"}',
|
||
"json": {"success": true, "token": "CcQ7dBjZZbjIXRkG"}
|
||
},
|
||
"validators": [
|
||
{"check": "status_code", "expect": 200, "comparator": "eq", "check_value": 200, "check_result": "pass"},
|
||
{"check": "headers.Content-Type", "expect": "application/json", "comparator": "eq", "check_value": "application/json", "check_result": "pass"},
|
||
{"check": "content.success", "expect": true, "comparator": "eq", "check_value": true, "check_result": "pass"}
|
||
]
|
||
}
|
||
},
|
||
{
|
||
"name": "/api/users/1000",
|
||
"status": "success",
|
||
"attachment": "",
|
||
"meta_data": {
|
||
"request": {
|
||
"url": "http://127.0.0.1:5000/api/users/1000",
|
||
"method": "POST",
|
||
"headers": {"User-Agent": "python-requests/2.18.4", "Accept-Encoding": "gzip, deflate", "Accept": "*/*", "Connection": "keep-alive", "Content-Type": "application/json", "device_sn": "FwgRiO7CNA50DSU", "token": "CcQ7dBjZZbjIXRkG", "Content-Length": "39"},
|
||
"start_timestamp": 1538449655.958944,
|
||
"json": {"name": "user1", "password": "123456"},
|
||
"body": b'{"name": "user1", "password": "123456"}'
|
||
},
|
||
"response": {
|
||
"status_code": 201,
|
||
"headers": {"Content-Type": "application/json", "Content-Length": "54", "Server": "Werkzeug/0.14.1 Python/3.6.5+", "Date": "Tue, 02 Oct 2018 03:07:35 GMT"},
|
||
"content_size": 54,
|
||
"response_time_ms": 3.34,
|
||
"elapsed_ms": 2.16,
|
||
"encoding": null,
|
||
"content": b'{"success": true, "msg": "user created successfully."}',
|
||
"content_type": "application/json",
|
||
"ok": true,
|
||
"url": "http://127.0.0.1:5000/api/users/1000",
|
||
"reason": "CREATED",
|
||
"cookies": {},
|
||
"text": '{"success": true, "msg": "user created successfully."}',
|
||
"json": {"success": true, "msg": "user created successfully."}
|
||
},
|
||
"validators": [
|
||
{"check": "status_code", "expect": 201, "comparator": "eq", "check_value": 201, "check_result": "pass"},
|
||
{"check": "headers.Content-Type", "expect": "application/json", "comparator": "eq", "check_value": "application/json", "check_result": "pass"},
|
||
{"check": "content.success", "expect": true, "comparator": "eq", "check_value": true, "check_result": "pass"},
|
||
{"check": "content.msg", "expect": "user created successfully.", "comparator": "eq", "check_value": "user created successfully.", "check_result": "pass"}
|
||
]
|
||
}
|
||
}
|
||
],
|
||
"in_out": {
|
||
"in": {"SECRET_KEY": "DebugTalk"},
|
||
"out": {"token": "CcQ7dBjZZbjIXRkG"}
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 生成 HTML 测试报告
|
||
|
||
如需生成 HTML 测试报告，可调用 `report.gen_html_report` 方法。
|
||
|
||
```python
|
||
from httprunner import report
|
||
|
||
report_path = report.gen_html_report(
|
||
summary,
|
||
report_template="/path/to/custom_report_template",
|
||
report_dir="/path/to/reports_dir",
|
||
report_file="/path/to/report_file_path"
|
||
)
|
||
```
|
||
|
||
`gen_html_report()` 的参数有四个：
|
||
|
||
- summary（必传）: 测试运行结果汇总数据
|
||
- report_template（可选）: 指定自定义的 HTML 报告模板，模板必须采用 Jinja2 的格式
|
||
- report_dir（可选）: 指定生成报告的文件夹路径
|
||
- report_file（可选）: 指定生成报告的文件路径，该参数的优先级高于 report_dir
|
||
|
||
关于测试报告的详细内容，请查看[测试报告](/run-tests/report/)部分。
|
||
|
||
[TextTestRunner]: https://docs.python.org/3.6/library/unittest.html#unittest.TextTestRunner |