Pytest第三章（参考指南4）

回到目录

第三章参考指南

3.4 API 参考

3.4.7 对象

OptionGroup 类

class OptionGroup

在自己的部分中显示的一组选项。
**addoption(*opts, attrs)
- 向此组添加一个选项。
- 如果指定了长选项的简写版本，它将在帮助信息中被抑制。例如，addoption(‘–two-words’, ‘–tw-words’) 会导致帮助信息仅显示 --two-words，但 --tw-words 会被接受，并且自动目标位于 args.two_words 中。
- 参数
  - opts (str) - 选项名，可以是短选项或长选项。
  - attrs (Any) - 与 argparse 库的 add_argument() 函数接受的相同属性。

PytestPluginManager 类

final class PytestPluginManager

基类：PluginManager
一个带有额外 pytest 特定功能的插件管理器：
- 从命令行、PYTEST_PLUGINS 环境变量和在加载插件时找到的 pytest_plugins 全局变量中加载插件。
- 在启动期间加载 conftest.py。
register(plugin, name=None)
- 注册一个插件并返回其名称。
- 参数
  - name (str | None) - 注册插件的名称。如果未指定，将使用 get_canonical_name() 生成一个名称。
- 返回
  - 插件名称。如果名称被阻止注册，则返回 None。
- 返回类型
  - str | None
- 如果插件已注册，将引发 ValueError。
getplugin(name)
- 获取插件。
hasplugin(name)
- 检查是否已注册具有给定名称的插件。
import_plugin(modname, consider_entry_points=False)
- 导入具有 modname 的插件。
- 如果 consider_entry_points 为 True，则也会考虑入口点名称来查找插件。
add_hookcall_monitoring(before, after)
- 为所有钩子添加前后跟踪函数。
- 返回一个撤销函数，调用该函数时会移除添加的追踪器。
- before(hook_name, hook_impls, kwargs) 将在所有钩子调用之前被调用，并接收一个 hookcaller 实例、HookImpl 实例列表和钩子调用的关键字参数。
- after(outcome, hook_name, hook_impls, kwargs) 接收与 before 相同的参数，但还包含一个表示整个钩子调用结果的 Result 对象。
add_hookspecs(module_or_class)
- 添加在给定模块或类中定义的新钩子规范。
- 如果函数已被相应的 HookspecMarker 装饰，则会被识别为钩子规范。
check_pending()
- 验证所有未针对钩子规范进行验证的钩子都是可选的，否则将引发 PluginValidationError。
enable_tracing()
- 启用钩子调用的跟踪。
- 返回一个撤销函数，调用该函数时会移除添加的跟踪。
get_canonical_name(plugin)
- 为插件对象返回一个标准名称。
- 注意，插件可能以由 register(plugin, name) 的调用者指定的不同名称注册。要获取已注册插件的名称，请使用 get_name(plugin)。
get_hookcallers(plugin)
- 获取指定插件的所有钩子调用者。
- 返回
  - 钩子调用者，如果插件未在此插件管理器中注册，则返回 None。
- 返回类型
  - list[HookCaller] | None
get_name(plugin)
- 返回插件注册的名称，如果未注册则返回 None。
get_plugin(name)
- 返回在给定名称下注册的插件（如果有）。
get_plugins()
- 返回所有已注册插件对象的集合。
has_plugin(name)
- 返回是否已注册具有给定名称的插件。
is_blocked(name)
- 返回给定插件名称是否被阻止。
is_registered(plugin)
- 返回插件是否已注册。
list_name_plugin()
- 返回所有已注册插件的 (name, plugin) 对列表。
list_plugin_distinfo()
- 返回所有 setuptools 注册插件的 (plugin, distinfo) 对列表。
load_setuptools_entrypoints(group, name=None)
- 从查询指定的 setuptools 组加载模块。
- 参数：
  - group (str) - 要加载插件的入口点组。
  - name (str | None) - 如果提供，则仅加载具有给定名称的插件。
- 返回：
  - 此调用加载的插件数量。
- 返回类型：
  - int
set_blocked(name)
- 阻止给定名称的注册，如果已注册则取消注册。
subset_hook_caller(name, remove_plugins)
- 返回一个代理 HookCaller 实例，用于管理对所有已注册插件（除了 remove_plugins 中的插件）的命名方法调用。
unblock(name)
- 解除一个名称的阻塞。
- 返回该名称是否实际被阻塞。
unregister(plugin=None, name=None)
- 注销一个插件及其所有钩子实现。
- 插件可以通过插件对象或插件名称指定。如果两者都指定了，它们必须一致。
- 返回注销的插件，如果没有找到则返回 None。
project_name: Final
- 项目名称。
hook: Final
- “钩子中继”，用于在所有已注册插件上调用钩子。参见调用钩子。
trace: Final[tracing.TagTracerSub]
- 跟踪入口点。参见内置跟踪。

TerminalReporter类

final class TerminalReporter(config, file=None)

wrap_write(content, *, flush=False, margin=8, line_sep='\n', **markup)
- 用边距包装消息以显示进度信息。
rewrite(line, **markup)
- 将终端光标重置到行首并写入给定的行。
- 参数：
  - erase - 如果为 True，还会添加空格直到整个终端宽度，以确保之前的行被正确擦除。
