pytest 使用指南

-k EXPRESSION

只运行与给定子字符串表达式匹配的测试。表达式是Python可求值的表达式，其中所有名称都是与测试名称及其父类匹配的子字符串。示例：-k'test_method或test_other'匹配其名称为的所有测试函数和类包含“test_method”或“test_other”，而-k“not test_methods”与不包含的匹配在它们的名称中包含“test_method”。-k“not test_method and not test_other”将消除比赛。此外，关键字与包含额外名称的类和函数相匹配它们的“extra_keyword_matches”集，以及直接为其分配名称的函数他们。匹配不区分大小写。

-m MARKEXPR

仅运行与给定标记表达式匹配的测试。例如：-m'mark1'而不是mark2'。

--markers

显示标记（内置、插件和每个项目的标记）。

-x --exitfirst

第一次出错或测试失败时立即退出

--maxfail=num

在第一个num失败或错误后退出

--strict-config

解析配置文件的pytest部分时遇到的任何警告都会引发错误

--strict-markers

未在配置文件的“标记”部分注册的标记会引发错误

--strict

（弃用）别名--strict-markers

--fixtures，--funcargs

显示可用的夹具，按插件外观排序（仅显示带有前导“_”的夹具带有“-v”）

--fixtures-per-test

显示每次测试的夹具

--pdb

在出现错误或键盘中断时启动交互式Python调试器

--pdbcls=modulename:classname

指定一个自定义的交互式 Python 调试器，用于 --pdb 选项。例如：--pdbcls=IPython.terminal.debugger:TerminalPdb

--trace

运行每个测试时立即中断

--capture=method

每个测试捕获方法：fd|sys|no|tee-sys之一

-s

快捷方式--capture=no

--runxfail

报告xfail测试的结果，就像它们没有被标记一样

--lf，--last-failed

仅重新运行上次运行时失败的测试（如果没有失败，则全部重新运行）

--ff，--failed-first

运行所有测试，但先运行最后的失败。这可能会重新排序测试，从而导致重复夹具设置/拆卸。

--nf，--new-first

首先从新文件运行测试，然后按文件mtime排序其余测试

--cache-show =[CACHESHOW]

显示缓存内容，不执行收集或测试。可选参数：glob（默认值：“*”）。

--cache clear

在测试运行开始时删除所有缓存内容

--lfnf={all,none}, --last-failed-no-failures={all,none}

使用 --lf 选项时，决定在不存在先前（已知）失败或未找到缓存的 lastfailed 数据时是否执行测试。all（默认值）会再次运行完整的测试套件。none 仅输出一条关于无已知失败的消息并成功退出。

--sw, --stepwise

测试失败时逐步退出，下次从上次失败的测试继续

--sw-skip, --stepwise-skip

忽略第一个未通过的测试，但在下一个未通过测试时停止。隐式启用--逐步启用。

--sw-reset, --stepwise-reset

重置逐步状态，重新启动逐步工作流。隐式启用--stepwise。

--allure-severities=SEVERITIES_SET

以逗号分隔的严重性名称列表。将只运行这些严重程度的测试。可能的值有：阻塞、严重、正常、轻微、微不足道。

--allure-epics =EPICS_SET

以逗号分隔的史诗名称列表。运行至少具有一个指定功能标签的测试。

--allure-features=FEATURES_SET

以逗号分隔的要素名称列表。运行至少具有一个指定功能标签的测试。

--allure-stories=STORIES_SET

以逗号分隔的故事名称列表。运行至少有一个指定故事标签的测试。

--allure-ids=IDS_SET

逗号分隔的ID列表。运行至少有一个指定id标签的测试。

--allure-label =LABELS_SET

以label_name=value1，value2格式运行的标签列表。“运行至少有一个指定标签的测试。

--allure-link-pattern=LINK_TYPE:LINK_PATTERN

链接模式。链接类型的URL模式。允许测试中的短链接，比如“issue 1”。文本将使用python格式化为完整的URL string.format()。

报告

--durations=N

显示N个最慢的设置/测试持续时间（N=0）

--durations-min=N

包含在最慢列表中的最小持续时间（秒）。默认值：0.005（如果-vv为给定）。

-v,--verbose

提高详细程度

-- no-header

禁用标题

--no-fold-skipped

不要在简短的总结中折叠跳过的测试

--force-short-summary

无论详细程度如何，均强制输出精简摘要

-q, --quiet

减少冗长

--verbosity=VERBOSE

