pytest Plugin¶
ecu.test code 包含一个 pytest 插件,可将 ecu.test code 测试用例结果便捷地上报到 test.guide。该插件会自动将每条断言转换为一个测试步骤,并收集参数、自定义属性以及日志、stdout 或 stderr 输出。
前提条件¶
ecu.test code(参见 Getting Started(快速入门))。
正在运行的 test.guide 实例
设置¶
设置所需的环境变量:
TESTGUIDE_URL:test.guide 实例的基础 URL(末尾不带斜杠)。TESTGUIDE_PROJECT_ID:数值型项目 ID(将鼠标悬停在项目名称上即可看到提示)。TESTGUIDE_AUTH_KEY:个人认证密钥(可在 test.guide 的“Authentication keys”下创建)。
提供的 demo Workspace(工作区)启动配置允许你在 Visual Studio Code 对话框中输入这些值,也可以手动设置:
Linux Bash
export TESTGUIDE_URL="https://your.test-guide.instance" export TESTGUIDE_PROJECT_ID=42 export TESTGUIDE_AUTH_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Windows CMD
set TESTGUIDE_URL=https://your.test-guide.instance set TESTGUIDE_PROJECT_ID=42 set TESTGUIDE_AUTH_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
创建(或扩展)
tests/pytest.ini以启用通过断言的上报:[pytest] enable_assertion_pass_hook = True enable_verdict_none = true修改该文件后,请清理 Python 字节码(删除
__pycache__文件夹)。添加一个最小测试(
tests/test_quickstart.py):def test_add(): assert 1 + 1 == 2运行 pytest 并上传:
pytest tests/test_quickstart.py --upload-to-testguide控制台中的 Pytest 报告里应能看到带有相应过滤条件的 test.guide 链接。请在 test.guide 项目中查看该次测试运行。如果启用了
enable_assertion_pass_hook,通过的断言会显示为一个 Verdict 为 PASSED 的测试步骤。
故障排查¶
SSL 问题:如果 test.guide 实例使用手动配置的 SSL 证书,并且上传结果到 test.guide 时遇到问题,可以安装 pip_system_certs,以便使用操作系统级别配置的证书。或者,也可以将 pytest 配置为跳过证书校验(不推荐)。更多细节请参见 Configuration(配置) 章节。
测试 Verdict 不是 PASSED:请确认
enable_assertion_pass_hook = True,并删除旧的.pyc文件。
配置¶
命令行¶
pytest 命令行选项通过 pytest 命令行传入,并且仅对当前这一次测试运行生效,例如:
pytest test_example.py --upload-to-testguide
下表列出了该 pytest 插件提供的全部命令行选项。“Default” 表示未使用该选项时该功能是否启用。
选项 |
默认值 |
说明 |
|---|---|---|
|
|
将本次测试运行的结果上传到 test.guide |
|
|
在调用 pytest 的目录中创建一个 `.report` 目录。该目录中包含用于上传到 test.guide 的全部 JSON 报告和工件。 |
|
|
在上传报告到 test.guide 时跳过 SSL 校验。 |
pytest.ini¶
pytest.ini 中的条目用于定义插件选项的持久默认值(例如 enable_assertion_pass_hook = true)。
下表列出了该 pytest 插件提供的全部 .ini 选项:
名称 |
类型 |
默认值 |
说明 |
|---|---|---|---|
|
|
|
在上传报告到 test.guide 时跳过 SSL 校验。 |
|
|
|
发送到 test.guide 的 HTTP 请求超时时间,单位为秒。(仅在使用报告上传时生效。) |
|
|
|
不包含任何断言的测试用例(测试函数)会在 test.guide 报告中以 Verdict NONE 上报。(该配置不会改变原生 pytest 报告中的测试结果。) |
测试结果与 Verdict¶
该 pytest 插件会将每条断言表示为一个测试步骤。为了让通过的断言也能显示出来,必须启用 pytest 选项
enable_assertion_pass_hook
。交付的 pytest.ini 中已预先配置该选项。修改 enable_assertion_pass_hook 配置后,请务必清理 .pyc 文件。你也可以设置
enable_verdict_none,以便为不包含任何断言的测试用例分配 Verdict “NONE”。
请注意,除 AssertionError 之外的任何异常,都会导致该测试用例在 test.guide 报告中以 Verdict ERROR 上报。被跳过的测试会以 Verdict INCONCLUSIVE 上报。下文给出了 Verdict 及其触发条件的详细概览。
警告
pytest 与 test.guide 之间的测试结果可能存在差异 对测试结果的误判可能导致对测试用例或测试步骤质量得出错误结论。
pytest 原生结果(passed、failed、skipped)并不总是与 test.guide 中测试用例或测试步骤的 Verdict 完全一致。
插件配置选项会影响测试结果到 Verdict 的映射关系。
务必检查当前生效的插件选项。
只能结合已启用的插件选项来解释 Verdict。
说明
下表假定已在 pytest.ini 中设置 enable_assertion_pass_hook = True。
test.guide Verdict |
触发情况 |
配置 |
|---|---|---|
PASSED |
在 setup 过程中以及测试用例本身执行时都没有抛出异常。 |
默认行为 |
FAILED |
setup 过程中没有抛出异常,但测试用例中抛出了 AssertionError。 |
默认行为 |
ERROR |
setup 过程中抛出了异常,或者测试用例中抛出了 AssertionError 以外的异常。 |
默认行为 |
INCONCLUSIVE |
测试用例通过 |
默认行为 |
NONE |
在 setup 过程中以及测试用例本身执行时都没有抛出异常,且测试用例中没有 assert 语句。 |
|
输出捕获¶
该 pytest 插件可以将 pytest 通过 stdout、stderr 或 logging 捕获的输出作为工件包含在 test.guide 报告中。 此外,只要某个测试用例的 Verdict 为 FAILED 或 ERROR,该测试用例还会附加一份 pytest 报告作为工件。
Stdout 与 Stderr¶
该功能默认启用。只要在测试用例内捕获到 stdout 或 stderr 内容,就会向该测试用例添加一个包含捕获内容的工件
(stdout.log / stderr.log)。如果没有捕获到任何内容,则不会创建对应工件。可以通过关闭 pytest 捕获功能来禁用此特性,例如使用命令行选项 -s。
pytest test_example.py -s --upload-to-testguide
更多信息请参见 pytest 文档中的 Disabling Capturing 。
日志¶
与 stdout 和 stderr 类似,该插件也可以将 pytest 捕获的日志(来自 logging 库)作为工件附加到测试用例。
如果在测试用例内捕获到日志,则会向该测试用例添加工件 logs.log。有关在 pytest 中启用和配置日志的更多信息,请参见 pytest 文档中的
How to manage logging。
Pytest 报告¶
只要某个测试用例被赋予 Verdict FAILED 或 ERROR,该测试用例就会附加一份 pytest 报告作为工件
(<test_case_name>.log)。pytest 报告通常包含 traceback 等有用信息,有助于分析测试用例中的错误。
属性记录¶
Pytest 允许通过 record_property fixture 为单个 test case 附加任意键/值元数据(参见
pytest docs)。
这些属性会在 test.guide 中作为对应 test case 的 Attributes 报告。此功能始终启用。
说明
非 str 类型的值会转换为其 repr(),从而使复杂对象也能以可读形式显示。
示例¶
def test_properties(record_property):
record_property("ecu_sw_version", "v1.2.3") # str value
record_property("retries", 2) # int -> converted with repr()
record_property("tags", ["smoke", "api"]) # list -> converted with repr()
assert 1 + 1 == 2
test.guide 中的 Attributes(所有值均为字符串):
属性 |
值 |
|---|---|
ecu_sw_version |
|
retries |
|
tags |
|
Constants¶
使用标记 pytest.mark.constants(...),可以将命名常量附加到 test case。
这些值在 test.guide 中作为相应 test case 的 Constants 报告。
该标记只接受关键字参数。它既可以用作
test 函数或 test 类的装饰器,也可以通过模块级的 pytestmark 设置
(参见 示例)。
此外,constants fixture 会将以
pytest.mark.constants(...) 设置的常量作为属性提供,供测试内部使用。
Info
类型为 str 的常量值按原样使用。其他所有对象都转换为其 repr() 表示。
通过 constants 标记在模块级设置常量,仅在将该标记存储在名为 pytestmark 的变量中时才有效(参见 pytest 文档)。
Example¶
import pytest
# Makes GLOBAL_CONSTANT available to all tests in this module
pytestmark = pytest.mark.constants(GLOBAL_CONSTANT="myValue")
# MAX_RETRIES is only available in test_constants
@pytest.mark.constants(MAX_RETRIES=3)
def test_constants(constants):
for i in range(constants.MAX_RETRIES):
do_something()
# GLOBAL_CONSTANT is available via the pytestmark variable
assert constants.GLOBAL_CONSTANT = "myValue"
# constants markers can be combined
# constants are reported even if the constants fixture is not used
@pytest.mark.constants(ARCH="x86", OS="linux")
@pytest.mark.constants(BUILD_TYPE="release")
def test_something():
assert True
参数记录¶
每个测试函数的参数(包括参数化取值和注入的 fixture)都会作为 test.guide 参数上报。这样可以在后续过滤或区分参数化测试用例的各次单独执行。对于每个测试用例参数,都会创建一个方向为 IN 的 test.guide 参数。此功能始终启用。
说明
str 或 int 类型的值会直接使用。其他所有 Python 对象都会转换为
repr(),从而使复杂结构也能以可读形式显示。
示例¶
import pytest
@pytest.mark.parametrize("x,y", [ (1, 2), (3, 4) ])
def test_params(x, y):
assert (x + y) > 0
结果:会上报两个同名的 test.guide 测试用例,其参数值如下:
测试运行 |
x |
y |
|---|---|---|
1 |
|
|
2 |
|
|