- 其余的关键字参数是标记指令。
build_summary_stats_line()
- 构建在最后的摘要统计行中使用的部分。
- 摘要统计行是在结尾显示的行，例如“=== 12 passed, 2 errors in Xs ===”。
- 此函数构建组成该行文本的“部分”列表，在上面的例子中它将是：
```
        [
            ("12 passed", {"green": True}),
            ("2 errors", {"red": True})
        ]
```
- 每一行的最后一个字典是一个“标记字典”，由 TerminalWriter 用于着色输出。
- 行的最终颜色也由这个函数确定，并且是返回元组的第二个元素。

TestReport类

final class TestReport

基类：BaseReport
基本测试报告对象（如果 setup 和 teardown 调用失败也会使用）。
报告可以包含任意额外属性。
nodeid: str
- 规范化的收集节点ID。
location: tuple[str, int | None, str]
- 一个 (文件系统路径, 行号, 域信息) 元组，指示测试项的实际位置——它可能与收集的位置不同，例如，如果方法是从其他模块继承的。文件系统路径可能是相对于 config.rootdir 的。行号从0开始。
keywords: Mapping[str, Any]
- 包含所有与测试调用相关的关键词和标记的名称>值字典。
outcome: Literal[‘passed’, ‘failed’, ‘skipped’]
- 测试结果，总是以下之一：“passed”，“failed”，“skipped”。
longrepr: None | ExceptionInfo[BaseException] | tuple[str, int, str] | str | TerminalRepr
- 失败表示或 None。
when: str | None
- “setup”, “call”, “teardown”之一，表示运行测试阶段。
user_properties
- 用户属性是一个包含 (name, value) 的元组列表，保存用户定义的测试属性。
sections: list[tuple[str, str]]
- 字符串元组 (标题, 内容)，为测试报告提供额外信息。pytest 用它来添加从 stdout、stderr 和拦截的日志事件捕获的文本。其他插件也可以用它来向报告中添加任意信息。
duration: float
- 运行测试所需的时间。
start: float
- 自纪元以来，调用开始时的系统时间，以秒为单位。
stop: float
- 自纪元以来，调用结束时的系统时间，以秒为单位。
类方法 from_item_and_call(item, call)
- 创建并填充一个带有标准项和调用信息的 TestReport。
- 参数
  - item(Item) - 项。
  - call(CallInfo[None]) - 调用信息。
属性 caplog: str
- 如果启用了日志捕获，则返回捕获的日志行。
- 在版本3.5中添加。
属性 capstderr: str
- 如果启用了捕获，则返回从 stderr 捕获的文本。
- 在版本3.0中添加。
属性 capstdout: str
- 如果启用了捕获，则返回从 stdout 捕获的文本。
- 在版本3.0中添加。
属性 count_towards_summary: bool
- 实验性是否应将此报告计入测试会话结束时显示的总计数中，如“1 通过，1 失败等”。
- 注意：
  - 此函数被认为是实验性的，因此请注意它可能会在补丁版本中发生变化。
属性 failed: bool
- 结果是否失败。
属性 fspath: str
- 报告节点的路径部分，作为字符串。
属性 headline: str | None
- 实验性在此报告的 longrepr 输出中显示的标题行，更常见于在失败期间的回溯表示：
```
----------------------Test.foo--------------------
```
- 在上面的例子中，headline 是 “Test.foo”。
- 注意：
  - 此函数被认为是实验性的，因此请注意它可能会在补丁版本中发生变化。
属性 longreprtext: str
- 只读属性，返回 longrepr 的完整字符串表示。
- 在版本3.0中添加。
属性 passed: bool
- 结果是否通过。
属性 skipped: bool
- 结果是否跳过。

TestShortLogReport类

class TestShortLogReport

用于存储测试状态结果类别、简短字母和详细单词。例如 “rerun”，“R”，(“RERUN”, {“yellow”: True})。
变量：
- category - 结果的类别，例如“passed”、“skipped”、“error”，或空字符串。
- letter - 测试进行时显示的简短字母，例如“.”、“s”、“E”，或空字符串。
- word - 在详细模式下，测试进行时显示的详细单词，例如"PASSED"、“SKIPPED”、“ERROR”，或空字符串。
category: str
- 字段编号0的别名
letter: str
- 字段编号1的别名
word: str | tuple[str, Mapping[str, bool]]
- 字段编号2的别名

Result类

Result 对象在 hook wrappers 中使用，有关更多信息，请参阅插件文档中的 Result。

Stash 类

class Stash

Stash 是一个类型安全的异构可变映射，允许键和值类型在创建它（即 Stash）的位置之外单独定义。
通常你会得到一个具有 Stash 的对象，例如 Config 或 Node：
```
stash: Stash = some_object.stash
```
如果一个模块或插件想要在此 Stash 中存储数据，它会为其键创建 StashKeys（在模块级别）：
```
# 在模块的顶层
some_str_key = StashKey[str]()
some_bool_key = StashKey[bool]()
```

要存储信息：

# 值类型必须与键匹配。
stash[some_str_key] = "value"
stash[some_bool_key] = True

要检索信息：

# some_str 的静态类型是 str。
some_str = stash[some_str_key]
# some_bool 的静态类型是 bool。
some_bool = stash[some_bool_key]