设置冗长。默认值：0。

-r chars

显示由字符指定的额外测试摘要信息：（f）失败，（E）错误，（s）跳过，（x）失败，（X） 通过，（p）已通过，（p）与输出一起通过，（a）除通过（p/p）外的所有内容，或（a）所有内容。（w）收益是默认情况下启用（请参阅--disable warnings），“N”可用于重置列表。（默认值：'fE'）。

--disable-warnings，--disable-pytest-warnings

禁用警告摘要

-l, --showlocals

在回溯信息中显示局部变量（默认禁用）

--no-showlocals

在回溯信息中隐藏局部变量（用于抵消通过 addopts 传递的 --showlocals 参数）

---tb=style

回溯打印模式（auto/long/short/line/native/no）

--xfail-tb

显示xfail的回溯（只要-tb=no）

--show-capture={no,stdout,stderr,log,all}

控制捕获的stdout/stderr/log在失败的测试中的显示方式。默认值：all。

--full-trace

不剪切任何回溯（默认为剪切）

--color=color

彩色终端输出(yes/no/auto)

--code-highlight

代码高亮显示={yes,no}.是否应突出显示代码（仅当--color也启用时）。默认值：yes。

--pastebin=mode

发送failed|all到bpaste.net pastebin服务

--junit xml=path

在给定路径创建junit xml样式的报告文件

--junit prefix=str

junit-xml输出中类名的前缀

--html=path

在给定路径创建html报告文件。

----self-contained-html

创建一个包含所有必要样式、脚本和图像的自包含的html文件-这意味着在CSP限制到位的情况下，报告可能无法呈现或运行（请参见https://developer.mozilla.org/docs/Web/Security/CSP)

--css=path

将给定的css文件内容附加到报告样式文件中。

pytest警告

-W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS

设置要报告的警告，请查看Python本身的-W选项集合

收集

--collect-only, --co

只收集测试，不执行测试

--pyargs

尝试将所有参数解释为Python包

--ignore=path

收集过程中忽略路径（允许多个）

--ignore glob=path

在收集过程中忽略路径模式（允许多个）

--deselect=nodeid_prefix

在收集过程中取消选择项目（通过节点id前缀）（允许多个）

--confcutdir=dir

仅加载相对于指定目录的conftest.py

--noconftest

不加载任何conftest.py文件

--keep-duplicates

保持重复的目录

--collect-in-virtualenv

不要忽略本地virtualenv目录中的测试

--continue-on-collection-errors

即使发生收集错误，也强制执行测试

--import-mode={prepend,append,importlib}

导入测试模块和conftest文件时，在sys.path前添加/追加。默认值：prepend。

--doctest-modules

在所有.py模块中运行doctests

--doctest-report={none,cdiff,ndiff,udiff,only_first_failure}

在doctest失败时为差异选择另一种输出格式

--doctest-glob=pat

Doctests文件匹配模式，默认：test*.txt

--doctest-ignore-import-errors

忽略doctest收集错误

--doctest-continue-on-failure

对于给定的doctest，在第一次失败后继续运行测试会话调试和配置

测试会话调试与配置

-c FILE，--config FILE=FILE

从“FILE”加载配置，而不是尝试定位隐式配置之一文件夹。

--rootdir=rootdir

定义测试的根目录。可以是相对路径：'root_dir'，'./root_dir'，'root_dir/another_dir/'；绝对路径：'/home/user/root_dir'；带变量的路径：“$HOME/root_dir”。

--basetemp=dir

此测试运行的基本临时目录。（警告：如果此目录存在，则会将其删除。）

-V、 --version

显示pytest版本和相关信息

-h, --help

显示帮助信息和配置详情

-p name

提前加载指定的插件模块名或入口点（允许多个）。若要避免加载插件，请使用 no: 前缀，例如 no:doctest。另请参阅 --disable-plugin-autoload。

--disable-plugin-autoload

通过入口点打包元数据禁用插件自动加载。仅会加载在 -p 参数或环境变量 PYTEST_PLUGINS 中明确指定的插件

--trace-config

追踪 conftest.py 文件的加载过程

--debug=[DEBUG_FILE_NAME]

将内部追踪调试信息存储到此日志文件中。该文件以 'w' 模式打开并会被截断，请谨慎使用。默认值：pytestdebug.log。

-o OVERRIDE_INI, --override-ini=OVERRIDE_INI