新增于版本 7.0。
__setitem__(key, value)
- 为键设置值。
__getitem__(key)
- 获取键的值。
- 如果键之前未设置，则引发 KeyError。
get(key, default)
- 获取键的值，如果键之前未设置则返回默认值。
setdefault(key, default)
- 如果已设置，则返回键的值；否则将键的值设置为默认值并返回默认值。
__delitem__(key)
- 删除键的值。
- 如果键之前未设置，则引发 KeyError。
__contains__(key)
- 返回键是否已设置。
__len__()
- 返回 Stash 中存在的项数。

class StashKey

基类：Generic[T]
StashKey 是用作 Stash 键的对象。
StashKey 与键值的类型 T 相关联。
StashKey 是唯一的，不会与其他键冲突。
新增于版本 7.0。

3.4.8 全局变量

pytest 在测试模块或 conftest.py 文件中定义某些全局变量时会以特殊方式处理。

collect_ignore

可以在 conftest.py 文件中声明，以排除测试目录或模块。需要是一个路径列表（str、pathlib.Path 或任何 os.PathLike）。

collect_ignore = ["setup.py"]

collect_ignore_glob

可以在 conftest.py 文件中声明，以使用 Unix shell 风格的通配符排除测试目录或模块。需要是一个字符串列表，其中字符串可以包含 glob 模式。

collect_ignore_glob = ["*_ignore.py"]

pytest_plugins

可以在测试模块和 conftest.py 文件的全局级别声明，以注册额外的插件。可以是 str 或 Sequence[str] 类型。

pytest_plugins = "myapp.testsupport.myplugin"
pytest_plugins = ("myapp.testsupport.tools", "myapp.testsupport.regression")

pytestmark

可以在测试模块的全局级别声明，以将一个或多个标记应用于所有测试函数和方法。可以是一个单个标记或标记列表（按从左到右的顺序应用）。

import pytest

pytestmark = pytest.mark.webtest

import pytest

pytestmark = [pytest.mark.integration, pytest.mark.slow]

3.4.9 环境变量

可以用来改变 pytest 行为的环境变量。

CI

当设置（无论值为何），pytest 会识别出它正在 CI 进程中运行。这是 BUILD_NUMBER 变量的替代选项。另见 ci-pipelines。

BUILD_NUMBER

当设置（无论值为何），pytest 会识别出它正在 CI 进程中运行。这是 CI 变量的替代选项。另见 ci-pipelines。

PYTEST_ADDOPTS

这包含一个命令行（由 py:mod:shlex 模块解析），该命令行将被添加到用户提供的命令行之前，详见内置配置文件选项以获取更多信息。

PYTEST_VERSION

此环境变量在 pytest 会话开始时定义，之后未定义。它包含 pytest.version 的值，可用于轻松检查代码是否在 pytest 运行中执行。

PYTEST_CURRENT_TEST

这不是由用户设置的，而是由 pytest 内部使用当前测试的名称设置的，以便其他进程可以检查它，有关更多信息，请参阅 PYTEST_CURRENT_TEST 环境变量。

PYTEST_DEBUG

当设置时，pytest 将打印跟踪和调试信息。

PYTEST_DEBUG_TEMPROOT

由 tmp_path 等固定装置生成的临时目录的根目录，如“临时目录位置和保留”中所述。

PYTEST_DISABLE_PLUGIN_AUTOLOAD

当设置时，禁用通过入口点打包元数据自动加载插件。仅显式指定的插件将被加载。

PYTEST_PLUGINS

包含应作为插件加载的模块的逗号分隔列表：
```
export PYTEST_PLUGINS=my_module.plugin,x_dist
```

PYTEST_THEME

为代码输出设置 pygment 样式。

PYTEST_THEME_MODE

将 PYTEST_THEME 设置为 dark 或 light。

PY_COLORS

当设置为 1 时，pytest 将在终端输出中使用颜色。当设置为 0 时，pytest 不使用颜色。PY_COLORS 优先于 NO_COLOR 和 FORCE_COLOR。

NO_COLOR

当设置为非空字符串（无论值为何）时，pytest 将不在终端输出中使用颜色。PY_COLORS 优先于 NO_COLOR，而 NO_COLOR 优先于 FORCE_COLOR。请参阅 no-color.org 了解支持此社区标准的其他库。

FORCE_COLOR

当设置为非空字符串（无论值为何）时，pytest 将在终端输出中使用颜色。PY_COLORS 和 NO_COLOR 优先于 FORCE_COLOR。

3.4.10 异常

final exception UsageError

基类：Exception
pytest 使用或调用中的错误。

final exception FixtureLookupError

基类：LookupError
无法返回请求的固定装置（缺失或无效）。

3.4.11 警告

在某些情况下生成的自定义警告，例如使用不当或已弃用的功能。

class PytestWarning

基类：UserWarning
pytest 发出的所有警告的基类。

class PytestAssertRewriteWarning

基类：PytestWarning
由 pytest 断言重写模块发出的警告。

class PytestCacheWarning

基类：PytestWarning
在各种情况下由缓存插件发出的警告。

class PytestCollectionWarning

基类：PytestWarning
当 pytest 无法收集模块中的文件或符号时发出的警告。

class PytestConfigWarning

基类：PytestWarning
为配置问题发出的警告。

class PytestDeprecationWarning

基类：PytestWarning, DeprecationWarning
用于将在未来版本中移除的功能的警告类别。

class PytestExperimentalApiWarning

基类：PytestWarning, FutureWarning
用于表示 pytest 中实验功能的警告类别。由于 API 可能会更改甚至在未来版本中完全移除，因此应谨慎使用。

class PytestRemovedIn9Warning

基类：PytestDeprecationWarning
用于将在 pytest 9 中移除的功能的警告类别。

class PytestUnknownMarkWarning

基类：PytestWarning
在使用未知标记时发出的警告。有关详细信息，请参阅如何使用属性标记测试函数。

class PytestUnraisableExceptionWarning

基类：PytestWarning
报告了一个不可引发的异常。不可引发的异常是在 del 实现和其他类似情况下引发的异常，这些情况下异常不能像正常情况一样被引发。

class PytestUnhandledThreadExceptionWarning

基类：PytestWarning
在一个线程中发生了未处理的异常。此类异常不会像正常情况一样传播。

有关更多信息，请参阅文档中的内部 pytest 警告部分。

3.4.12 配置选项

以下是一些内置配置选项的列表，这些选项可以写入 pytest.ini（或 .pytest.ini）、pyproject.toml、tox.ini 或 setup.cfg 文件中，通常位于仓库的根目录。

要详细了解每个文件格式，请参阅“配置文件格式”。

警告：

除了一些及其简单的使用场景外，不建议使用setup.cfg配置文件。

配置选项可以通过命令行使用 -o/--override-ini 覆盖，该选项也可以多次传递。预期的格式是 name=value。例如：

pytest -o console_output_style=classic -o cache_dir=/tmp/mycache

addopts

将指定的 OPTS 添加到命令行参数集中，就像它们是由用户指定的一样。示例：如果你有以下 ini 文件内容：
```
# pytest.ini 的内容
[pytest]
addopts = --maxfail=2 -rf  # 在两次失败后退出，并报告失败信息
```
执行 pytest test_hello.py 实际上意味着：
```
pytest --maxfail=2 -rf test_hello.py
```
默认情况下不添加任何选项。

cachedir

设置缓存插件内容存储的目录。默认目录是 .pytest_cache，在 rootdir 中创建。目录可以是相对路径或绝对路径。如果设置相对路径，则该目录相对于 rootdir 创建。此外，路径可能包含环境变量，这些变量将被展开。有关缓存插件的更多信息，请参阅“如何重新运行失败的测试并在测试运行之间保持状态”。

collect_imported_tests

在版本 8.4 中新增。将其设置为 false 将使 pytest 只从定义了类/函数的测试文件中收集类/函数（而不是导入的地方）。
```
[pytest]
collect_imported_tests = false
```
默认值：true

pytest 通常会在测试模块命名空间中收集类/函数，即使它们是从另一个文件导入的。例如：

# src/domain.py 的内容
class Testament: ...

# tests/test_testament.py 的内容
from domain import Testament

def test_testament(): ...

在这种情况下，默认选项下，pytest 将从 tests/test_testament.py 收集 Testament 类，因为它以 Test 开头，尽管在这种情况下它是一个生产类，在测试模块命名空间中被导入。
在配置文件中将 collected_imported_tests 设置为 false 可以防止这种情况。

consider_namespace_packages

控制 pytest 在收集 Python 模块时是否尝试识别命名空间包。默认值为 False。
如果要测试的包是命名空间包的一部分，请将其设置为 True。
仅支持原生命名空间包，没有计划支持旧版命名空间包。
在版本 8.1 中新增。

console_output_style

设置运行测试时的控制台输出样式：
- classic: 经典的 pytest 输出。
- progress: 类似经典 pytest 输出，但带有进度指示器。
- progress-even-when-capture-no: 即使在 capture=no 时也允许使用进度指示器。
- count: 类似 progress，但显示已完成测试的数量而不是百分比。
- times: 显示测试持续时间。
默认值是 progress，但如果你更喜欢或新模式导致意外问题，可以回退到 classic：
```
# pytest.ini 的内容
[pytest]
console_output_style = classic
```

disable_test_id_escaping_and_forfeit_all_rights_to_community_support

在版本 4.4 中新增。
pytest 默认会转义 unicode 字符串中用于参数化的任何非 ASCII 字符，因为它有几个缺点。然而，如果你想在参数化中使用 unicode 字符串并在终端中看到它们（未转义），请在你的 pytest.ini 中使用此选项：
```
[pytest]
disable_test_id_escaping_and_forfeit_all_rights_to_community_support = True
```
请注意，这可能会导致不必要的副作用，甚至根据使用的操作系统和当前安装的插件产生错误，因此请自行承担风险使用它。
默认值为 False。
参见 @pytest.mark.parametrize: 参数化测试函数。

doctest_encoding

解码包含 docstrings 的文本文件时使用的默认编码。参见 pytest 如何处理 doctests。

doctest_optionflags

一个或多个来自标准 doctest 模块的 doctest 标志名称。参见 pytest 如何处理 doctests。

empty_parameter_set_mark

允许选择对参数化中的空参数集的操作：
- skip 跳过具有空参数集的测试（默认）
- xfail 将具有空参数集的测试标记为 xfail(run=False)
- fail_at_collect 如果 parametrize 收集到空参数集，则引发异常
```
# pytest.ini 的内容
[pytest]
empty_parameter_set_mark = xfail
```
注意
- 该选项的默认值计划在未来版本中更改为 xfail，因为这被认为较少出错，请参阅 #3155 获取更多详细信息。

fault_handler_timeout