使用 "option=value" 格式覆盖 ini 选项，例如 -o xfail_strict=True -o cache_dir=cache。

--assert=MODE

控制断言调试工具。'plain' 不进行断言调试。'rewrite'（默认值）在导入测试模块时重写 assert 语句以提供断言表达式信息。

--setup-only

仅设置夹具，不执行测试

--setup-show

执行测试时显示夹具的设置过程

--setup-plan

显示将要执行的夹具和测试项目，但不实际执行任何操作

logging

--log-level=LEVEL

捕获/显示的消息级别。默认未设置，因此取决于根/父日志处理程序的有效级别，默认为 "WARNING"。

--log-format=LOG_FORMAT

日志模块使用的日志格式

--log-date-format=LOG_DATE_FORMAT

日志模块使用的日志日期格式

--log-cli-level=LOG_CLI_LEVEL

CLI 日志级别

--log-cli-format=LOG_CLI_FORMAT

日志模块使用的日志格式

--log-cli-date-format=LOG_CLI_DATE_FORMAT

日志模块使用的日志日期格式

--log-file=LOG_FILE

日志写入文件的路径

--log-file-mode={w,a}

日志文件打开模式

--log-file-level=LOG_FILE_LEVEL

日志文件日志级别

--log-file-format=LOG_FILE_FORMAT

日志模块使用的日志格式

--log-file-date-format=LOG_FILE_DATE_FORMAT

日志模块使用的日志日期格式

--log-auto-indent=LOG_AUTO_INDENT

自动缩进传递给日志模块的多行消息。接受 true|on、false|off 或整数。

--log-disable=LOGGER_DISABLE

按名称禁用日志记录器。可多次传递

报告

--alluredir=DIR

在指定目录中生成 Allure 报告（目录可以不存在）

--clean-alluredir

如果 alluredir 文件夹存在则清理

--allure-no-capture

不将 pytest 捕获的日志/标准输出/标准错误附加到报告中

--inversion=INVERSION

运行不在测试计划覆盖范围内的测试（支持分布式测试）

--cov=[SOURCE]

执行期间要测量的路径或包名（允许多个）。使用 --cov= 不进行任何源过滤并记录所有内容。

--cov-reset

重置目前选项中累积的覆盖源。

--cov-report=TYPE

要生成的报告类型：term、term-missing、annotate、html、xml、json、lcov（允许多个）。term 和 term-missing 后可接 ":skip-covered"。annotate、html、xml、json 和 lcov 后可接 ":DEST"，其中 DEST 指定输出位置。使用 --cov-report= 不生成任何输出。

--cov-config=PATH

覆盖率的配置文件。默认值：.coveragerc

--no-cov-on-fail

如果测试运行失败则不报告覆盖率。默认值：False

--no-cov

完全禁用覆盖率报告（适用于调试器）。默认值：False

--cov-fail-under=MIN

如果总覆盖率低于 MIN 则失败

--cov-append

不删除覆盖率数据而是追加到当前数据。默认值：False

--cov-branch

启用分支覆盖率

--cov-precision=COV_PRECISION

覆盖报告精度。

--cov-context=CONTEXT

要使用的动态上下文。当前仅支持 "test"。

--metadata=key value

附加元数据。

--metadata-from-json=METADATA_FROM_JSON

来自JSON字符串的附加元数据。

--metadata-from-json-file=METADATA_FROM_JSON_FILE

来自JSON文件的附加元数据。

Playwright

--browser={chromium,firefox,webkit}

应使用的浏览器引擎

--headed

以有头模式运行测试

--browser-channel=BROWSER_CHANNEL

要使用的浏览器渠道

--slowmo=SLOWMO

以慢速模式运行测试

--device=DEVICE

要模拟的设备

--output=OUTPUT

测试生成的产物目录，默认为 test-results

--tracing={on,off,retain-on-failure}

是否为每个测试记录追踪信息

--video={on,off,retain-on-failure}

是否为每个测试录制视频

--screenshot={on,off,only-on-failure}

是否在每个测试后自动捕获截图

--full-page-screenshot

是否截取完整页面截图

自定义选项Custom options

--base-url=url

被测应用程序的基础URL

--verify-base-url

验证基础URL

在找到的首个 pytest.ini|tox.ini|setup.cfg|pyproject.toml 文件中的[pytest]初始化配置选项[pytest] ini-options in the first pytest.ini|tox.ini|setup.cfg|pyproject.toml file found

markers (linelist)

为测试函数注册新标记