如果测试运行时间超过 x 秒（包括 fixture 设置和拆卸），则转储所有线程的堆栈跟踪。使用 fault_handler.dump_traceback_later() 函数实现，因此所有注意事项都适用。
```
# pytest.ini 的内容
[pytest]
fault_handler_timeout = 5
```
有关更多信息，请参阅 fault_handler。

filterwarnings

设置一个过滤器和操作的列表，这些应该针对匹配的警告采取。默认情况下，在测试会话期间发出的所有警告将在测试会话结束时以摘要形式显示。
```
# pytest.ini 的内容
[pytest]
filterwarnings =
    error
    ignore::DeprecationWarning
```
这告诉 pytest 忽略弃用警告，并将所有其他警告转换为错误。有关更多信息，请参阅“如何捕获警告”。

junit_duration_report

在版本 4.1 中新增。配置 JUnit XML 报告中记录持续时间的方式：
- total（默认）：报告的持续时间包括设置、调用和拆卸时间。
- call：报告的持续时间仅包括调用时间，不包括设置和拆卸时间。
```
[pytest]
junit_duration_report = call
```

junit_family

在版本 4.2 中新增。在版本 6.1 中更改：默认值更改为 xunit2。配置生成的 JUnit XML 文件的格式。可能的选项有：
- xunit1（或 legacy）：产生旧样式输出，与 xunit 1.0 格式兼容。
- xunit2：产生 xunit 2.0 样式输出，这应与最新版本的 Jenkins 更加兼容。这是默认值。
```
[pytest]
junit_family = xunit2
```

junit_logging

在版本 3.5 中新增。
在版本 5.4 中更改：添加了 log、all 和 out-err 选项。
配置是否应将捕获的输出写入 JUnit XML 文件。有效值为：
- log：仅写入捕获的日志输出。
- system-out：写入捕获的 stdout 内容。
- system-err：写入捕获的 stderr 内容。
- out-err：写入捕获的 stdout 和 stderr 内容。
- all：写入捕获的日志、stdout 和 stderr 内容。
- no（默认值）：不写入任何捕获的输出。
```
[pytest]
junit_logging = system-out
```

junit_log_passing_tests

在版本 4.6 中新增。
如果 junit_logging != “no”，则配置是否应将捕获的输出写入通过测试的 JUnit XML 文件中。默认值为 True。
```
[pytest]
junit_log_passing_tests = False
```

junit_suite_name

要设置根测试套件 xml 项的名称，可以在配置文件中配置 junit_suite_name 选项：
```
[pytest]
junit_suite_name = my_suite
```

log_auto_indent

允许选择性地自动缩进多行日志消息。
支持命令行选项 --log-auto-indent [value] 和配置选项 log_auto_indent = [value] 来设置所有日志的自动缩进行为。
[value] 可以是：
- True 或 “On” - 动态自动缩进多行日志消息。
- False 或 “Off” 或 0 - 不自动缩进多行日志消息（默认行为）。
- [正整数] - 按 [value] 空格自动缩进多行日志消息。
```
[pytest]
log_auto_indent = False
```
支持传递 kwarg extra={“auto_indent”: [value]} 到 logging.log() 调用中，以指定日志中特定条目的自动缩进行为。extra kwarg 会覆盖命令行或配置中指定的值。

log_cli

启用测试运行期间的日志显示（也称为“实时日志记录”）。默认值为 False。
```
[pytest]
log_cli = True
```

log_cli_date_format

设置一个与 time.strftime() 兼容的字符串，用于格式化实时日志记录中的日期。
```
[pytest]
log_cli_date_format = %Y-%m-%d %H:%M:%S
```
有关更多信息，请参阅 Live Logs。

log_cli_format

设置一个与 logging 兼容的字符串，用于格式化实时日志消息。
```
[pytest]
log_cli_format = %(asctime)s %(levelname)s %(message)s
```
有关更多信息，请参阅 Live Logs。

log_cli_level

设置应为实时日志记录捕获的最低日志消息级别。可以使用整数值或级别的名称。
```
[pytest]
log_cli_level = INFO
```
有关更多信息，请参阅 Live Logs。

log_date_format

设置一个与 time.strftime() 兼容的字符串，该字符串将在格式化日志捕获日期时使用。
```
[pytest]
log_date_format = %Y-%m-%d %H:%M:%S
```
有关更多信息，请参阅 How to manage logging。

log_file

设置一个相对于当前工作目录的文件名，日志消息应写入该文件，除了其他正在使用的日志设施外。
```
[pytest]
log_file = logs/pytest-logs.txt
```
有关更多信息，请参阅 How to manage logging。

log_file_date_format

设置一个与 time.strftime() 兼容的字符串，该字符串将在格式化日志文件中的日期时使用。
```
[pytest]
log_file_date_format = %Y-%m-%d %H:%M:%S
```
有关更多信息，请参阅 How to manage logging。

log_file_format

设置一个与 logging 兼容的字符串，用于格式化重定向到日志文件的日志消息。
```
[pytest]
log_file_format = %(asctime)s %(levelname)s %(message)s
```
有关更多信息，请参阅 How to manage logging。

log_file_level

设置日志文件应捕获的最低日志消息级别。可以使用整数值或级别的名称。
```
[pytest]
log_file_level = INFO
```
有关更多信息，请参阅如何管理日志记录。

log_format

设置一个与 logging 兼容的字符串，用于格式化捕获的日志消息。
```
[pytest]
log_format = %(asctime)s %(levelname)s %(message)s
```
有关更多信息，请参阅如何管理日志记录。

log_level

设置日志捕获应捕获的最低日志消息级别。可以使用整数值或级别的名称。
```
[pytest]
log_level = INFO
```
有关更多信息，请参阅如何管理日志记录。

markers

当使用 --strict-markers 或 --strict 命令行参数时，只允许已知标记——由 pytest 核心代码或某些插件定义的标记。
你可以在该设置中列出其他标记以将其添加到白名单中，在这种情况下，你可能需要添加 --strict-markers 到 addopts 以避免未来的回归问题：
```
[pytest]
addopts = --strict-markers
markers =
    slow
    serial
```
注意
- 强烈建议使用 --strict-markers。–strict 仅保留用于向后兼容性，并且可能会使其他人感到困惑，因为它仅适用于标记而不适用于其他选项。

minversion

指定运行测试所需的最小 pytest 版本。

# pytest.ini 的内容
[pytest]
minversion = 3.0  # 如果我们使用 pytest-2.8 运行将失败

no_recurse_dirs

设置在递归进行测试发现时要避免的目录基本名称模式。各个（fnmatch 风格）模式应用于目录的基本名称，以决定是否递归进入该目录。模式匹配字符：
- - 匹配所有内容
- ? 匹配任何单个字符
- [seq] 匹配 seq 中的任何字符
- [!seq] 匹配不在 seq 中的任何字符
默认模式是 ‘.egg’, '.’, ‘_darcs’, ‘.build’, ‘.CVS’, ‘.dist’, ‘.node_modules’, ‘.venv’, ‘{arch}’。设置 no_recurse_dirs 会替换默认值。以下是一个如何避免某些目录的例子：
```
[pytest]
norecursedirs = .svn _build tmp*
```
这将告诉 pytest 不要查看典型的 subversion 或 sphinx-build 目录或任何以 tmp 开头的目录。
此外，pytest 将尝试智能地识别并忽略虚拟环境。任何被认为是虚拟环境根目录的目录在测试收集期间不会被考虑，除非给出了 --collect-in-virtualenv。注意 no_recurse_dirs 的优先级高于 --collect-in-virtualenv；例如，如果你打算在一个与 .* 匹配的基础目录中的虚拟环境中运行测试，你必须覆盖 no_recurse_dirs 并使用 --collect-in-virtualenv 标志。

python_classes

一个或多个名称前缀或 glob 风格的模式，用于确定哪些类被视为测试收集的对象。通过在模式之间添加空格来搜索多个 glob 模式。默认情况下，pytest 将任何以 Test 开头的类视为测试收集对象。以下是如何从以 Suite 结尾的类中收集测试的一个例子：
```
[pytest]
python_classes = *Suite
```
请注意，无论此选项如何，unittest.TestCase 的派生类总是会被收集，因为 unittest 自己的收集框架用于收集这些测试。

python_files

一个或多个 Glob 风格的文件模式，用于确定哪些 Python 文件被视为测试模块。通过在模式之间添加空格来搜索多个 glob 模式：
```
[pytest]
python_files = test_*.py check_*.py example_*.py
```

或者每行一个：

[pytest]
python_files =
    test_*.py
    check_*.py
    example_*.py

默认情况下，匹配 test_*.py 和 *_test.py 的文件将被视为测试模块。

python_functions

一个或多个名称前缀或 glob 模式，用于确定哪些测试函数和方法被视为测试。通过在模式之间添加空格来搜索多个 glob 模式。默认情况下，pytest 将任何以 test 开头的函数视为测试。以下是如何收集以 test 结尾的测试函数和方法的一个例子：
```
[pytest]
python_functions = *test
```
请注意，这对于 unittest.TestCase 派生类上的方法没有影响，因为 unittest 自己的收集框架用于收集这些测试。
有关更详细的示例，请参阅更改命名约定。

pythonpath

设置应添加到 Python 搜索路径的目录列表。这些目录将被添加到 sys.path 的头部。类似于 PYTHONPATH 环境变量，这些目录将包含在 Python 查找导入模块的位置中。路径相对于 rootdir 目录。在整个测试会话期间，这些目录保留在路径中。
```
[pytest]
pythonpath = src1 src2
```

required_plugins

必须存在的插件列表，以空格分隔。插件可以列出版本说明符或不带版本说明符直接跟在其名称之后。不同版本说明符之间的空白是不允许的。如果找不到任何一个插件，则发出错误。

[pytest]
required_plugins = pytest-django>=3.0.0,<4.0.0 pytest-html pytest-xdist>=1.0.0

testpaths

当从 rootdir 目录执行 pytest 时，如果没有在命令行中指定具体的目录、文件或测试 ID，此选项设置应搜索测试的目录列表。文件系统路径可以使用 shell 风格的通配符，包括递归的 ** 模式。
当所有项目测试都在已知位置时非常有用，可以加快测试收集速度，并避免意外地选择不需要的测试。
```
[pytest]
testpaths = testing doc
```
此配置意味着执行：
```
pytest
```
与执行以下命令具有相同的实际效果：
```
pytest testing doc
```

tmp_path_retention_count

根据 tmp_path_retention_policy，我们应该保留多少个会话的 tmp_path 目录。
```
[pytest]
tmp_path_retention_count = 3
```
默认值：3