empty_parameter_set_mark (string)

为测试函数注册新标记

filterwarnings (linelist)

每行指定一个warnings.filterwarnings模式，在-W/--pythonwarnings之后处理

norecursedirs (args)

递归时要避免的目录模式

testpaths (args)

当命令行未指定文件或目录时，用于搜索测试的目录

collect_imported_tests (bool)

是否在testpaths之外的导入模块中收集测试

consider_namespace_packages (bool)

在导入期间解析模块名称时是否考虑命名空间包

usefixtures (args)

本项目使用的默认夹具列表

python_files (args)

Python测试模块发现的全局样式文件模式

python_classes (args)

Python测试类发现的前缀或全局名称

python_functions (args)

Python测试函数和方法发现的前缀或全局名称

disable_test_id_escaping_and_forfeit_all_rights_to_community_support (bool)

禁用非ASCII字符的字符串转义，可能导致意外副作用（使用风险自负）

console_output_style (string)

控制台输出："classic"经典模式，或带进度信息（"progress"百分比显示 | "count"计数显示 | "progress-even-when-capture-no"即使capture=no也强制显示进度）

verbosity_test_cases (string)

为测试用例执行指定详细级别，覆盖主级别。

xfail_strict (bool)

更高级别将提供每个测试用例的更详细信息未显式给出时xfail标记strict参数的默认值（默认：False）

tmp_path_retention_count (string)

根据tmp_path_retention_policy策略保留tmp_path目录的会话次数

tmp_path_retention_policy (string)

控制根据测试结果保留由tmp_path夹具创建的目录(all/failed/none)

enable_assertion_pass_hook (bool)

启用pytest_assertion_pass钩子。请确保删除任何先前生成的pyc缓存文件

truncation_limit_lines (string)

设置触发截断的行数阈值

truncation_limit_chars (string)

设置触发截断的字符数阈值

verbosity_assertions (string)

为断言指定详细级别，覆盖主级别。更高级别将在断言失败时提供更详细的解释

junit_suite_name (string)

JUnit报告的测试套件名称

junit_logging (string)

将捕获的日志消息写入JUnit报告：可选no|log|system-out|system-err|out-err|all

junit_log_passing_tests (bool)

为通过的测试捕获日志信息到JUnit报告

junit_duration_report (string)

报告持续时间类型：报告 total|call其中之一

junit_family (string)

total总时间|call调用时间生成XML模式：legacy|xunit1|xunit2

doctest_optionflags (args)

doctest的选项标志

doctest_encoding (string)

doctest文件使用的编码

cache_dir (string)

缓存目录路径

log_level (string)

--log-level的默认值

log_format (string)

--log-format的默认值

log_date_format (string)

--log-date-format的默认值

log_cli (bool)

启用测试运行期间的日志显示（也称为"实时日志"）

log_cli_level (string)

--log-cli-level的默认值

log_cli_format (string)

--log-cli-format的默认值

log_cli_date_format (string)

--log-cli-date-format的默认值

log_file (string)

--log-file的默认值

log_file_mode (string)

--log-file-mode的默认值

log_file_level (string):

--log-file-level的默认值

log_file_format (string)

--log-file-format的默认值

log_file_date_format (string)

--log-file-date-format的默认值

log_auto_indent (string)

--log-auto-indent的默认值

faulthandler_timeout (string)

如果测试完成时间超过TIMEOUT秒，则转储所有线程的追溯信息

addopts (args)

额外的命令行选项

minversion (string)

最低要求的pytest版本

pythonpath (paths)

添加路径到sys.path

required_plugins (args)

pytest运行必须存在的插件

base_url (string)

被测应用程序的基础URL

render_collapsed (bool)

以所有行折叠的状态打开报告，适用于超大型报告

max_asset_filename_length (string)

设置HTML报告中附加资源的最大文件名长度

environment_table_redact_list (linelist)

应对其值从报告中编辑的环境表变量正则表达式列表

环境变量

CI

当设置此选项时（无论值为何），pytest 将识别当前处于 CI 流程中运行，并不再截断摘要信息

BUILD_NUMBER

等效于 CI 环境标识

PYTEST_ADDOPTS

额外的命令行选项

PYTEST_PLUGINS

启动时加载的逗号分隔插件列表

PYTEST_DISABLE_PLUGIN_AUTOLOAD

设置此项以禁用插件自动加载功能

PYTEST_DEBUG

设置此项以启用 pytest 内部调试追踪