tmp_path_retention_policy

控制由 tmp_path 固定装置创建的目录基于测试结果保留哪些目录。
- all: 保留所有测试的目录，无论结果如何。
- failed: 仅保留结果为错误或失败的测试的目录。
- none: 在每个测试结束后总是删除目录，无论结果如何。
```
[pytest]
tmp_path_retention_policy = all
```
默认值：all

truncation_limit_chars

控制断言消息内容的最大截断字符数。
将值设置为 0 可禁用截断的字符限制。
```
[pytest]
truncation_limit_chars = 640
```
pytest 默认会将断言消息截断到一定长度，以防止与大量数据进行比较时导致控制台输出过载。
默认值：640
注意
- 如果 pytest 检测到它正在 CI 上运行，则自动禁用截断。

truncation_limit_lines

控制断言消息内容的最大截断行数。
将值设置为 0 可禁用截断的行数限制。
```
[pytest]
truncation_limit_lines = 8
```
pytest 默认会将断言消息截断到一定长度，以防止与大量数据进行比较时导致控制台输出过载。
默认值：8
注意
- 如果 pytest 检测到它正在 CI 上运行，则自动禁用截断。

usefixtures

将应用于所有测试函数的固定装置列表；这在语义上等同于将 @pytest.mark.usefixtures 标记应用于所有测试函数。
```
[pytest]
usefixtures =
    clear_db
```

verbosity_assertions

专门为断言相关的输出设置详细程度级别，覆盖应用程序级别的详细程度。
```
[pytest]
verbosity_assertions = 2
```
默认情况下采用应用程序级别的详细程度（通过命令行选项）。可以使用特殊值“auto”显式地使用全局详细程度级别。

verbosity_test_cases

为测试用例执行相关的输出设置一个特定的详细程度级别，覆盖应用程序级别的详细程度。
```
[pytest]
verbosity_test_cases = 2
```
默认情况下采用应用程序级别的详细程度（通过命令行选项 -v）。可以使用特殊值“auto”显式地使用全局详细程度级别。

xfail_strict

如果设置为 True，实际成功的用 @pytest.mark.xfail 标记的测试将默认使测试套件失败。有关更多信息，请参阅 strict 参数。
```
[pytest]
xfail_strict = True
```

3.4.13 命令行

所有命令行标志可以通过运行 pytest --help 获得：

$ pytest --help
用法：pytest [选项] [文件或目录] [文件或目录] [...]

位置参数：
- file_or_dir
通用：
- -k EXPRESSION 只运行与给定子字符串表达式匹配的测试。表达式是一个可评估的Python表达式，其中所有名称都与测试名称及其父类进行子字符串匹配。例如：-k ‘test_method or test_other’ 匹配所有名称包含’test_method’或’test_other’的测试函数和类，而 -k ‘not test_method’ 匹配那些名称中不包含’test_method’的测试。-k ‘not test_method and not test_other’ 将消除这些匹配项。此外，关键字还与包含额外名称的类和函数匹配，以及直接分配给它们名称的函数。匹配是不区分大小写的。
- -m MARKEXPR 只运行与给定标记表达式匹配的测试。例如：-m ‘mark1 and not mark2’。
- –markers 显示标记（内置、插件和每个项目的标记）。
- -x, --exitfirst 在第一个错误或失败测试时立即退出。
- –fixtures, --funcargs 显示可用的fixture，按插件出现排序（以’_‘开头的fixture仅在’-v’下显示）。
- –fixtures-per-test 按测试显示fixture。
- –pdb 在错误或KeyboardInterrupt时启动交互式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 运行所有测试，但先运行上次失败的测试。这可能会重新排序测试，从而导致重复的fixture设置/拆卸。
- –nf, --new-first 首先运行新文件中的测试，然后按文件修改时间排序其余测试。
- –cache-show=[CACHESHOW] 显示缓存内容，不执行收集或测试。可选参数：glob（默认：‘*’）。
- –cache-clear 在测试运行开始时删除所有缓存内容。
- –lfnf={all,none}, --last-failed-no-failures={all,none} 与…–lf一起确定当没有先前（已知）的失败或没有找到缓存的’last failed’数据时是否执行测试。‘all’（默认）再次运行完整的测试套件。'none’只发出关于没有已知失败的消息并成功退出。
- –sw, --stepwise 在测试失败时退出，并从下次最后失败的测试继续。
- –sw-skip, --stepwise-skip 忽略第一个失败的测试，但在下一个失败的测试处停止。隐式启用–stepwise。
报告：
- –durations=N 显示N个最慢的设置/测试持续时间（N=0表示全部）。
- –durations-min=N 最小持续时间（秒），用于包含在最慢列表中。默认值：0.005。
- -v, --verbose 增加详细程度。
- –no-header 禁用标题。
- –no-summary 禁用摘要。
- –no-fold-skipped 不在简短摘要中折叠跳过的测试。
- -q, --quiet 减少详细程度。
- –verbosity=VERBOSE 设置详细程度。默认值：0。
- -r chars 根据字符显示额外的测试摘要信息：(f) 失败，(E) 错误，(s) 跳过，(x) 失败，(X) 通过，§ 通过，§ 输出通过，(a) 除通过外的所有，(A) 全部。(w) 警告默认启用（参见–disable-warnings），'N’可以用来重置列表。（默认：‘fE’）。
- –disable-warnings, --disable-pytest-warnings 禁用警告摘要。
- -l, --showlocals 在回溯中显示局部变量（默认禁用）。
- –no-showlocals 在回溯中隐藏局部变量（否定–showlocals，通过addopts传递）。
- –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 将失败/所有信息发送到 bpaste.net pastebin 服务。
- –junit-xml=path 在指定路径创建 junit-xml 样式的报告文件。
- –junit-prefix=str 在 junit-xml 输出中为类名添加前缀。
pytest-警告:
- -W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS 设置要报告的警告，参见 Python 自身的 -W 选项。
- –maxfail=num 在首次出现 num 次失败或错误后退出。
- –strict-config 解析配置文件中的 ‘pytest’ 部分时遇到的任何警告都会引发错误。
- –strict-markers 未在配置文件的 ‘markers’ 部分注册的标记会引发错误。
- –strict （已弃用）–strict-markers 的别名。
- -c FILE, --config-file=FILE 从 ‘FILE’ 加载配置，而不是尝试查找隐式配置文件之一。
- –continue-on-collection-errors 即使发生收集错误也要强制执行测试。
- –rootdir=ROOTDIR 定义测试的根目录。可以是相对路径：‘root_dir’, ‘./root_dir’, ‘root_dir/another_dir/’；绝对路径：‘/home/user/root_dir’; 带变量的路径：‘$HOME/root_dir’。
用例搜集:
- –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 不忽略本地虚拟环境目录中的测试。
- –import-mode={prepend, append, importlib} 导入测试模块和 conftest 文件时，预置/追加到 sys.path。默认值：prepend。
- –doctest-modules 在所有 .py 模块中运行 doctest。
- –doctest-report={none, cdiff, ndiff, udiff, only_first_failure} 选择另一种输出格式用于 doctest 失败时的差异。
- –doctest-glob=pat 匹配 doctest 文件的模式，默认值：test*.txt。
- –doctest-ignore-import-errors 忽略 doctest 收集错误。
- –doctest-continue-on-failure 对于给定的 doctest，在第一次失败后继续运行
测试会话调试和配置：
- –basetemp=dir 本次测试运行的基本临时目录。（警告：如果该目录存在，它将被删除。）
- -V, --version 显示 pytest 版本和插件信息。当给出两次时，还显示有关插件的信息。
- -h, --help 显示帮助消息和配置信息。
- -p name 提前加载给定的插件模块名称或入口点（允许多个）。要避免加载插件，请使用“no:”前缀，例如“no:doctest”。
- –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”（默认）在导入时重写测试模块中的断言语句以提供断言语句信息。
- –setup-only 仅设置 fixture，不执行测试。
- –setup-show 在执行测试时显示 fixture 的设置。
- –setup-plan 显示将要执行的 fixture 和测试，但不执行任何操作。
日志记录：
- –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 CLI 使用的日志格式。
- –log-cli-date-format=LOG_CLI_DATE_FORMAT CLI 使用的日志日期格式。
- –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 通过名称禁用日志记录器。可以多次传递。
[pytest] ini-options 在第一个找到的 pytest.ini|tox.ini|setup.cfg|pyproject.toml 配置文件中：
- markers (linelist): 注册新的测试函数标记。
- empty_parameter_set_mark (string): 空参数集的默认标记。
- norecursedirs (args): 避免递归的目录模式。
- testpaths (args): 当命令行未提供文件或目录时，搜索测试的目录。
- filterwarnings (linelist): 每一行指定一个警告过滤模式。在 -W/–pythonwarnings 处理之后处理。
- consider_namespace_packages (bool): 导入时解析模块名时考虑命名空间包。
- usefixtures (args): 与此项目一起使用的默认 fixture 列表。
- python_files (args): Python 测试模块发现的 glob 样式文件模式。
- python_classes (args): Python 测试类发现的前缀或 glob 名称。
- python_functions (args): Python 测试函数和方法发现的前缀或 glob 名称。
- 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’ fixture 创建的哪些目录。（all/failed/none）
- enable_assertion_pass_hook (bool): 启用 pytest_assertion_pass 钩子。确保删除任何先前生成的 pyc 缓存文件。
- 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): 发出 XML 的模式：legacy|xunit1|xunit2
- doctest_option_flags (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 的默认值
- pythonpath (paths): 将路径添加到 sys.path
- fault_handler_timeout (string): 如果测试超过 TIMEOUT 秒未完成，则转储所有线程的堆栈跟踪
- addopts (args): 额外的命令行选项
- minversion (string): 最低所需的 pytest 版本
- required_plugins (args): 必须存在的插件，pytest 才能运行
环境变量：
- CI: 当设置（无论值为何），pytest 知道它正在 CI 进程中运行，并且不会截断摘要信息
- BUILD_NUMBER: 等同于 CI
- PYTEST_ADDOPTS: 额外的命令行选项
- PYTEST_PLUGINS: 逗号分隔的启动时要加载的插件
- PYTEST_DISABLE_PLUGIN_AUTOLOAD: 设置为禁用插件自动加载
- PYTEST_DEBUG: 设置为启用 pytest 内部的调试跟踪

要查看可用标记，请输入：pytest --markers

要查看可用 fixture，请输入：pytest --fixtures（根据指定的文件或目录显示，如果未指定则显示当前目录；以 ‘_’ 开头的 fixture 只在使用 ‘-v’ 选项时显示）