API 参考

此页面包含 pytest API 的完整参考。

常量

pytest.__version__

当前 pytest 版本，以字符串形式表示

>>> import pytest
>>> pytest.__version__
'7.0.0'

pytest.version_tuple

7.0 版新增。

当前 pytest 版本，以元组形式表示

>>> import pytest
>>> pytest.version_tuple
(7, 0, 0)

对于预发布版本，最后一个组件将是一个包含预发布版本的字符串

>>> import pytest
>>> pytest.version_tuple
(7, 0, '0rc1')

函数

pytest.approx

approx(expected, rel=None, abs=None, nan_ok=False)

断言两个数字（或两个有序的数字序列）在一定容差范围内彼此相等。

由于 浮点数运算：问题和限制，我们直观上期望相等的数字并不总是相等

>>> 0.1 + 0.2 == 0.3
False

这个问题在编写测试时经常遇到，例如，在确保浮点值符合预期时。解决此问题的一种方法是断言两个浮点数在某个适当的容差范围内相等

>>> abs((0.1 + 0.2) - 0.3) < 1e-6
True

但是，像上面这样的比较写起来很乏味，而且难以理解。此外，通常不鼓励进行像上面那样的绝对比较，因为没有一种容差适用于所有情况。 1e-6 适用于接近 1 的数字，但对于非常大的数字来说太小，对于非常小的数字来说太大。最好将容差表示为预期值的一部分，但像这样的相对比较更难正确简洁地编写。

approx 类使用尽可能直观的语法执行浮点比较

>>> from pytest import approx
>>> 0.1 + 0.2 == approx(0.3)
True

相同的语法也适用于有序的数字序列

>>> (0.1 + 0.2, 0.2 + 0.4) == approx((0.3, 0.6))
True

numpy 数组

>>> import numpy as np                                                          
>>> np.array([0.1, 0.2]) + np.array([0.2, 0.4]) == approx(np.array([0.3, 0.6])) 
True

以及用于比较 numpy 数组与标量的情况

>>> import numpy as np                                         
>>> np.array([0.1, 0.2]) + np.array([0.2, 0.1]) == approx(0.3) 
True

仅支持有序序列，因为 approx 需要明确推断序列的相对位置。这意味着不支持 sets 和其他无序序列。

最后，还可以比较字典的*值*

>>> {'a': 0.1 + 0.2, 'b': 0.2 + 0.4} == approx({'a': 0.3, 'b': 0.6})
True

如果两个映射具有相同的键，并且它们各自的值符合预期的容差，则比较结果为真。

容差

默认情况下，approx 将预期值的 1e-6（即百万分之一）内的数字视为相等。如果预期值为 0.0，这种处理方式会导致令人惊讶的结果，因为除了 0.0 本身之外，没有任何数字相对接近 0.0。为了更合理地处理这种情况，approx 还将预期值的 1e-12 内的数字视为相等。无穷大和 NaN 是特殊情况。无论相对容差如何，无穷大只被认为等于自身。默认情况下，NaN 不被认为与任何值相等，但您可以通过将 nan_ok 参数设置为 True 来使其等于自身。（这是为了方便比较使用 NaN 表示“无数据”的数组。）

可以通过将参数传递给 approx 构造函数来更改相对容差和绝对容差

>>> 1.0001 == approx(1)
False
>>> 1.0001 == approx(1, rel=1e-3)
True
>>> 1.0001 == approx(1, abs=1e-3)
True

如果指定 abs 而不是 rel，则比较将完全不考虑相对容差。换句话说，如果两个数字超过指定的绝对容差，即使它们在默认的 1e-6 相对容差内，它们仍将被视为不相等。如果同时指定 abs 和 rel，则只要满足任何一个容差，这些数字就会被视为相等

>>> 1 + 1e-8 == approx(1)
True
>>> 1 + 1e-8 == approx(1, abs=1e-12)
False
>>> 1 + 1e-8 == approx(1, rel=1e-6, abs=1e-12)
True

您还可以使用 approx 来比较非数字类型，或者包含非数字类型的字典和序列，在这种情况下，它会退回到严格相等。这对于比较可以包含可选值的字典和序列非常有用

>>> {"required": 1.0000005, "optional": None} == approx({"required": 1, "optional": None})
True
>>> [None, 1.0000005] == approx([None,1])
True
>>> ["foo", 1.0000005] == approx([None,1])
False

如果您正在考虑使用 approx，那么您可能想知道它与其他比较浮点数的好方法相比如何。所有这些算法都基于相对容差和绝对容差，并且在大多数情况下应该是一致的，但它们确实存在一些有意义的差异

• math.isclose(a, b, rel_tol=1e-9, abs_tol=0.0)：如果相对于 a 或 b 满足相对容差，或者满足绝对容差，则为 True。因为相对容差是相对于 a 和 b 计算的，所以此测试是对称的（即 a 和 b 都不是“参考值”）。如果要与 0.0 进行比较，则必须指定绝对容差，因为默认情况下没有容差。更多信息：math.isclose()。

• numpy.isclose(a, b, rtol=1e-5, atol=1e-8)：如果 a 和 b 之间的差小于相对于 b 的相对容差和绝对容差之和，则为 True。因为相对容差仅相对于 b 计算，所以此测试是不对称的，您可以将 b 视为参考值。 numpy.allclose() 提供了对比较序列的支持。更多信息：numpy.isclose。

• unittest.TestCase.assertAlmostEqual(a, b)：如果 a 和 b 在 1e-7 的绝对容差范围内，则为 True。不考虑相对容差，因此此函数不适用于非常大或非常小的数字。此外，它仅在 unittest.TestCase 的子类中可用，并且它很丑陋，因为它不遵循 PEP8。更多信息：unittest.TestCase.assertAlmostEqual()。

• a == pytest.approx(b, rel=1e-6, abs=1e-12)：如果满足相对于 b 的相对容差或满足绝对容差，则为 True。因为相对容差仅针对 b 计算，所以此测试是不对称的，您可以将 b 视为参考值。在您明确指定绝对容差但未指定相对容差的特殊情况下，仅考虑绝对容差。

注意

approx 可以处理 numpy 数组，但如果您需要比较、NaN 或基于 ULP 的容差的支持，我们建议使用 测试支持 (numpy.testing) 中的专用测试助手。

要使用正则表达式匹配字符串，可以使用 Matches（来自 re_assert 包）。

警告

在 3.2 版中已更改。

为了避免不一致的行为，>、>=、< 和 <= 比较会引发 TypeError。下面的示例说明了该问题

assert approx(0.1) > 0.1 + 1e-10  # calls approx(0.1).__gt__(0.1 + 1e-10)
assert 0.1 + 1e-10 > approx(0.1)  # calls approx(0.1).__lt__(0.1 + 1e-10)

在第二个示例中，预期会调用 approx(0.1).__le__(0.1 + 1e-10)。但实际上，使用 approx(0.1).__lt__(0.1 + 1e-10) 进行比较。这是因为丰富比较的调用层次结构遵循固定的行为。更多信息：object.__ge__()

在 3.7.1 版中已更改：当 approx 遇到非数字类型的字典值或序列元素时，会引发 TypeError。

在 6.1.0 版中已更改：approx 对于非数字类型回退到严格相等，而不是引发 TypeError。

pytest.fail

教程：如何使用 skip 和 xfail 处理无法成功的测试

fail(reason[, pytrace=True, msg=None])

使用给定的消息明确使正在执行的测试失败。

参数：

• reason (str) – 向用户显示的消息，作为失败的原因。

• pytrace (bool) – 如果为 False，则 msg 表示完整的失败信息，并且不会报告 python 回溯。

pytest.skip

skip(reason[, allow_module_level=False, msg=None])

使用给定的消息跳过正在执行的测试。

此函数只能在测试期间（设置、调用或拆卸）或在收集期间使用 allow_module_level 标志调用。此函数也可以在 doctest 中调用。

参数：

• reason (str) – 向用户显示的消息，作为跳过的原因。

• allow_module_level (bool) –

  允许在模块级别调用此函数。在模块级别引发跳过异常将停止模块的执行，并阻止收集模块中的所有测试，即使是 skip 调用之前定义的测试。

  默认为 False。

注意

最好尽可能使用 pytest.mark.skipif 标记来声明在某些条件下（如平台或依赖项不匹配）跳过测试。类似地，使用 # doctest: +SKIP 指令（请参阅 doctest.SKIP）静态跳过 doctest。

pytest.importorskip

importorskip(modname, minversion=None, reason=None, *, exc_type=None)

导入并返回请求的模块 modname，如果无法导入该模块，则跳过当前测试。

参数：

• modname (str) – 要导入的模块的名称。

• minversion (str | None) – 如果给出，则导入的模块的 __version__ 属性必须至少是此最小版本，否则测试仍将被跳过。

• reason (str | None) – 如果给出，则在无法导入模块时，将显示此原因作为消息。

• exc_type (Type[ImportError] | None) –

  为了跳过模块而应捕获的异常。必须是 ImportError 或子类。

  如果可以导入模块但引发了 ImportError，pytest 将向用户发出警告，因为用户通常希望找不到该模块（这将引发 ModuleNotFoundError）。

  可以通过显式传递 exc_type=ImportError 来抑制此警告。

  有关详细信息，请参阅 pytest.importorskip 关于 ImportError 的默认行为。

返回值：

导入的模块。这应该分配给它的规范名称。

返回类型：

任何

例子

docutils = pytest.importorskip("docutils")

8.2 版新增： exc_type 参数。

pytest.xfail

xfail(reason='')

使用给定的原因强制 xfail 执行中的测试或设置函数。

此函数应仅在测试期间调用（设置、调用或拆卸）。

使用 xfail() 后不会执行其他代码（它通过引发异常在内部实现）。

参数：

reason (str) – 向用户显示为 xfail 原因的消息。

注意

最好尽可能使用 pytest.mark.xfail 标记来声明在某些条件下（如已知错误或缺少功能）要 xfail 的测试。

pytest.exit

exit(reason[, returncode=None, msg=None])

退出测试过程。

参数：

• reason (str) – 显示为退出 pytest 原因的消息。reason 具有默认值，只是因为 msg 已弃用。

• returncode (int | None) – 退出 pytest 时使用的返回码。None 与 0（无错误）相同，与 sys.exit() 相同。

pytest.main

教程：从 Python 代码调用 pytest

main(args=None, plugins=None)

执行进程内测试运行。

参数：

• args (List[str] | PathLike[str] | None) – 命令行参数列表。如果为 None 或未给出，则默认为直接从进程命令行读取参数 (sys.argv)。

• plugins (Sequence[str | object] | None) – 要在初始化期间自动注册的插件对象列表。

返回值：

退出代码。

返回类型：

int | ExitCode

pytest.param

param(*values[, id][, marks])

在 pytest.mark.parametrize 调用或 参数化夹具 中指定参数。

@pytest.mark.parametrize(
    "test_input,expected",
    [
        ("3+5", 8),
        pytest.param("6*9", 42, marks=pytest.mark.xfail),
    ],
)
def test_eval(test_input, expected):
    assert eval(test_input) == expected

参数：

• values (对象) – 参数集值的变量参数，按顺序排列。

• marks (MarkDecorator | 集合[MarkDecorator | Mark]) – 要应用于此参数集的单个标记或标记列表。

• id (字符串 | 无) – 要归属于此参数集的 ID。

pytest.raises

教程：关于预期异常的断言

with raises(expected_exception: 类型[E] | 元组[类型[E], ...], *, match: 字符串 | 模式[字符串] | 无 = ...) → RaisesContext[E] as excinfo

with raises(expected_exception: Type[E] | Tuple[Type[E], ...], func: Callable[[...], Any], *args: Any, **kwargs: Any) → ExceptionInfo[E] as excinfo

断言代码块/函数调用会引发一个异常类型，或其子类之一。

参数：

• expected_exception – 预期的异常类型，如果预期有多个可能的异常类型，则为元组。请注意，传递的异常的子类也将匹配。

• match (str | re.Pattern[str] | None) –

  如果指定，则为包含正则表达式的字符串或正则表达式对象，使用 re.search() 对其进行测试，以匹配异常的字符串表示形式及其 PEP 678 __notes__。

  要匹配可能包含 特殊字符 的字符串字面量，可以使用 re.escape() 对其进行转义。

  （这仅在 pytest.raises 用作上下文管理器时使用，并在其他情况下传递给函数。当使用 pytest.raises 作为函数时，可以使用：pytest.raises(Exc, func, match="passed on").match("my pattern")。）

使用 pytest.raises 作为上下文管理器，它将捕获给定类型或其任何子类的异常

>>> import pytest
>>> with pytest.raises(ZeroDivisionError):
...    1/0

如果代码块没有引发预期的异常（例如上面的 ZeroDivisionError），或者根本没有引发异常，则检查将失败。

您还可以使用关键字参数 match 来断言异常是否与文本或正则表达式匹配

>>> with pytest.raises(ValueError, match='must be 0 or None'):
...     raise ValueError("value must be 0 or None")

>>> with pytest.raises(ValueError, match=r'must be \d+$'):
...     raise ValueError("value must be 42")

match 参数搜索格式化的异常字符串，其中包括任何 PEP-678 __notes__

>>> with pytest.raises(ValueError, match=r"had a note added"):  
...     e = ValueError("value must be 42")
...     e.add_note("had a note added")
...     raise e

上下文管理器生成一个 ExceptionInfo 对象，可用于检查捕获到的异常的详细信息

>>> with pytest.raises(ValueError) as exc_info:
...     raise ValueError("value must be 42")
>>> assert exc_info.type is ValueError
>>> assert exc_info.value.args[0] == "value must be 42"

警告

鉴于 pytest.raises 匹配子类，请谨慎使用它来匹配像这样的 Exception

with pytest.raises(Exception):  # Careful, this will catch ANY exception raised.
    some_function()

因为 Exception 是几乎所有异常的基类，所以这很容易隐藏真正的错误，用户编写此代码时期望出现特定异常，但由于重构过程中引入的错误而引发了其他异常。

避免使用 pytest.raises 来捕获 Exception，除非确定确实要捕获任何引发的异常。

注意

将 pytest.raises 用作上下文管理器时，值得注意的是，正常的上下文管理器规则适用，并且引发的异常必须是上下文管理器范围内最后一行。此范围内的后续代码行将不会被执行。例如

>>> value = 15
>>> with pytest.raises(ValueError) as exc_info:
...     if value > 10:
...         raise ValueError("value must be <= 10")
...     assert exc_info.type is ValueError  # This will not execute.

相反，必须采用以下方法（注意范围的差异）

>>> with pytest.raises(ValueError) as exc_info:
...     if value > 10:
...         raise ValueError("value must be <= 10")
...
>>> assert exc_info.type is ValueError

使用 pytest.mark.parametrize

使用 pytest.mark.parametrize 时，可以对测试进行参数化，以便某些运行引发异常而其他运行则不会。

有关示例，请参见 参数化条件引发。

另请参阅

有关更多示例和详细讨论，请参阅 关于预期异常的断言。

旧格式

可以通过传递要调用的 lambda 来指定可调用对象

>>> raises(ZeroDivisionError, lambda: 1/0)
<ExceptionInfo ...>

或者，您可以使用参数指定任意可调用对象

>>> def f(x): return 1/x
...
>>> raises(ZeroDivisionError, f, 0)
<ExceptionInfo ...>
>>> raises(ZeroDivisionError, f, x=0)
<ExceptionInfo ...>

以上格式完全受支持，但不建议用于新代码，因为上下文管理器格式被认为更具可读性且不易出错。

注意

与 Python 中捕获的异常对象类似，显式清除对返回的 ExceptionInfo 对象的本地引用可以帮助 Python 解释器加速其垃圾收集。

清除这些引用会破坏引用循环（ExceptionInfo -> 捕获的异常 -> 引发异常的帧堆栈 -> 当前帧堆栈 -> 局部变量 -> ExceptionInfo），这使得 Python 会保留对该循环引用的所有对象（包括当前帧中的所有局部变量），直到下一次循环垃圾收集运行。更多详细信息可以在 Python 官方文档中找到 try 语句。

pytest.deprecated_call

教程：确保代码触发弃用警告

with deprecated_call(*, match: str | Pattern[str] | None = ...) → WarningsRecorder

with deprecated_call(func: Callable[[...], T], *args: Any, **kwargs: Any) → T

断言代码产生 DeprecationWarning 或 PendingDeprecationWarning 或 FutureWarning。

此函数可以用作上下文管理器。

>>> import warnings
>>> def api_call_v2():
...     warnings.warn('use v3 of this api', DeprecationWarning)
...     return 200

>>> import pytest
>>> with pytest.deprecated_call():
...    assert api_call_v2() == 200

它也可以通过传递一个函数以及 *args 和 **kwargs 来使用，在这种情况下，它将确保调用 func(*args, **kwargs) 会产生上述警告类型之一。返回值是函数的返回值。

在上下文管理器形式中，您可以使用关键字参数 match 来断言警告与文本或正则表达式匹配。

上下文管理器生成一个 warnings.WarningMessage 对象列表，每个引发的警告对应一个对象。

pytest.register_assert_rewrite

**教程**：断言重写

register_assert_rewrite(*names)

注册一个或多个要在导入时重写的模块名称。

此函数将确保此模块或包内的所有模块都将重写其断言语句。因此，您应该确保在实际导入模块之前调用它，如果您是使用包的插件，通常在您的 __init__.py 中调用。

参数：

names (str) – 要注册的模块名称。

pytest.warns

**教程**：使用 warns 函数断言警告

with warns(expected_warning: ~typing.Type[Warning] | ~typing.Tuple[~typing.Type[Warning], ...] = <class 'Warning'>, *, match: str | ~typing.Pattern[str] | None = None) → WarningsChecker

with warns(expected_warning: Type[Warning] | Tuple[Type[Warning], ...], func: Callable[[...], T], *args: Any, **kwargs: Any) → T

断言代码会引发特定类型的警告。

具体来说，参数 expected_warning 可以是一个警告类或警告类元组，并且 with 块内的代码必须至少发出一个该类或这些类的警告。

此辅助函数会生成一个 warnings.WarningMessage 对象列表，每个发出的警告对应一个对象（无论它是否是 expected_warning）。从 pytest 8.0 开始，当上下文关闭时，不匹配的警告也会被重新发出。

此函数可以用作上下文管理器。

>>> import pytest
>>> with pytest.warns(RuntimeWarning):
...    warnings.warn("my warning", RuntimeWarning)

在上下文管理器表单中，您可以使用关键字参数 match 来断言警告是否与文本或正则表达式匹配

>>> with pytest.warns(UserWarning, match='must be 0 or None'):
...     warnings.warn("value must be 0 or None", UserWarning)

>>> with pytest.warns(UserWarning, match=r'must be \d+$'):
...     warnings.warn("value must be 42", UserWarning)

>>> with pytest.warns(UserWarning):  # catch re-emitted warning
...     with pytest.warns(UserWarning, match=r'must be \d+$'):
...         warnings.warn("this is not here", UserWarning)
Traceback (most recent call last):
  ...
Failed: DID NOT WARN. No warnings of type ...UserWarning... were emitted...

使用 pytest.mark.parametrize

使用 pytest.mark.parametrize 时，可以对测试进行参数化，以便某些运行会引发警告，而其他运行则不会。

这可以通过与异常相同的方式实现，有关示例，请参阅 参数化条件引发。

pytest.freeze_includes

教程：冻结 pytest

freeze_includes()

返回 pytest 使用的模块名称列表，这些模块名称应包含在 cx_freeze 中。

标记

标记可用于将元数据应用于*测试函数*（但不能应用于 fixture），然后 fixture 或插件可以访问这些元数据。

pytest.mark.filterwarnings

教程：@pytest.mark.filterwarnings

向标记的测试项添加警告过滤器。

pytest.mark.filterwarnings(filter)

参数：

filter (str) –

一个*警告规范字符串*，由 Python 文档的 警告过滤器 部分中指定的元组 (action, message, category, module, lineno) 的内容组成，并以 ":" 分隔。可以省略可选字段。传递用于过滤的模块名称不会进行正则表达式转义。

例如

@pytest.mark.filterwarnings("ignore:.*usage will be deprecated.*:DeprecationWarning")
def test_foo(): ...

pytest.mark.parametrize

教程：如何参数化fixture和测试函数

此标记与 pytest.Metafunc.parametrize() 具有相同的签名；请参见此处。

pytest.mark.skip

教程：跳过测试函数

无条件跳过测试函数。

pytest.mark.skip(reason=None)

参数：

reason (str) – 跳过测试函数的原因。

pytest.mark.skipif

教程：跳过测试函数

如果条件为 True，则跳过测试函数。

pytest.mark.skipif(condition, *, reason=None)

参数：

• condition (bool 或 str) – 如果应跳过条件，则为 True/False，或者为 条件字符串。

• reason (str) – 跳过测试函数的原因。

pytest.mark.usefixtures

教程：在类和模块中使用 usefixtures 使用 fixture

将测试函数标记为使用给定的 fixture 名称。

pytest.mark.usefixtures(*names)

参数：

args – 要使用的 fixture 的名称，以字符串形式提供。

注意

在钩子中使用 usefixtures 时，它只能在测试设置之前应用于测试函数时加载 fixture（例如，在 pytest_collection_modifyitems 钩子中）。

另请注意，此标记在应用于fixture时无效。

pytest.mark.xfail

教程：XFail：将测试函数标记为预期失败

将测试函数标记为预期失败。

pytest.mark.xfail(condition=False, *, reason=None, raises=None, run=True, strict=xfail_strict)

参数：

• condition (Union[bool, str]) – 将测试函数标记为 xfail 的条件（True/False 或 条件字符串）。如果是 bool，则还必须指定 reason（请参阅 条件字符串）。

• reason (str) – 将测试函数标记为 xfail 的原因。

• raises (Type[Exception]) – 预计由测试函数引发的异常类（或类元组）；其他异常将导致测试失败。请注意，传递的类的子类也将导致匹配（类似于 except 语句的工作方式）。

• run (bool) – 是否应实际执行测试函数。如果为 False，则该函数将始终 xfail 并且不会被执行（如果函数出现段错误，则此选项很有用）。

• strict (bool) –

  • 如果为 False，则如果函数失败，则在终端输出中显示为 xfailed，如果通过，则显示为 xpass。在这两种情况下，这都不会导致整个测试套件失败。这对于标记以后要处理的*不稳定*测试（随机失败的测试）特别有用。

  • 如果为 True，则如果函数失败，则在终端输出中显示为 xfailed，但如果意外通过，则将导致测试套件**失败**。这对于标记始终失败的函数特别有用，并且如果它们意外开始通过（例如，库的新版本修复了已知错误），则应该有明确的指示。

  默认为 xfail_strict，默认值为 False。

自定义标记

使用工厂对象 pytest.mark 动态创建标记，并将其作为装饰器应用。

例如

@pytest.mark.timeout(10, "slow", method="thread")
def test_function(): ...

将创建 Mark 对象并将其附加到收集的 Item，然后可以使用 Node.iter_markers 由 fixture 或钩子访问。 mark 对象将具有以下属性

mark.args == (10, "slow")
mark.kwargs == {"method": "thread"}

使用多个自定义标记的示例

@pytest.mark.timeout(10, "slow", method="thread")
@pytest.mark.slow
def test_function(): ...

当 Node.iter_markers 或 Node.iter_markers_with_node 与多个标记一起使用时，将首先迭代最靠近函数的标记。上面的示例将导致 @pytest.mark.slow，然后是 @pytest.mark.timeout(...)。

Fixtures

教程：Fixtures 参考

测试函数或其他 fixture 可以通过将 fixture 声明为参数名称来请求它们。

需要 fixture 的测试示例

def test_output(capsys):
    print("hello")
    out, err = capsys.readouterr()
    assert out == "hello\n"

需要另一个 fixture 的 fixture 示例

@pytest.fixture
def db_session(tmp_path):
    fn = tmp_path / "db.file"
    return connect(fn)

有关更多详细信息，请参阅完整的 fixtures 文档。

@pytest.fixture

@fixture(fixture_function: FixtureFunction, *, scope: Literal['session', 'package', 'module', 'class', 'function'] | Callable[[str, Config], Literal['session', 'package', 'module', 'class', 'function']] = 'function', params: Iterable[object] | None = None, autouse: bool = False, ids: Sequence[object | None] | Callable[[Any], object | None] | None = None, name: str | None = None) → FixtureFunction

@fixture(fixture_function: None = None, *, scope: Literal['session', 'package', 'module', 'class', 'function'] | Callable[[str, Config], Literal['session', 'package', 'module', 'class', 'function']] = 'function', params: Iterable[object] | None = None, autouse: bool = False, ids: Sequence[object | None] | Callable[[Any], object | None] | None = None, name: str | None = None) → FixtureFunctionMarker

用于标记 fixture 工厂函数的装饰器。

此装饰器可以使用或不使用参数来定义 fixture 函数。

稍后可以引用 fixture 函数的名称，以便在运行测试之前调用它：测试模块或类可以使用 pytest.mark.usefixtures(fixturename) 标记。

测试函数可以直接使用 fixture 名称作为输入参数，在这种情况下，将注入从 fixture 函数返回的 fixture 实例。

Fixtures 可以使用 return 或 yield 语句向测试函数提供其值。当使用 yield 时，无论测试结果如何，yield 语句之后的代码块都将作为拆卸代码执行，并且必须且仅 yield 一次。

参数：

• scope –

  此 fixture 共享的范围；可以是 "function"（默认）、"class"、"module"、"package" 或 "session" 之一。

  此参数也可以是可调用对象，它接收 (fixture_name, config) 作为参数，并且必须返回包含上述值之一的 str。

  有关更多信息，请参阅文档中的 动态范围。

• params – 可选的参数列表，这些参数将导致多次调用 fixture 函数以及使用它的所有测试。当前参数在 request.param 中可用。

• autouse – 如果为 True，则会为所有可以看到它的测试激活 fixture 函数。如果为 False（默认值），则需要显式引用才能激活 fixture。

• ids – 与每个参数相对应的 id 序列，以便它们成为测试 id 的一部分。如果没有提供 id，则将根据参数自动生成它们。

• name – fixture 的名称。默认为装饰函数的名称。如果在定义 fixture 的同一个模块中使用 fixture，则 fixture 的函数名称将被请求 fixture 的函数参数遮蔽；解决此问题的一种方法是将装饰函数命名为 fixture_<fixturename>，然后使用 @pytest.fixture(name='<fixturename>')。

capfd

教程：如何捕获 stdout/stderr 输出

capfd()

启用对文件描述符 1 和 2 的写入进行文本捕获。

捕获的输出可通过 capfd.readouterr() 方法调用获得，该方法返回一个 (out, err) 命名元组。out 和 err 将是 text 对象。

返回 CaptureFixture[str] 的实例。

示例：.. code-block:: python

def test_system_echo(capfd)

os.system(‘echo “hello”’) captured = capfd.readouterr() assert captured.out == “hellon”

capfdbinary

教程：如何捕获 stdout/stderr 输出

capfdbinary()

启用对文件描述符 1 和 2 的写入进行字节捕获。

捕获的输出可通过 capfd.readouterr() 方法调用获得，该方法返回一个 (out, err) 命名元组。 out 和 err 将是 byte 对象。

返回 CaptureFixture[bytes] 的实例。

示例：.. code-block:: python

def test_system_echo(capfdbinary)

os.system(‘echo “hello”’) captured = capfdbinary.readouterr() assert captured.out == b”hellon”

caplog

**教程**：如何管理日志记录

caplog()

访问和控制日志捕获。

捕获的日志可通过以下属性/方法获得

* caplog.messages        -> list of format-interpolated log messages
* caplog.text            -> string containing formatted log output
* caplog.records         -> list of logging.LogRecord instances
* caplog.record_tuples   -> list of (logger_name, level, message) tuples
* caplog.clear()         -> clear captured records and formatted log output string

返回一个 pytest.LogCaptureFixture 实例。

final class LogCaptureFixture

提供对日志捕获的访问和控制。

property handler: LogCaptureHandler

获取装置使用的日志处理程序。

get_records(when)

获取某个可能测试阶段的日志记录。

参数：

**when** (Literal['setup', 'call', 'teardown']) – 要从中获取记录的测试阶段。有效值为：“setup”、“call”和“teardown”。

返回值：

给定阶段捕获的记录列表。

返回类型：

List[LogRecord]

3.4 版新增。

property text: str

格式化的日志文本。

property records: List[LogRecord]

日志记录列表。

property record_tuples: List[Tuple[str, int, str]]

用于断言比较的精简版日志记录列表。

元组的格式为

(logger_name, log_level, message)

property messages: List[str]

格式插值后的日志消息列表。

与包含格式字符串和插值参数的“records”不同，此列表中的日志消息都已插值。

与包含处理程序输出的“text”不同，此列表中的日志消息没有级别、时间戳等修饰，使得精确比较更加可靠。

请注意，不包括回溯或堆栈信息（来自 logging.exception() 或传递给日志记录函数的 exc_info 或 stack_info 参数），因为这是由处理程序中的格式化程序添加的。

3.7 版新增。

clear()

重置日志记录列表和捕获的日志文本。

set_level(level, logger=None)

在测试期间设置记录器的阈值级别。

严重程度低于此级别的日志消息将不会被捕获。

在 3.4 版更改: 此函数更改的记录器级别将在测试结束时恢复为其初始值。

如果通过 logging.disable() 禁用了请求的日志记录级别，则将启用该级别。

参数：

• level (int | str) – 级别。

• logger (str | None) – 要更新的记录器。如果未给出，则为根记录器。

with at_level(level, logger=None)

上下文管理器，用于设置捕获日志的级别。“with”语句结束后，级别将恢复为其原始值。

如果通过 logging.disable() 禁用了请求的日志记录级别，则将启用该级别。

参数：

• level (int | str) – 级别。

• logger (str | None) – 要更新的记录器。如果未给出，则为根记录器。

with filtering(filter_)

上下文管理器，用于在“with”语句块期间将给定过滤器临时添加到 caplog 的 handler()，并在块结束时删除该过滤器。

参数：

filter – 自定义 logging.Filter 对象。

7.5 版新增。

capsys

教程：如何捕获 stdout/stderr 输出

capsys()

启用对写入 sys.stdout 和 sys.stderr 的文本捕获。

捕获的输出可通过 capsys.readouterr() 方法调用获得，该方法返回一个 (out, err) 命名元组。out 和 err 将是 text 对象。

返回 CaptureFixture[str] 的实例。

示例：.. code-block:: python

def test_output(capsys):

print("hello") captured = capsys.readouterr() assert captured.out == "hellon"

class CaptureFixture

capsys、capsysbinary、capfd 和 capfdbinary fixture 返回的对象。

readouterr()

读取并返回到目前为止捕获的输出，重置内部缓冲区。

返回值：

捕获的内容是一个命名元组，具有 out 和 err 字符串属性。

返回类型：

CaptureResult

with disabled()

在 with 块内暂时禁用捕获。

capsysbinary

教程：如何捕获 stdout/stderr 输出

capsysbinary()

启用对 sys.stdout 和 sys.stderr 的写入的字节捕获。

捕获的输出可以通过 capsysbinary.readouterr() 方法调用获得，该方法返回一个 (out, err) 命名元组。out 和 err 将是 bytes 对象。

返回 CaptureFixture[bytes] 的实例。

示例：.. code-block:: python

def test_output(capsysbinary):

print("hello") captured = capsysbinary.readouterr() assert captured.out == b"hellon"

config.cache

**教程**：如何重新运行失败的测试并在测试运行之间维护状态

config.cache 对象允许其他插件和 fixture 在测试运行之间存储和检索值。要从 fixture 访问它，请在 fixture 中请求 pytestconfig 并使用 pytestconfig.cache 获取它。

在底层，缓存插件使用 json 标准库模块的简单 dumps/loads API。

config.cache 是 pytest.Cache 的实例

final class Cache

cache fixture 的实例。

mkdir(name)

返回具有给定名称的目录路径对象。

如果该目录尚不存在，则将创建该目录。您可以使用它来管理文件，例如在测试会话之间存储/检索数据库转储。

7.0 版新增。

参数：

name (str) – 必须是不包含 / 分隔符的字符串。确保名称包含您的插件或应用程序标识符，以防止与其他缓存用户发生冲突。

get(key, default)

返回给定键的缓存值。

如果尚未缓存任何值或无法读取该值，则返回指定的默认值。

参数：

• key (str) – 必须是用 / 分隔的值。通常，第一个名称是您的插件或应用程序的名称。

• default – 在缓存未命中或缓存值无效的情况下返回的值。

set(key, value)

保存给定键的值。

参数：

• key (str) – 必须是用 / 分隔的值。通常，第一个名称是您的插件或应用程序的名称。

• value (object) – 必须是任何基本 Python 类型的组合，包括嵌套类型，如字典列表。

doctest_namespace

教程：如何运行 doctest

doctest_namespace()

返回 dict 的夹具，该字典将被注入到 doctest 的命名空间中。

通常，此夹具与另一个 autouse 夹具一起使用

@pytest.fixture(autouse=True)
def add_np(doctest_namespace):
    doctest_namespace["np"] = numpy

有关更多详细信息，请参阅：‘doctest_namespace’ 夹具。

monkeypatch

教程：如何对模块和环境进行猴子补丁/模拟

monkeypatch()

用于猴子补丁的便捷夹具。

该夹具提供了以下方法来修改对象、字典或 os.environ

• monkeypatch.setattr(obj, name, value, raising=True)

• monkeypatch.delattr(obj, name, raising=True)

• monkeypatch.setitem(mapping, name, value)

• monkeypatch.delitem(obj, name, raising=True)

• monkeypatch.setenv(name, value, prepend=None)

• monkeypatch.delenv(name, raising=True)

• monkeypatch.syspath_prepend(path)

• monkeypatch.chdir(path)

• monkeypatch.context()

所有修改将在请求的测试函数或夹具完成后撤消。 raising 参数决定了如果设置/删除操作没有指定目标，是否会引发 KeyError 或 AttributeError。

要撤消夹具在包含范围内所做的修改，请使用 context()。

返回一个 MonkeyPatch 实例。

final class MonkeyPatch

帮助程序，方便地对属性/项/环境变量/系统路径进行猴子补丁。

由 monkeypatch 夹具返回。

在 6.2 版更改: 现在也可以直接用作 pytest.MonkeyPatch()，用于夹具不可用的情况。在这种情况下，请使用 with MonkeyPatch.context() as mp: 或记住显式调用 undo()。

classmethod with context()

上下文管理器，返回一个新的 MonkeyPatch 对象，该对象在退出时撤消在 with 块内完成的任何修补。

示例：.. code-block:: python

import functools

def test_partial(monkeypatch)

with monkeypatch.context() as m

m.setattr(functools, “partial”, 3)

在希望在测试结束之前撤消某些补丁的情况下很有用，例如模拟 stdlib 函数，如果模拟这些函数可能会破坏 pytest 本身（有关示例，请参见 问题 #3290）。

setattr(target: str, name: object, value: ~_pytest.monkeypatch.Notset = <notset>, raising: bool = True) → None

setattr(target: object, name: str, value: object, raising: bool = True) → None

设置目标上的属性值，记住旧值。

例如

import os

monkeypatch.setattr(os, "getcwd", lambda: "/")

上面的代码用一个总是返回 "/" 的 lambda 替换了 os.getcwd() 函数。

为了方便起见，您可以指定一个字符串作为 target，它将被解释为一个点分隔的导入路径，最后一部分是属性名称。

monkeypatch.setattr("os.getcwd", lambda: "/")

如果属性不存在，则引发 AttributeError，除非 raising 设置为 False。

在哪里打补丁

monkeypatch.setattr 的工作原理是（临时）将名称指向的对象更改为另一个对象。可以有多个名称指向任何单个对象，因此要使修补工作，您必须确保修补了被测系统使用的名称。

有关完整说明，请参阅 unittest.mock 文档中的 在哪里打补丁 部分，该部分适用于 unittest.mock.patch()，但也适用于 monkeypatch.setattr。

delattr(target, name=<notset>, raising=True)

从 target 中删除属性 name。

如果没有指定 name 并且 target 是一个字符串，它将被解释为一个点分隔的导入路径，最后一部分是属性名称。

如果属性不存在，则引发 AttributeError，除非 raising 设置为 False。

setitem(dic, name, value)

将字典条目 name 设置为值。

delitem(dic, name, raising=True)

从字典中删除 name。

如果它不存在，则引发 KeyError，除非 raising 设置为 False。

setenv(name, value, prepend=None)

将环境变量 name 设置为 value。

如果 prepend 是一个字符，则读取当前环境变量值，并在其前面加上 value 和 prepend 字符。

delenv(name, raising=True)

从环境中删除 name。

如果它不存在，则引发 KeyError，除非 raising 设置为 False。

syspath_prepend(path)

将 path 添加到 sys.path 导入位置列表的开头。

chdir(path)

将当前工作目录更改为指定的路径。

参数：

path (str | PathLike[str]) – 要切换到的路径。

undo()

撤消之前的更改。

此调用会清空撤消堆栈。再次调用它没有任何效果，除非在撤消调用之后进行更多 monkeypatching 操作。

通常不需要调用 undo()，因为它会在拆卸期间自动调用。

注意

同一个 monkeypatch fixture 会在单个测试函数调用中使用。如果测试函数本身和其中一个测试 fixture 都使用了 monkeypatch，则调用 undo() 将撤消这两个函数中所做的所有更改。

建议改用 context()。

pytestconfig

pytestconfig()

会话范围的 fixture，返回会话的 pytest.Config 对象。

例子

def test_foo(pytestconfig):
    if pytestconfig.getoption("verbose") > 0:
        ...

pytester

6.2 版新增。

提供了一个 Pytester 实例，可用于运行和测试 pytest 本身。

它提供了一个空目录，pytest 可以在其中隔离执行，并且包含编写测试、配置文件和匹配预期输出的功能。

要使用它，请在你的最顶层 conftest.py 文件中包含

pytest_plugins = "pytester"

final class Pytester

用于编写测试/配置文件、在隔离环境中执行 pytest 并与预期输出进行匹配的工具，非常适合对 pytest 插件进行黑盒测试。

它试图尽可能地将测试运行与外部因素隔离，并在初始化期间将当前工作目录修改为 path 和环境变量。

exception TimeoutExpired

plugins: List[str | object]

要与 parseconfig() 和 runpytest() 一起使用的插件列表。最初这是一个空列表，但可以将插件添加到列表中。要添加到列表中的项目的类型取决于使用它们的方法，因此请参阅它们以获取详细信息。

property path: Path

用于创建文件/运行测试等的临时目录路径。

make_hook_recorder(pluginmanager)

为 PytestPluginManager 创建一个新的 HookRecorder。

chdir()

使用 cd 命令进入临时目录。

这在实例化时自动完成。

makefile(ext, *args, **kwargs)

在测试目录中创建新的文本文件。

参数：

• ext (str) – 文件应使用的扩展名，包括点，例如 .py。

• args (str) – 所有 args 都被视为字符串并使用换行符连接。结果将作为内容写入文件。文件名基于请求此夹具的测试函数。

• kwargs (str) – 每个关键字都是一个文件名，而它的值将作为文件的内容写入。

返回值：

第一个创建的文件。

返回类型：

路径

示例： .. code-block:: python

pytester.makefile(“.txt”, “line1”, “line2”)

pytester.makefile(“.ini”, pytest=”[pytest]naddopts=-rsn”)

要创建二进制文件，请直接使用 pathlib.Path.write_bytes()

filename = pytester.path.joinpath("foo.bin")
filename.write_bytes(b"...")

makeconftest(source)

写入一个 conftest.py 文件。

参数：

source (str) – 文件内容。

返回值：

conftest.py 文件。

返回类型：

路径

makeini(source)

写入一个 tox.ini 文件。

参数：

source (str) – 文件内容。

返回值：

tox.ini 文件。

返回类型：

路径

getinicfg(source)

返回 tox.ini 配置文件中的 pytest 部分。

makepyprojecttoml(source)

写入一个 pyproject.toml 文件。

参数：

source (str) – 文件内容。

返回值：

pyproject.ini 文件。

返回类型：

路径

6.0 版本新增。

makepyfile(*args, **kwargs)

使用 .py 扩展名创建文件的快捷方式。

默认为带有“.py”扩展名的测试名称，例如 test_foobar.py，会覆盖现有文件。

示例： .. code-block:: python

def test_something(pytester)

# 初始文件名为 test_something.py。 pytester.makepyfile("foobar") # 要创建多个文件，请相应地传递 kwargs。 pytester.makepyfile(custom="foobar") # 此时，测试目录中同时存在“test_something.py”和“custom.py”。

maketxtfile(*args, **kwargs)

使用 .txt 扩展名创建文件的快捷方式。

默认为带有“.txt”扩展名的测试名称，例如 test_foobar.txt，会覆盖现有文件。

示例： .. code-block:: python

def test_something(pytester)

# 初始文件名为 test_something.txt。 pytester.maketxtfile("foobar") # 要创建多个文件，请相应地传递 kwargs。 pytester.maketxtfile(custom="foobar") # 此时，测试目录中同时存在“test_something.txt”和“custom.txt”。

syspathinsert(path=None)

将目录添加到 sys.path 的开头，默认为 path。

当此对象在每次测试结束时失效时，这将自动撤消。

参数：

path (str | PathLike[str] | None) – 路径。

mkdir(name)

创建一个新的（子）目录。

参数：

name (str | PathLike[str]) – 目录的名称，相对于 pytester 路径。

返回值：

创建的目录。

返回类型：

路径

mkpydir(name)

创建一个新的 Python 包。

这将创建一个包含空 __init__.py 文件的（子）目录，以便将其识别为 Python 包。

copy_example(name=None)

将文件从项目的目录复制到 testdir。

参数：

name (str | None) – 要复制的文件的名称。

返回值：

复制目录的路径（在 self.path 内）。

返回类型：

路径

getnode(config, arg)

获取文件的集合节点。

参数：

• config (Config) – pytest 配置。请参阅 parseconfig() 和 parseconfigure() 以了解如何创建它。

• arg (str | PathLike[str]) – 文件的路径。

返回值：

节点。

返回类型：

Collector | Item

getpathnode(path)

返回文件的集合节点。

这类似于 getnode()，但使用 parseconfigure() 来创建（已配置的）pytest Config 实例。

参数：

path (str | PathLike[str]) – 文件的路径。

返回值：

节点。

返回类型：

Collector | Item

genitems(colitems)

从集合节点生成所有测试项。

这将递归到集合节点并返回其中包含的所有测试项的列表。

参数：

colitems (序列[项 | 收集器]) – 集合节点。

返回值：

收集到的项目。

返回类型：

列表[项]

runitem(source)

运行“test_func”项。

调用的测试实例（包含测试方法的类）必须提供一个 .getrunner() 方法，该方法应返回一个可以为单个项运行测试协议的运行器，例如 _pytest.runner.runtestprotocol。

inline_runsource(source, *cmdlineargs)

使用 pytest.main() 在进程中运行测试模块。

此运行将“source”写入临时文件并对其运行 pytest.main()，返回一个 HookRecorder 实例作为结果。

参数：

• source (字符串) – 测试模块的源代码。

• cmdlineargs – 要使用的任何额外的命令行参数。

inline_genitems(*args)

在进程中运行 pytest.main(['--collect-only'])。

运行 pytest.main() 函数以在测试进程本身内部运行所有 pytest，如 inline_run()，但返回收集到的项的元组和 HookRecorder 实例。

inline_run(*args, plugins=(), no_reraise_ctrlc=False)

在进程中运行 pytest.main()，返回一个 HookRecorder。

运行 pytest.main() 函数以在测试进程本身内部运行所有 pytest。这意味着它可以返回一个 HookRecorder 实例，该实例提供比通过匹配 runpytest() 的 stdout/stderr 更详细的结果。

参数：

• args (str | PathLike[str]) – 要传递给 pytest.main() 的命令行参数。

• plugins – pytest.main() 实例应使用的额外插件实例。

• no_reraise_ctrlc (bool) – 通常我们从子运行中重新引发键盘中断。如果为 True，则捕获 KeyboardInterrupt 异常。

runpytest_inprocess(*args, **kwargs)

返回在进程中运行 pytest 的结果，提供与 self.runpytest() 提供的接口类似的接口。

runpytest(*args, **kwargs)

根据命令行选项“–runpytest”在内联或子进程中运行 pytest，并返回一个 RunResult。

parseconfig(*args)

从给定的命令行参数返回一个新的 pytest pytest.Config 实例。

这将调用 _pytest.config 中的 pytest 引导代码来创建一个新的 pytest.PytestPluginManager 并调用 pytest_cmdline_parse 钩子来创建一个新的 pytest.Config 实例。

如果 plugins 已被填充，则它们应该是要向插件管理器注册的插件模块。

parseconfigure(*args)

返回一个新的 pytest 配置的 Config 实例。

返回一个新的 pytest.Config 实例，如 parseconfig()，但也调用 pytest_configure 钩子。

getitem(source, funcname='test_func')

返回测试函数的测试项。

将源代码写入 Python 文件，并在生成的模块上运行 pytest 的收集，返回请求的函数名称的测试项。

参数：

• source (str | PathLike[str]) – 模块源代码。

• funcname (str) – 要为其返回测试项的测试函数的名称。

返回值：

测试项。

返回类型：

项目

getitems(source)

返回从模块收集的所有测试项。

将源代码写入 Python 文件，并在生成的模块上运行 pytest 的收集，返回其中包含的所有测试项。

getmodulecol(source, configargs=(), *, withinit=False)

返回 source 的模块收集节点。

使用 makepyfile() 将 source 写入文件，然后在其上运行 pytest 收集，返回测试模块的收集节点。

参数：

• source (str | PathLike[str]) – 要收集的模块的源代码。

• configargs – 要传递给 parseconfigure() 的任何额外参数。

• withinit (bool) – 是否还要将 __init__.py 文件写入同一目录以确保它是一个包。

collect_by_name(modcol, name)

返回模块集合中名称的收集节点。

在模块收集节点中搜索与给定名称匹配的收集节点。

参数：

• modcol (Collector) – 模块收集节点；参见 getmodulecol()。

• name (str) – 要返回的节点的名称。

popen(cmdargs, stdout=-1, stderr=-1, stdin=NotSetType.token, **kw)

调用 subprocess.Popen。

调用 subprocess.Popen，确保当前工作目录位于 PYTHONPATH 中。

您可能想改用 run()。

run(*cmdargs, timeout=None, stdin=NotSetType.token)

使用参数运行命令。

使用 subprocess.Popen 运行进程，保存标准输出和标准错误。

参数：

• cmdargs (str | PathLike[str]) – 要传递给 subprocess.Popen 的参数序列，类路径对象将自动转换为 str。

• timeout (float | None) – 超时并引发 Pytester.TimeoutExpired 的秒数。

• stdin (NotSetType | bytes | IO[Any] | int) –

  可选的标准输入。

  • 如果它是 CLOSE_STDIN（默认），则此方法使用 stdin=subprocess.PIPE 调用 subprocess.Popen，并且在新命令启动后立即关闭标准输入。

  • 如果它是 bytes 类型，则这些字节将发送到命令的标准输入。

  • 否则，它将传递给 subprocess.Popen。有关这种情况下的更多信息，请参阅 subprocess.Popen 中 stdin 参数的文档。

返回值：

结果。

返回类型：

RunResult

runpython(script)

使用 sys.executable 作为解释器运行 Python 脚本。

runpython_c(command)

运行 python -c "command"。

runpytest_subprocess(*args, timeout=None)

使用给定参数将 pytest 作为子进程运行。

添加到 plugins 列表中的任何插件都将使用 -p 命令行选项添加。此外，--basetemp 用于将任何临时文件和目录放在以“runpytest-”为前缀的编号目录中，以避免与临时文件和目录的常规编号 pytest 位置冲突。

参数：

• args (str | PathLike[str]) – 要传递给 pytest 子进程的参数序列。

• timeout (float | None) – 超时并引发 Pytester.TimeoutExpired 的秒数。

返回值：

结果。

返回类型：

RunResult

spawn_pytest(string, expect_timeout=10.0)

使用 pexpect 运行 pytest。

这可以确保使用正确的 pytest 并设置临时目录位置。

返回 pexpect 子进程。

spawn(cmd, expect_timeout=10.0)

使用 pexpect 运行命令。

返回 pexpect 子进程。

final class RunResult

从 Pytester 运行命令的结果。

ret: int | ExitCode

返回值。

outlines

从标准输出捕获的行列表。

errlines

从标准错误捕获的行列表。

stdout

LineMatcher 类型的标准输出。

使用例如 str(stdout) 来重建标准输出，或者常用的 stdout.fnmatch_lines() 方法。

stderr

LineMatcher 类型的标准错误输出。

duration

持续时间，以秒为单位。

parseoutcomes()

通过解析测试进程生成的终端输出，返回一个结果名词 -> 计数的字典。

返回的名词将始终为复数形式

======= 1 failed, 1 passed, 1 warning, 1 error in 0.13s ====

将返回 {"failed": 1, "passed": 1, "warnings": 1, "errors": 1}。

classmethod parse_summary_nouns(lines)

从 pytest 终端摘要行中提取名词。

为了保持一致性，它总是返回复数名词

======= 1 failed, 1 passed, 1 warning, 1 error in 0.13s ====

将返回 {"failed": 1, "passed": 1, "warnings": 1, "errors": 1}。

assert_outcomes(passed=0, skipped=0, failed=0, errors=0, xpassed=0, xfailed=0, warnings=None, deselected=None)

断言指定的测试结果在测试运行的文本输出中以相应的数字出现（0 表示未出现）。

仅当 warnings 和 deselected 不为 None 时才检查它们。

class LineMatcher

灵活的文本匹配。

这是一个方便的类，用于测试像命令输出这样的大文本。

构造函数接受一个不带尾随换行符的行列表，即 text.splitlines()。

__str__()

返回完整的原始文本。

6.2 版新增: 在旧版本中可以使用 str()。

fnmatch_lines_random(lines2)

检查行是否存在于输出中，顺序不限（使用 fnmatch.fnmatch()）。

re_match_lines_random(lines2)

检查行是否存在于输出中，顺序不限（使用 re.match()）。

get_lines_after(fnline)

返回文本中给定行之后的所有行。

给定的行可以包含 glob 通配符。

fnmatch_lines(lines2, *, consecutive=False)

检查行是否存在于输出中（使用 fnmatch.fnmatch()）。

参数是一个行列表，这些行必须匹配并且可以使用 glob 通配符。如果它们不匹配，则调用 pytest.fail()。匹配和不匹配的行也会作为错误消息的一部分显示。

参数：

• lines2 (序列[字符串]) – 要匹配的字符串模式。

• consecutive (布尔值) – 是否连续匹配行？

re_match_lines(lines2, *, consecutive=False)

检查行是否存在于输出中（使用 re.match()）。

参数是一个行列表，这些行必须使用 re.match 进行匹配。如果它们不匹配，则调用 pytest.fail()。

匹配和不匹配的内容也会作为错误信息的一部分显示。

参数：

• lines2 (Sequence[str]) – 要匹配的字符串模式。

• consecutive (bool) – 是否连续匹配行？

no_fnmatch_line(pat)

使用 fnmatch.fnmatch 确保捕获的行与给定模式不匹配。

参数：

pat (str) – 用于匹配行的模式。

no_re_match_line(pat)

使用 re.match 确保捕获的行与给定模式不匹配。

参数：

pat (str) – 用于匹配行的正则表达式。

str()

返回完整的原始文本。

final class HookRecorder

记录插件管理器中调用的所有钩子。

钩子记录器由 Pytester 创建。

这将包装插件管理器中的所有钩子调用，在传播正常调用之前记录每个调用。

getcalls(names)

获取对具有给定名称（或名称）的钩子的所有记录调用。

matchreport(inamepart='', names=('pytest_runtest_logreport', 'pytest_collectreport'), when=None)

返回点导入路径匹配的测试报告。

final class RecordedHookCall

对钩子的记录调用。

对钩子调用的参数设置为属性。例如

calls = hook_recorder.getcalls("pytest_runtest_setup")
# Suppose pytest_runtest_setup was called once with `item=an_item`.
assert calls[0].item is an_item

record_property

教程：record_property

record_property()

向调用测试添加额外的属性。

用户属性将成为测试报告的一部分，并可供配置的报告器使用，例如 JUnit XML。

该 fixture 可使用 name, value 调用。该值会自动进行 XML 编码。

例子

def test_function(record_property):
    record_property("example_key", 1)

record_testsuite_property

教程：record_testsuite_property

record_testsuite_property()

将新的 <property> 标签记录为根 <testsuite> 的子级。

这适用于编写有关整个测试套件的全局信息，并且与 xunit2 JUnit 家族兼容。

这是一个 session 级别的 fixture，使用 (name, value) 调用。示例

def test_foo(record_testsuite_property):
    record_testsuite_property("ARCH", "PPC")
    record_testsuite_property("STORAGE_TYPE", "CEPH")

参数：

• name – 属性名称。

• value – 属性值。将转换为字符串。

警告

目前，此 fixture 不适用于 pytest-xdist 插件。有关详细信息，请参阅 问题 #7767。

recwarn

**教程**：使用 warns 函数断言警告

recwarn()

返回一个 WarningsRecorder 实例，该实例记录测试函数发出的所有警告。

有关警告类别的信息，请参阅 https://pytest.pythonlang.cn/en/latest/how-to/capture-warnings.html。

类 WarningsRecorder

一个用于记录引发的警告的上下文管理器。

每个记录的警告都是 warnings.WarningMessage 的实例。

改编自 warnings.catch_warnings。

注意

DeprecationWarning 和 PendingDeprecationWarning 的处理方式不同；请参阅 确保代码触发弃用警告。

属性 list: List[WarningMessage]

记录的警告列表。

pop(cls=<class 'Warning'>)

弹出第一个记录的警告，该警告是 cls 的实例，但不是任何其他匹配项的子类的实例。如果没有匹配项，则引发 AssertionError。

clear()

清除记录的警告列表。

request

示例：根据命令行选项将不同的值传递给测试函数

request fixture 是一种特殊的 fixture，提供请求测试函数的信息。

class FixtureRequest

request fixture 的类型。

request 对象允许访问请求测试上下文，并在 fixture 被参数化的情况下具有 param 属性。

fixturename: Final

正在执行此请求的 fixture。

property scope: Literal['session', 'package', 'module', 'class', 'function']

范围字符串，可以是 “function”、“class”、“module”、“package”、“session” 之一。

property fixturenames: List[str]

此请求中所有活动 fixture 的名称。

abstract property node

底层集合节点（取决于当前请求范围）。

property config: Config

与此请求关联的 pytest 配置对象。

property function

如果请求具有函数级范围，则为测试函数对象。

property cls

收集测试函数的类（可以是 None）。

property instance

收集测试函数的实例（可以是 None）。

property module

收集测试函数的 Python 模块对象。

property path: Path

收集测试函数的路径。

property keywords: MutableMapping[str, Any]

底层节点的关键字/标记字典。

property session: Session

Pytest 会话对象。

abstractmethod addfinalizer(finalizer)

添加终结器/拆卸函数，在请求测试上下文中的最后一个测试完成执行后，将在不带参数的情况下调用该函数。

applymarker(marker)

将标记应用于单个测试函数调用。

如果您不希望所有函数调用都有关键字/标记，则此方法很有用。

参数：

marker (str | MarkDecorator) – 通过调用 pytest.mark.NAME(...) 创建的对象。

raiseerror(msg)

引发 FixtureLookupError 异常。

参数：

msg (str | None) – 可选的自定义错误消息。

getfixturevalue(argname)

动态运行命名的 fixture 函数。

建议尽可能通过函数参数声明 fixture。但是，如果只能在测试设置时决定是否使用另一个 fixture，则可以使用此函数在 fixture 或测试函数体内部检索它。

此方法可以在测试设置阶段或测试运行阶段使用，但在测试拆卸阶段，fixture 的值可能不可用。

参数：

argname (str) – fixture 名称。

引发:

pytest.FixtureLookupError – 如果找不到给定的 fixture。

testdir

与 pytester 相同，但提供了一个实例，该实例的方法在适用时返回传统的 py.path.local 对象。

新代码应避免使用 testdir，而应使用 pytester。

final class Testdir

类似于 Pytester，但此类使用旧版 legacy_path 对象。

所有方法都只是转发到内部 Pytester 实例，并根据需要将结果转换为 legacy_path 对象。

exception TimeoutExpired

property tmpdir: LocalPath

执行测试的临时目录。

make_hook_recorder(pluginmanager)

参见 Pytester.make_hook_recorder()。

chdir()

参见 Pytester.chdir()。

makefile(ext, *args, **kwargs)

参见 Pytester.makefile()。

makeconftest(source)

参见 Pytester.makeconftest()。

makeini(source)

参见 Pytester.makeini()。

getinicfg(source)

参见 Pytester.getinicfg()。

makepyprojecttoml(source)

参见 Pytester.makepyprojecttoml()。

makepyfile(*args, **kwargs)

参见 Pytester.makepyfile()。

maketxtfile(*args, **kwargs)

参见 Pytester.maketxtfile()。

syspathinsert(path=None)

参见 Pytester.syspathinsert()。

mkdir(name)

参见 Pytester.mkdir()。

mkpydir(name)

参见 Pytester.mkpydir()。

copy_example(name=None)

参见 Pytester.copy_example()。

getnode(config, arg)

参见 Pytester.getnode()。

getpathnode(path)

参见 Pytester.getpathnode()。

genitems(colitems)

参见 Pytester.genitems()。

runitem(source)

参见 Pytester.runitem()。

inline_runsource(source, *cmdlineargs)

参见 Pytester.inline_runsource()。

inline_genitems(*args)

参见 Pytester.inline_genitems()。

inline_run(*args, plugins=(), no_reraise_ctrlc=False)

参见 Pytester.inline_run()。

runpytest_inprocess(*args, **kwargs)

参见 Pytester.runpytest_inprocess()。

runpytest(*args, **kwargs)

参见 Pytester.runpytest()。

parseconfig(*args)

参见 Pytester.parseconfig()。

parseconfigure(*args)

参见 Pytester.parseconfigure()。

getitem(source, funcname='test_func')

参见 Pytester.getitem()。

getitems(source)

参见 Pytester.getitems()。

getmodulecol(source, configargs=(), withinit=False)

参见 Pytester.getmodulecol()。

collect_by_name(modcol, name)

参见 Pytester.collect_by_name()。

popen(cmdargs, stdout=-1, stderr=-1, stdin=NotSetType.token, **kw)

参见 Pytester.popen()。

run(*cmdargs, timeout=None, stdin=NotSetType.token)

参见 Pytester.run()。

runpython(script)

参见 Pytester.runpython()。

runpython_c(command)

参见 Pytester.runpython_c()。

runpytest_subprocess(*args, timeout=None)

参见 Pytester.runpytest_subprocess()。

spawn_pytest(string, expect_timeout=10.0)

参见 Pytester.spawn_pytest()。

spawn(cmd, expect_timeout=10.0)

参见 Pytester.spawn()。

tmp_path

教程：如何在测试中使用临时目录和文件

tmp_path()

返回一个临时目录路径对象，该对象对于每个测试函数调用都是唯一的，并作为基本临时目录的子目录创建。

默认情况下，每次测试会话都会创建一个新的基本临时目录，并在 3 个会话后删除旧的基本目录，以帮助调试。可以使用 tmp_path_retention_count 和 tmp_path_retention_policy 配置此行为。如果使用了 --basetemp，则会在每个会话中清除它。请参阅 临时目录位置和保留。

返回的对象是一个 pathlib.Path 对象。

tmp_path_factory

教程：tmp_path_factory fixture

tmp_path_factory 是 TempPathFactory 的实例

final class TempPathFactory

用于创建公共基本临时目录下的临时目录的工厂。

可以使用 --basetemp 选项配置基本目录。

mktemp(basename, numbered=True)

创建一个由工厂管理的新临时目录。

参数：

• basename (str) – 目录基本名称，必须是相对路径。

• numbered (bool) – 如果为 True，则通过添加大于任何现有编号后缀来确保目录唯一：basename="foo-" 和 numbered=True 意味着此函数将创建名为 "foo-0"、"foo-1"、"foo-2" 等的目录。

返回值：

新目录的路径。

返回类型：

路径

getbasetemp()

返回基本临时目录，如果需要则创建它。

返回值：

基本临时目录。

返回类型：

路径

tmpdir

教程：tmpdir 和 tmpdir_factory fixture

tmpdir()

返回一个临时目录路径对象，该对象对于每个测试函数调用都是唯一的，并作为基本临时目录的子目录创建。

默认情况下，每次测试会话都会创建一个新的基本临时目录，并在 3 个会话后删除旧的基本目录，以帮助调试。如果使用了 --basetemp，则会在每个会话中清除它。请参阅 临时目录位置和保留。

返回的对象是一个 legacy_path 对象。

注意

现在，建议使用 tmp_path。

关于 tmpdir 和 tmpdir_factory fixture.

tmpdir_factory

教程：tmpdir 和 tmpdir_factory fixture

tmpdir_factory 是 TempdirFactory 的实例

final class TempdirFactory

向后兼容包装器，为 TempPathFactory 实现 py.path.local。

注意

现在，建议使用 tmp_path_factory。

关于 tmpdir 和 tmpdir_factory fixture.

mktemp(basename, numbered=True)

与 TempPathFactory.mktemp() 相同，但返回一个 py.path.local 对象。

getbasetemp()

与 TempPathFactory.getbasetemp() 相同，但返回一个 py.path.local 对象。

钩子

教程：编写插件

引用所有可以由 conftest.py 文件 和 插件 实现的钩子。

@pytest.hookimpl

@pytest.hookimpl

pytest 用于将函数标记为钩子实现的装饰器。

参见 编写钩子函数 和 pluggy.HookimplMarker()。

@pytest.hookspec

@pytest.hookspec

pytest 用于将函数标记为钩子规范的装饰器。

参见 声明新钩子 和 pluggy.HookspecMarker()。

引导钩子

为足够早注册的插件（内部插件和 setuptools 插件）调用的引导钩子。

pytest_load_initial_conftests(early_config, parser, args)

在命令行选项解析之前调用以实现 初始 conftest 文件 的加载。

参数：

• early_config (Config) – pytest 配置对象。

• args (List[str]) – 在命令行上传递的参数。

• parser (Parser) – 用于添加命令行选项。

在 conftest 插件中使用

不会为 conftest 文件调用此钩子。

pytest_cmdline_parse(pluginmanager, args)

返回一个初始化的 Config，解析指定的 args。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

注意

仅当使用 pytest.main 执行进程内测试运行时，才会为传递给 plugins 参数的插件类调用此钩子。

参数：

• pluginmanager (PytestPluginManager) – pytest 插件管理器。

• args (List[str]) – 命令行上传递的参数列表。

返回值：

pytest 配置对象。

返回类型：

Config | None

在 conftest 插件中使用

不会为 conftest 文件调用此钩子。

pytest_cmdline_main(config)

调用以执行主命令行操作。

默认实现将调用配置钩子和 pytest_runtestloop。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

config (Config) – pytest 配置对象。

返回值：

退出代码。

返回类型：

ExitCode | int | None

在 conftest 插件中使用

此钩子仅针对 初始 conftests 调用。

初始化钩子

为插件和 conftest.py 文件调用的初始化钩子。

pytest_addoption(parser, pluginmanager)

注册 argparse 风格的选项和 ini 风格的配置值，在测试运行开始时调用一次。

参数：

• parser (Parser) – 要添加命令行选项，请调用 parser.addoption(...)。要添加 ini 文件值，请调用 parser.addini(...)。

• pluginmanager (PytestPluginManager) – pytest 插件管理器，可用于安装 hookspec() 或 hookimpl()，并允许一个插件调用另一个插件的钩子来更改添加命令行选项的方式。

之后可以通过 config 对象访问选项，分别为

• config.getoption(name) 检索命令行选项的值。

• config.getini(name) 检索从 ini 风格文件中读取的值。

config 对象通过 .config 属性在许多内部对象上传递，或者可以作为 pytestconfig fixture 检索。

注意

此钩子与钩子包装器不兼容。

在 conftest 插件中使用

如果 conftest 插件实现了此钩子，则在注册 conftest 时将立即调用它。

此钩子仅针对 初始 conftests 调用。

pytest_addhooks(pluginmanager)

在插件注册时调用，以允许通过调用 pluginmanager.add_hookspecs(module_or_class, prefix) 添加新的钩子。

参数：

pluginmanager (PytestPluginManager) – pytest 插件管理器。

注意

此钩子与钩子包装器不兼容。

在 conftest 插件中使用

如果 conftest 插件实现了此钩子，则在注册 conftest 时将立即调用它。

pytest_configure(config)

允许插件和 conftest 文件执行初始配置。

注意

此钩子与钩子包装器不兼容。

参数：

config (Config) – pytest 配置对象。

在 conftest 插件中使用

在解析命令行选项后，将为每个 初始 conftest 文件调用此钩子。之后，在注册其他 conftest 文件时，也会调用此钩子。

pytest_unconfigure(config)

在测试进程退出之前调用。

参数：

config (Config) – pytest 配置对象。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。

pytest_sessionstart(session)

在创建 Session 对象之后，以及在执行收集和进入运行测试循环之前调用。

参数：

session (Session) – pytest 会话对象。

在 conftest 插件中使用

此钩子仅针对 初始 conftests 调用。

pytest_sessionfinish(session, exitstatus)

在整个测试运行结束后，即将向系统返回退出状态之前调用。

参数：

• session (Session) – pytest 会话对象。

• exitstatus (int | ExitCode) – pytest 将返回给系统的状态。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。

pytest_plugin_registered(plugin, plugin_name, manager)

已注册新的 pytest 插件。

参数：

• plugin (_PluggyPlugin) – 插件模块或实例。

• plugin_name (str) – 插件注册时使用的名称。

• manager (PytestPluginManager) – pytest 插件管理器。

注意

此钩子与钩子包装器不兼容。

在 conftest 插件中使用

如果 conftest 插件实现了此钩子，则在注册 conftest 时会立即调用它，对于迄今为止注册的每个插件（包括其自身！）调用一次，并在之后注册所有其他插件时调用。

收集钩子

pytest 调用以下钩子来收集文件和目录

pytest_collection(session)

为给定会话执行收集阶段。

在第一个非 None 结果处停止，请参阅 firstresult：在第一个非 None 结果处停止。返回值未使用，仅停止进一步处理。

默认的收集阶段如下（有关完整详细信息，请参阅各个钩子）

1. 从 session 作为初始收集器开始

1. pytest_collectstart(collector)

2. report = pytest_make_collect_report(collector)

3. 如果发生交互式异常，则执行 pytest_exception_interact(collector, call, report)

4. 对于每个收集的节点

1. 如果是项目，则执行 pytest_itemcollected(item)

2. 如果是收集器，则递归到其中。

5. pytest_collectreport(report)

2. pytest_collection_modifyitems(session, config, items)

1. 对任何取消选择的项目执行 pytest_deselected(items)（可能会被多次调用）

3. pytest_collection_finish(session)

4. 将 session.items 设置为收集到的项目列表

5. 将 session.testscollected 设置为收集到的项目数

您可以实现此钩子，以便仅在收集之前执行某些操作，例如，终端插件使用它来开始显示收集计数器（并返回 None）。

参数：

session (Session) – pytest 会话对象。

在 conftest 插件中使用

此钩子仅针对 初始 conftests 调用。

pytest_ignore_collect(collection_path, path, config)

返回 True 以防止将此路径视为要收集的路径。

在调用更具体的钩子之前，会先咨询此钩子以获取所有文件和目录。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

• collection_path (Path) – 要分析的路径。

• path (LEGACY_PATH) – 要分析的路径（已弃用）。

• config (Config) – pytest 配置对象。

在版本 7.0.0 中更改: 添加了 collection_path 参数作为 path 参数的 pathlib.Path 等效项。 path 参数已被弃用。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的收集路径，仅会咨询收集路径父目录中的 conftest 文件（如果路径是目录，则*不会*咨询其自身的 conftest 文件 - 目录不能忽略自身！）。

pytest_collect_directory(path, parent)

为给定目录创建一个 Collector，如果无关则返回 None。

在版本 8.0 中添加。

为了获得最佳结果，返回的收集器应该是 Directory 的子类，但这不是必需的。

新节点需要将指定的 parent 作为父节点。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

path (Path) – 要分析的路径。

有关使用此钩子的简单示例，请参阅 使用自定义目录收集器。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的收集路径，仅会咨询收集路径父目录中的 conftest 文件（如果路径是目录，则*不会*咨询其自身的 conftest 文件 - 目录不能收集自身！）。

pytest_collect_file(file_path, path, parent)

为给定路径创建一个 Collector，如果无关则返回 None。

为了获得最佳结果，返回的收集器应该是 File 的子类，但这不是必需的。

新节点需要将指定的 parent 作为父节点。

参数：

• file_path (Path) – 要分析的路径。

• path (LEGACY_PATH) – 要收集的路径（已弃用）。

在 7.0.0 版更改: file_path 参数作为 path 参数的 pathlib.Path 等效项添加。 path 参数已被弃用。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的文件路径，仅会查询文件路径父目录中的 conftest 文件。

pytest_pycollect_makemodule(module_path, path, parent)

为给定路径返回 pytest.Module 收集器，如果无关则返回 None。

将为每个匹配的测试模块路径调用此钩子。如果要为不匹配测试模块的文件创建测试模块，则需要使用 pytest_collect_file 钩子。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

• module_path (Path) – 要收集的模块的路径。

• path (LEGACY_PATH) – 要收集的模块的路径（已弃用）。

在 7.0.0 版更改: module_path 参数作为 path 参数的 pathlib.Path 等效项添加。

path 参数已被弃用，取而代之的是 fspath。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的父收集器，仅会查询收集器目录及其父目录中的 conftest 文件。

为了影响 Python 模块中对象的收集，您可以使用以下钩子

pytest_pycollect_makeitem(collector, name, obj)

为模块中的 Python 对象返回自定义项/收集器，如果无关则返回 None。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

• collector (Module | Class) – 模块/类收集器。

• name (str) – 模块/类中对象的名称。

• obj (object) – 对象。

返回值：

创建的项目/收集器。

返回类型：

无 | 项目 | 收集器 | 列表[项目 | 收集器]

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的收集器，仅会查询收集器目录及其父目录中的 conftest 文件。

pytest_generate_tests(metafunc)

生成对测试函数的（多个）参数化调用。

参数：

metafunc (Metafunc) – 测试函数的 Metafunc 帮助器。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的函数定义，仅会查询函数目录及其父目录中的 conftest 文件。

pytest_make_parametrize_id(config, val, argname)

返回给定 val 的用户友好字符串表示形式，该表示形式将由 @pytest.mark.parametrize 调用使用，如果钩子不知道 val，则返回 None。

如果需要，参数名称可作为 argname 使用。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

• config (Config) – pytest 配置对象。

• val (对象) – 参数化的值。

• argname (字符串) – pytest 生成的自动参数名称。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。

用于影响测试跳过的钩子

pytest_markeval_namespace(config)

在构造用于评估 xfail/skipif 标记中的字符串条件的全局字典时调用。

当标记的条件需要在收集时间（这是正常布尔条件所要求的）难以或不可能获取的对象时，这很有用。

6.2 版新增。

参数：

config (Config) – pytest 配置对象。

返回值：

要添加的附加全局变量字典。

返回类型：

字典[字符串, 任何]

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的项目，仅会查询项目父目录中的 conftest 文件。

收集完成后，您可以修改项目的顺序、删除或修改测试项目

pytest_collection_modifyitems(session, config, items)

在执行收集后调用。可以原地过滤或重新排序项目。

参数：

• session (Session) – pytest 会话对象。

• config (Config) – pytest 配置对象。

• items （List[Item]）– 项目对象列表。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

注意

如果在 conftest.py 文件中实现了此钩子，它将始终接收所有收集到的项目，而不仅仅是实现它的 conftest.py 文件下的项目。

pytest_collection_finish(session)

在执行和修改收集后调用。

参数：

session (Session) – pytest 会话对象。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

测试运行（runtest）钩子

所有与 runtest 相关的钩子都会接收一个 pytest.Item 对象。

pytest_runtestloop(session)

执行主要的 runtest 循环（在收集完成后）。

默认的钩子实现会对会话中收集的所有项目（session.items）执行 runtest 协议，除非收集失败或设置了 collectonly pytest 选项。

如果在任何时候调用了 pytest.exit()，循环将立即终止。

如果在任何时候设置了 session.shouldfail 或 session.shouldstop，则在当前项目的 runtest 协议完成后终止循环。

参数：

session (Session) – pytest 会话对象。

在第一个非 None 结果处停止，请参阅 firstresult：在第一个非 None 结果处停止。返回值未使用，仅停止进一步处理。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。

pytest_runtest_protocol(item, nextitem)

对单个测试项目执行 runtest 协议。

默认的 runtest 协议如下（有关完整详细信息，请参阅各个钩子）

• pytest_runtest_logstart(nodeid, location)

• 设置阶段

  • call = pytest_runtest_setup(item) （包装在 CallInfo(when="setup") 中）

  • report = pytest_runtest_makereport(item, call)

  • pytest_runtest_logreport(report)

  • 如果发生交互式异常，则执行 pytest_exception_interact(call, report)

• 调用阶段，如果设置成功并且未设置 setuponly pytest 选项

  • call = pytest_runtest_call(item) （包装在 CallInfo(when="call") 中）

  • report = pytest_runtest_makereport(item, call)

  • pytest_runtest_logreport(report)

  • 如果发生交互式异常，则执行 pytest_exception_interact(call, report)

• 拆卸阶段

  • call = pytest_runtest_teardown(item, nextitem) （包装在 CallInfo(when="teardown") 中）

  • report = pytest_runtest_makereport(item, call)

  • pytest_runtest_logreport(report)

  • 如果发生交互式异常，则执行 pytest_exception_interact(call, report)

• pytest_runtest_logfinish(nodeid, location)

参数：

• item (Item) – 为其执行 runtest 协议的测试项目。

• nextitem (可选[Item]) – 计划执行的下一个测试项（如果这是最后一个，则为 None）。

在第一个非 None 结果处停止，请参阅 firstresult：在第一个非 None 结果处停止。返回值未使用，仅停止进一步处理。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。

pytest_runtest_logstart(nodeid, location)

在为单个测试项运行 runtest 协议开始时调用。

有关 runtest 协议的描述，请参阅 pytest_runtest_protocol。

参数：

• nodeid (str) – 测试项的完整节点 ID。

• location (Tuple[str, int | None, str]) – 由 (filename, lineno, testname) 组成的元组，其中 filename 是相对于 config.rootpath 的文件路径，lineno 从 0 开始。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

pytest_runtest_logfinish(nodeid, location)

在为单个测试项运行 runtest 协议结束时调用。

有关 runtest 协议的描述，请参阅 pytest_runtest_protocol。

参数：

• nodeid (str) – 测试项的完整节点 ID。

• location (Tuple[str, int | None, str]) – 由 (filename, lineno, testname) 组成的元组，其中 filename 是相对于 config.rootpath 的文件路径，lineno 从 0 开始。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

pytest_runtest_setup(item)

调用以执行测试项的设置阶段。

默认实现会在 item 及其所有父级（尚未设置的）上运行 setup()。这包括获取测试项所需的 fixture 的值（尚未获取的）。

参数：

item (Item) – 测试项。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

pytest_runtest_call(item)

调用以运行测试项的测试（调用阶段）。

默认实现调用 item.runtest()。

参数：

item (Item) – 测试项。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

pytest_runtest_teardown(item, nextitem)

调用以执行测试项的拆卸阶段。

默认实现运行终结器并在 item 及其所有父级（需要拆卸）上调用 teardown()。这包括运行该项所需的装置的拆卸阶段（如果它们超出范围）。

参数：

• item (Item) – 测试项。

• nextitem (Item | None) – 计划成为下一个测试项（如果没有安排进一步的测试项，则为 None）。此参数用于执行精确拆卸，即只调用足够的终结器，以便 nextitem 只需要调用设置函数。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

pytest_runtest_makereport(item, call)

调用以创建 TestReport 用于测试项的每个设置、调用和拆卸运行测试阶段。

有关 runtest 协议的描述，请参阅 pytest_runtest_protocol。

参数：

• item (Item) – 测试项。

• call (CallInfo[None]) – 该阶段的 CallInfo。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

为了更深入地了解，您可以查看 _pytest.runner 中这些钩子的默认实现，还可以查看 _pytest.pdb 中的实现，它与 _pytest.capture 及其输入/输出捕获交互，以便在测试失败时立即进入交互式调试。

pytest_pyfunc_call(pyfuncitem)

调用底层测试函数。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

pyfuncitem (Function) – 函数项。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

报告钩子

与会话相关的报告钩子

pytest_collectstart(collector)

收集器开始收集。

参数：

collector (Collector) – 收集器。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的收集器，仅会查询收集器目录及其父目录中的 conftest 文件。

pytest_make_collect_report(collector)

执行 collector.collect() 并返回 CollectReport。

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

参数：

collector (Collector) – 收集器。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的收集器，仅会查询收集器目录及其父目录中的 conftest 文件。

pytest_itemcollected(item)

我们刚刚收集了一个测试项。

参数：

item (Item) – 测试项。

在 conftest 插件中的使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

pytest_collectreport(report)

收集器已完成收集。

参数：

report (CollectReport) – 收集报告。

在 conftest 插件中的使用

任何 conftest 文件都可以实现此钩子。对于给定的收集器，仅会查询收集器目录及其父目录中的 conftest 文件。

pytest_deselected(items)

针对取消选择的测试项调用，例如通过关键字。

可能会被多次调用。

参数：

items (Sequence[Item]) – 测试项。

在 conftest 插件中的使用

任何 conftest 文件都可以实现此钩子。

pytest_report_header(config, start_path, startdir)

返回一个字符串或字符串列表，作为终端报告的标题信息显示。

参数：

• config (Config) – pytest 配置对象。

• start_path (Path) – 起始目录。

• startdir (LEGACY_PATH) – 起始目录（已弃用）。

注意

插件返回的行显示在之前运行的插件的行之前。如果您希望您的行首先显示，请使用 trylast=True。

在版本 7.0.0 中更改: 添加了 start_path 参数作为 startdir 参数的 pathlib.Path 等效项。 startdir 参数已被弃用。

在 conftest 插件中的使用

此钩子仅针对 初始 conftests 调用。

pytest_report_collectionfinish(config, start_path, startdir, items)

返回一个字符串或字符串列表，在收集成功完成后显示。

这些字符串将显示在标准的“已收集 X 个项目”消息之后。

3.2 版新增。

参数：

• config (Config) – pytest 配置对象。

• start_path (Path) – 起始目录。

• startdir (LEGACY_PATH) – 起始目录（已弃用）。

• items (Sequence[Item]) – 将要执行的 pytest 项目列表；此列表不应被修改。

注意

插件返回的行显示在之前运行的插件的行之前。如果您希望您的行首先显示，请使用 trylast=True。

在版本 7.0.0 中更改: 添加了 start_path 参数作为 startdir 参数的 pathlib.Path 等效项。 startdir 参数已被弃用。

在 conftest 插件中的使用

任何 conftest 插件都可以实现此钩子。

pytest_report_teststatus(report, config)

返回用于状态报告的结果类别、简短字母和详细词语。

结果类别是用于统计结果的类别，例如“通过”、“跳过”、“错误”或空字符串。

简短字母在测试进行时显示，例如“.”、“s”、“E”或空字符串。

详细词语在详细模式下进行测试时显示，例如“通过”、“跳过”、“错误”或空字符串。

pytest 可能会根据报告结果隐式地为这些内容设置样式。要提供显式样式，请为详细词语返回一个元组，例如 "rerun", "R", ("RERUN", {"yellow": True})。

参数：

• report (CollectReport | TestReport) – 要返回其状态的报告对象。

• config (Config) – pytest 配置对象。

返回值：

测试状态。

返回类型：

TestShortLogReport | Tuple[str, str, Union[str, Tuple[str, Mapping[str, bool]]]]

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

pytest_report_to_serializable(config, report)

将给定的报告对象序列化为适合通过网络发送的数据结构，例如转换为 JSON。

参数：

• config (Config) – pytest 配置对象。

• report (CollectReport | TestReport) – 报告。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。确切的细节可能取决于调用钩子的插件。

pytest_report_from_serializable(config, data)

恢复先前使用 pytest_report_to_serializable 序列化的报告对象。

参数：

config (Config) – pytest 配置对象。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。确切的细节可能取决于调用钩子的插件。

pytest_terminal_summary(terminalreporter, exitstatus, config)

向终端摘要报告添加一个部分。

参数：

• terminalreporter (TerminalReporter) – 内部终端报告器对象。

• exitstatus (ExitCode) – 将报告给操作系统的退出状态。

• config (Config) – pytest 配置对象。

版本 4.2 中的新功能: config 参数。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

pytest_fixture_setup(fixturedef, request)

执行fixture设置。

参数：

• fixturdef – fixture 定义对象。

• request (SubRequest) – fixture 请求对象。

返回值：

调用 fixture 函数的返回值。

返回类型：

object | None

在第一个非 None 结果处停止，参见 firstresult：在第一个非 None 结果处停止。

注意

如果 fixture 函数返回 None，则将根据 firstresult: 停在第一个非 None 结果处 选项的行为，继续调用此钩子函数的其他实现。

在 conftest 插件中的使用

任何 conftest 文件都可以实现此钩子。对于给定的 fixture，只会在 fixture 作用域的目录及其父目录中查找 conftest 文件。

pytest_fixture_post_finalizer(fixturedef, request)

在 fixture 拆卸之后、缓存清除之前调用，因此 fixture 结果 fixturedef.cached_result 仍然可用（不是 None）。

参数：

• fixturdef – fixture 定义对象。

• request (SubRequest) – fixture 请求对象。

在 conftest 插件中的使用

任何 conftest 文件都可以实现此钩子。对于给定的 fixture，只会在 fixture 作用域的目录及其父目录中查找 conftest 文件。

pytest_warning_recorded(warning_message, when, nodeid, location)

处理由内部 pytest 警告插件捕获的警告。

参数：

• warning_message (warnings.WarningMessage) – 捕获的警告。这与 warnings.catch_warnings 生成的对象相同，并且包含与 warnings.showwarning() 的参数相同的属性。

• when (Literal['config', 'collect', 'runtest']) –

  指示何时捕获到警告。可能的值

  • "config"：在 pytest 配置/初始化阶段。

  • "collect"：在测试收集期间。

  • "runtest"：在测试执行期间。

• nodeid (str) – 项目的完整 ID。对于不特定于特定节点的警告，为空字符串。

• location (Tuple[str, int, str] | None) – 如果可用，则包含有关捕获的警告的执行上下文的信息（文件名、行号、函数）。当执行上下文处于模块级别时，function 的计算结果为 <module>。

6.0 版本新增。

在 conftest 插件中的使用

任何 conftest 文件都可以实现此钩子。如果警告特定于特定节点，则只会在节点的父目录中查找 conftest 文件。

用于报告测试执行情况的中心钩子

pytest_runtest_logreport(report)

处理为项目的每个设置、调用和拆卸运行测试阶段生成的 TestReport。

有关 runtest 协议的描述，请参阅 pytest_runtest_protocol。

在 conftest 插件中的使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

断言相关钩子

pytest_assertrepr_compare(config, op, left, right)

返回失败断言表达式中比较的解释。

如果没有自定义解释，则返回 None，否则返回字符串列表。字符串将由换行符连接，但字符串*中*的任何换行符都将被转义。请注意，除第一行外，所有行都将略微缩进，目的是使第一行成为摘要。

参数：

• config (Config) – pytest 配置对象。

• op (str) – 运算符，例如 "=="、"!="、"not in"。

• left (object) – 左操作数。

• right (object) – 右操作数。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

pytest_assertion_pass(item, lineno, orig, expl)

每当断言通过时调用。

5.0 版新增。

使用此钩子可以在断言通过后进行一些处理。原始断言信息在 orig 字符串中可用，而 pytest 自省的断言信息在 expl 字符串中可用。

此钩子必须由 enable_assertion_pass_hook ini 文件选项显式启用

[pytest]
enable_assertion_pass_hook=true

启用此选项时，您需要**清理**项目目录和解释器库中的**.pyc**文件，因为断言需要重新编写。

参数：

• item (Item) – 当前测试的 pytest 项目对象。

• lineno (int) – 断言语句的行号。

• orig (str) – 包含原始断言的字符串。

• expl (str) – 包含断言解释的字符串。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的测试项，仅会查询该项所在目录及其父目录中的 conftest 文件。

调试/交互钩子

有一些钩子可用于特殊报告或与异常交互

pytest_internalerror(excrepr, excinfo)

在发生内部错误时调用。

返回 True 以抑制将 INTERNALERROR 消息直接打印到 sys.stderr 的回退处理。

参数：

• excrepr (ExceptionRepr) – 异常 repr 对象。

• excinfo (ExceptionInfo[BaseException]) – 异常信息。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

pytest_keyboard_interrupt(excinfo)

在发生键盘中断时调用。

参数：

excinfo (ExceptionInfo[Union[KeyboardInterrupt, Exit]]) – 异常信息。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

pytest_exception_interact(node, call, report)

在引发可能以交互方式处理的异常时调用。

可以在收集期间调用（参见 pytest_make_collect_report），在这种情况下，report 是一个 CollectReport。

可以在项目的运行测试期间调用（参见 pytest_runtest_protocol），在这种情况下，report 是一个 TestReport。

如果引发的异常是内部异常（例如 skip.Exception），则不会调用此钩子。

参数：

• node (Item | Collector) – 项目或收集器。

• call (CallInfo[Any]) – 调用信息。包含异常。

• report (CollectReport | TestReport) – 收集或测试报告。

在 conftest 插件中使用

任何 conftest 文件都可以实现此钩子。对于给定的节点，仅会查询节点父目录中的 conftest 文件。

pytest_enter_pdb(config, pdb)

在调用 pdb.set_trace() 时调用。

插件可以使用它在 Python 调试器进入交互模式之前执行特殊操作。

参数：

• config (Config) – pytest 配置对象。

• pdb (pdb.Pdb) – Pdb 实例。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

pytest_leave_pdb(config, pdb)

在离开 pdb 时调用（例如，在 pdb.set_trace() 之后使用 continue）。

插件可以使用它在 Python 调试器离开交互模式之后执行特殊操作。

参数：

• config (Config) – pytest 配置对象。

• pdb (pdb.Pdb) – Pdb 实例。

在 conftest 插件中使用

任何 conftest 插件都可以实现此钩子。

收集树对象

这些是构成收集树的收集器和项目类（统称为“节点”）。

节点

class Node

基类：ABC

Collector 和 Item 的基类，它们是测试收集树的组件。

Collector 是树的内部节点，而 Item 是叶节点。

fspath: LocalPath

path 属性的 LEGACY_PATH 副本。供尚未迁移到 pathlib.Path 的方法使用，例如 Item.reportinfo。将在未来版本中弃用，建议使用 path 代替。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

keywords: MutableMapping[str, Any]

从所有作用域收集的关键字/标记。

own_markers: List[Mark]

属于此节点的标记对象。

extra_keyword_matches: Set[str]

允许添加额外的关键字用于匹配。

stash: Stash

插件可以在节点上存储信息以供自己使用的地方。

classmethod from_parent(parent, **kw)

节点的公共构造函数。

引入这种间接方式是为了能够从节点构造函数中删除脆弱的逻辑。

子类可以在覆盖构造时使用 super().from_parent(...)。

参数：

parent （Node） – 此节点的父节点。

property ihook: HookRelay

用于调用 pytest 钩子的 fspath 敏感钩子代理。

warn(warning)

为此节点发出警告。

除非明确禁止，否则警告将在测试会话后显示。

参数：

warning （Warning） – 要发出的警告实例。

引发:

ValueError – 如果 warning 实例不是 Warning 的子类。

用法示例

node.warn(PytestWarning("some message"))
node.warn(UserWarning("some message"))

在版本 6.2 中更改: 现在接受 Warning 的任何子类，而不仅仅是 PytestWarning 子类。

property nodeid: str

一个用“::”分隔的字符串，表示其在收集树中的地址。

for ... in iter_parents()

迭代所有父收集器，从自身开始，一直到收集树的根。

在 8.1 版本中添加。

listchain()

返回一个包含所有父收集器的列表，从收集树的根开始，到自身结束。

add_marker(marker, append=True)

动态地向节点添加标记对象。

参数：

• marker （str | MarkDecorator） – 标记。

• append （bool） – 是否追加标记，或者将其前置。

iter_markers(name=None)

迭代节点的所有标记。

参数：

name （str | None）– 如果给出，则按名称属性过滤结果。

返回值：

节点标记的迭代器。

返回类型：

Iterator[Mark]

for ... in iter_markers_with_node(name=None)

迭代节点的所有标记。

参数：

name （str | None）– 如果给出，则按名称属性过滤结果。

返回值：

（节点，标记）元组的迭代器。

返回类型：

Iterator[Tuple[Node, Mark]]

get_closest_marker(name: str) → Mark | None

get_closest_marker(name: str, default: Mark) → Mark

返回与名称匹配的第一个标记，从最近的（例如函数）到更远的级别（例如模块级别）。

参数：

• default – 如果未找到标记，则回退返回值。

• name – 要过滤的名称。

listextrakeywords()

返回自身和任何父级中所有额外关键字的集合。

addfinalizer(fin)

注册一个函数，当该节点完成时，将在没有参数的情况下调用该函数。

此方法只能在设置链中激活此节点时调用，例如在 self.setup() 期间。

getparent(cls)

获取作为给定类实例的最接近的父节点（包括自身）。

参数：

cls (Type[_NodeType]) – 要搜索的节点类。

返回值：

如果找到，则为节点。

返回类型：

_NodeType | None

repr_failure(excinfo, style=None)

返回集合或测试失败的表示形式。

另请参阅

使用非 Python 测试

参数：

excinfo （ExceptionInfo[BaseException]） – 失败的异常信息。

收集器

类 收集器

基类：Node，ABC

所有收集器的基类。

收集器通过 collect() 创建子级，从而迭代地构建收集树。

异常 CollectError

基类：Exception

收集期间的错误，包含自定义消息。

abstractmethod collect()

为此收集器收集子级（项目和收集器）。

repr_failure(excinfo)

返回收集失败的表示形式。

参数：

excinfo （ExceptionInfo[BaseException]） – 失败的异常信息。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

项目

类 项目

基类：Node，ABC

所有测试调用项目的基类。

请注意，对于单个函数，可能有多个测试调用项目。

user_properties: List[Tuple[str, object]]

一个元组列表（名称，值），其中包含此测试的用户定义属性。

名称: str

父节点范围内唯一的名称。

父级

父收集器节点。

配置: 配置

pytest 配置对象。

会话: 会话

此节点所属的 pytest 会话。

路径: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

abstractmethod 运行测试()

运行此项目的测试用例。

必须由子类实现。

另请参阅

使用非 Python 测试

添加报告部分(时间, 键, 内容)

添加一个新的报告部分，类似于内部添加 stdout 和 stderr 捕获输出的操作

item.add_report_section("call", "stdout", "report section contents")

参数：

• 时间 (str) – 可能的捕获状态之一，"设置"、"调用"、"拆卸"。

• 键 (str) – 部分的名称，可以随意自定义。Pytest 在内部使用 "stdout" 和 "stderr"。

• 内容 (str) – 完整内容，以字符串形式表示。

报告信息()

获取此项目的测试报告位置信息。

返回包含三个元素的元组

• 测试的路径（默认为 self.path）

• 测试的从 0 开始的行号（默认为 None）

• 要显示的测试名称（默认为 ""）

另请参阅

使用非 Python 测试

property 位置: Tuple[str, int | None, str]

返回此项目的 (relfspath, lineno, testname) 元组，其中 relfspath 是相对于 config.rootpath 的文件路径，lineno 是从 0 开始的行号。

文件

class 文件

基类： FSCollector， ABC

从文件中收集测试的基类。

使用非 Python 测试.

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

FSCollector

class FSCollector

基类： Collector， ABC

文件系统收集器的基类。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

classmethod from_parent(parent, *, fspath=None, path=None, **kw)

公共构造函数。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

Session

final class Session

基类： Collector

集合树的根。

Session 收集作为参数传递给 pytest 的初始路径。

exception Interrupted

基类：KeyboardInterrupt

表示测试运行被中断。

exception Failed

基类：Exception

表示测试运行失败并停止。

property startpath: Path

调用 pytest 的路径。

版本 7.0.0 中新增。

isinitpath(path, *, with_parents=False)

路径是否是初始路径？

初始路径是在命令行中显式传递给 pytest 的路径。

参数：

with_parents (bool) – 如果设置，则当路径是初始路径的父路径时，也返回 True。

在版本 8.0 中更改: 添加了 with_parents 参数。

perform_collect(args: Sequence[str] | None = None, genitems: Literal[True] = True) → Sequence[Item]

perform_collect(args: Sequence[str] | None = None, genitems: bool = True) → Sequence[Item | Collector]

为本次会话执行收集阶段。

这是由默认的 pytest_collection 钩子实现调用的；有关更多详细信息，请参阅此钩子的文档。出于测试目的，也可以直接在新的 Session 上调用它。

此函数通常会递归地将从会话中收集的任何收集器扩展到它们的项目，并且只返回项目。出于测试目的，可以通过传递 genitems=False 来抑制这种情况，在这种情况下，返回值包含这些未扩展的收集器，并且 session.items 为空。

for ... in collect()

为此收集器收集子级（项目和收集器）。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

包

class Package

基类：Directory

Python 包中文件和目录的收集器 - 具有 __init__.py 文件的目录。

注意

默认情况下，没有 __init__.py 文件的目录由 Dir 收集。两者都是 Directory 收集器。

版本 8.0 中变更: 现在继承自 Directory。

for ... in collect()

为此收集器收集子级（项目和收集器）。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

模块

class Module

基类：File，PyCollector

用于 Python 模块中测试类和函数的收集器。

collect()

为此收集器收集子级（项目和收集器）。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

类

class Class

基类：PyCollector

用于 Python 类中测试方法（和嵌套类）的收集器。

classmethod from_parent(parent, *, name, obj=None, **kw)

公共构造函数。

collect()

为此收集器收集子级（项目和收集器）。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

函数

class Function

基类： PyobjMixin, Item

负责设置和执行 Python 测试函数的项目。

参数：

• name – 完整的函数名称，包括任何装饰器，例如由参数化添加的装饰器（my_func[my_param]）。

• parent – 父节点。

• config – pytest Config 对象。

• callspec – 如果给出，则此函数已参数化，并且 callspec 包含有关参数化的元信息。

• callobj – 如果给出，则是在调用函数时将调用的对象，否则将使用 originalname 从 parent 获取 callobj。

• keywords – 绑定到函数对象的关键字，用于“-k”匹配。

• session – pytest Session 对象。

• fixtureinfo – 已在此 fixture 节点解析的 Fixture 信息。

• originalname – 用于访问底层函数对象的属性名称。默认为 name。如果名称与原始名称不同，请设置此项，例如，当它包含由参数化添加的装饰器时（my_func[my_param]）。

originalname

原始函数名称，没有任何装饰器（例如，参数化会向函数名称添加 "[...]" 后缀），用于从 parent 访问底层函数对象（如果未明确给出 callobj）。

3.0 版新增。

classmethod from_parent(parent, **kw)

公共构造函数。

property function

底层 python “函数”对象。

property instance

函数绑定到的 Python 实例对象。

如果不是测试方法，例如对于独立测试函数、类或模块，则返回 None。

runtest()

执行底层测试函数。

repr_failure(excinfo)

返回集合或测试失败的表示形式。

另请参阅

使用非 Python 测试

参数：

excinfo （ExceptionInfo[BaseException]） – 失败的异常信息。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

函数定义

class FunctionDefinition

基类：Function

此类是一个权宜之计，直到我们发展到拥有实际的函数定义节点并设法摆脱 metafunc。

runtest()

执行底层测试函数。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

setup()

执行底层测试函数。

对象

可从 fixture 或 钩子 访问的对象，或可从 pytest 导入的对象。

调用信息

final class CallInfo

函数调用结果/异常信息。

excinfo: ExceptionInfo[BaseException] | None

如果调用引发了异常，则为捕获的异常。

start: float

调用开始时的系统时间，以自纪元以来的秒数表示。

stop: float

调用结束时的系统时间，以自纪元以来的秒数表示。

duration: float

调用持续时间，以秒为单位。

when: Literal['collect', 'setup', 'call', 'teardown']

调用的上下文：“collect”、“setup”、“call” 或 “teardown”。

property result: TResult

如果调用没有引发异常，则为调用的返回值。

只有当 excinfo 为 None 时才能访问。

classmethod from_call(func, when, reraise=None)

调用 func，将结果包装在 CallInfo 中。

参数：

• func (Callable[[], TResult]) – 要调用的函数。不带参数调用。

• when (Literal['collect', 'setup', 'call', 'teardown']) – 调用函数的阶段。

• reraise (Type[BaseException] | Tuple[Type[BaseException], ...] | None) – 如果函数引发了异常，则应传播的异常，而不是包装在 CallInfo 中。

收集报告

final class CollectReport

基类： BaseReport

收集报告对象。

报告可以包含任意额外的属性。

nodeid: str

标准化集合节点 ID。

outcome: Literal['passed', 'failed', 'skipped']

测试结果，始终是“passed”、“failed”、“skipped”之一。

longrepr: None | ExceptionInfo[BaseException] | Tuple[str, int, str] | str | TerminalRepr

无或失败表示。

result

收集到的项目和集合节点。

sections: List[Tuple[str, str]]

包含字符串元组 (标题, 内容) 的元组，其中包含测试报告的额外信息。pytest 使用它来添加从 stdout、stderr 和拦截的日志事件中捕获的文本。其他插件可以使用它向报告添加任意信息。

property caplog: str

如果启用了日志捕获，则返回捕获的日志行。

3.5 版新增。

property capstderr: str

如果启用了捕获，则返回从 stderr 捕获的文本。

3.0 版新增。

property capstdout: str

如果启用了捕获，则返回从 stdout 捕获的文本。

3.0 版新增。

property count_towards_summary: bool

实验性的 此报告是否应计入测试会话结束时显示的总数：“1 次通过，1 次失败等”。

注意

此函数被认为是实验性的，因此请注意，即使在补丁版本中，它也可能会发生变化。

property failed: bool

结果是否失败。

property fspath: str

报告节点的路径部分，以字符串形式表示。

property head_line: str | None

实验性的 此报告的 longrepr 输出中显示的标题行，更常见于失败期间的回溯表示

________ Test.foo ________

在上面的例子中，head_line 是“Test.foo”。

注意

此函数被认为是实验性的，因此请注意，即使在补丁版本中，它也可能会发生变化。

property longreprtext: str

只读属性，返回 longrepr 的完整字符串表示形式。

3.0 版新增。

property passed: bool

结果是否通过。

property skipped: bool

结果是否跳过。

配置

final class Config

访问配置值、插件管理器和插件钩子。

参数：

• pluginmanager (PytestPluginManager) – 一个 pytest PluginManager。

• invocation_params (InvocationParams) – 包含有关 pytest.main() 调用的参数的对象。

final class InvocationParams(*, args, plugins, dir)

保存 pytest.main() 期间传递的参数。

对象属性是只读的。

版本 5.1 中新增。

注意

请注意，环境变量 PYTEST_ADDOPTS 和 addopts ini 选项由 pytest 处理，不包含在 args 属性中。

访问 InvocationParams 的插件必须注意这一点。

args: Tuple[str, ...]

传递给 pytest.main() 的命令行参数。

plugins: Sequence[str | object] | None

额外的插件，可能是 None。

dir: Path

调用 pytest.main() 的目录。

class ArgsSource(value)

指示测试参数的来源。

版本 7.2 中新增。

ARGS = 1

命令行参数。

INVOCATION_DIR = 2

调用目录。

TESTPATHS = 3

“testpaths” 配置值。

option

以属性形式访问命令行选项。

类型：

argparse.Namespace

invocation_params

调用 pytest 的参数。

类型：

InvocationParams

pluginmanager

插件管理器处理插件注册和钩子调用。

类型：

PytestPluginManager

stash

插件可以在其中存储配置信息以供自己使用。

类型：

Stash

property rootpath: Path

根目录 的路径。

类型：

pathlib.Path

版本 6.1 中新增。

property inipath: Path | None

指向 配置文件 的路径。

类型：

可选[pathlib.Path]

版本 6.1 中新增。

add_cleanup(func)

添加一个函数，当配置对象不再使用时调用（通常与 pytest_unconfigure 一致）。

classmethod fromdictargs(option_dict, args)

可用于子进程的构造函数。

issue_config_time_warning(warning, stacklevel)

在“配置”阶段发出并处理警告。

在 pytest_configure 期间，我们无法使用 catch_warnings_for_item 函数捕获警告，因为不可能在 pytest_configure 周围设置钩子包装器。

此函数主要用于需要在 pytest_configure（或类似阶段）期间发出警告的插件。

参数：

• warning (Warning) – 警告实例。

• stacklevel (int) – 转发给 warnings.warn 的堆栈级别。

addinivalue_line(name, line)

向 ini 文件选项添加一行。该选项必须已声明，但可能尚未设置，在这种情况下，该行将成为其值的第一行。

getini(name)

从 ini 文件 返回配置值。

如果在 ini 文件 中未定义配置值，则将返回通过 parser.addini 注册配置时提供的 default 值。请注意，您甚至可以提供 None 作为有效的默认值。

如果在使用 parser.addini 注册时未提供 default，则将返回基于传递给 parser.addini 的 type 参数的默认值。基于 type 的默认值为：paths、pathlist、args 和 linelist：空列表 [] bool：False string：空字符串 ""

如果在通过 parser.addini 注册配置时既没有传递 default 参数也没有传递 type 参数，则将该配置视为字符串，并返回默认空字符串 ''。

如果指定的名称尚未通过之前的 parser.addini 调用（通常来自插件）注册，则会引发 ValueError。

getoption(name, default=<NOTSET>, skip=False)

返回命令行选项值。

参数：

• name (str) – 选项的名称。您也可以指定字面量 --OPT 选项而不是 “dest” 选项名称。

• default – 如果不存在该名称的选项，则使用默认值。

• skip (bool) – 如果为 True，则在选项不存在或值为 None 时引发 pytest.skip。

getvalue(name, path=None)

已弃用，请改用 getoption()。

getvalueorskip(name, path=None)

已弃用，请改用 getoption(skip=True)。

VERBOSITY_ASSERTIONS: Final = 'assertions'

失败断言的详细级别类型（请参阅 verbosity_assertions）。

VERBOSITY_TEST_CASES: Final = 'test_cases'

测试用例执行的详细级别类型（请参阅 verbosity_test_cases）。

get_verbosity(verbosity_type=None)

检索细粒度详细级别类型的详细级别。

参数：

verbosity_type（str | None）– 要获取级别的详细级别类型。如果为给定类型配置了级别，则将返回该值。如果给定类型不是已知的详细级别类型，则将返回全局详细级别。如果给定类型为 None（默认值），则将返回全局详细级别。

要为细粒度的详细级别类型配置级别，配置文件应包含配置名称的设置和详细级别的数值。可以使用特殊值“auto”来显式使用全局详细级别。

示例： .. code-block:: ini

# pytest.ini 的内容 [pytest] verbosity_assertions = 2

pytest -v

print(config.get_verbosity())  # 1
print(config.get_verbosity(Config.VERBOSITY_ASSERTIONS))  # 2

目录

final class Dir

文件系统目录中文件的收集器。

在版本 8.0 中添加。

注意

默认情况下，包含 __init__.py 文件的 Python 目录由 Package 收集。两者都是 Directory 收集器。

classmethod from_parent(parent, *, path)

公共构造函数。

参数：

• parent（Collector）– 此 Dir 的父收集器。

• path（Path）– 目录的路径。

for ... in collect()

为此收集器收集子级（项目和收集器）。

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

目录

class Directory

从目录收集文件的基类。

一个基本的目录收集器会执行以下操作：遍历目录中的文件和子目录，并通过调用钩子 pytest_collect_directory 和 pytest_collect_file 为它们创建收集器，并在使用 pytest_ignore_collect 检查它们未被忽略后进行创建。

默认的目录收集器是 Dir 和 Package。

在版本 8.0 中添加。

使用自定义目录收集器.

name: str

父节点范围内唯一的名称。

parent

父收集器节点。

config: Config

pytest 配置对象。

session: Session

此节点所属的 pytest 会话。

path: pathlib.Path

收集此节点的文件系统路径（可以是 None）。

ExceptionInfo

final class ExceptionInfo

包装 sys.exc_info() 对象并提供导航回溯的帮助。

classmethod from_exception(exception, exprinfo=None)

为现有异常返回一个 ExceptionInfo。

异常必须有一个非 None 的 __traceback__ 属性，否则此函数将因断言错误而失败。这意味着必须已引发异常，或使用 with_traceback() 方法添加了回溯。

参数：

exprinfo (str | None) – 一个文本字符串，用于帮助确定是否应该从输出中删除 AssertionError。默认为异常消息/__str__()。

7.4 版新增。

classmethod from_exc_info(exc_info, exprinfo=None)

与 from_exception() 类似，但使用旧式的 exc_info 元组。

classmethod from_current(exprinfo=None)

返回与当前回溯匹配的 ExceptionInfo。

警告

实验性 API

参数：

exprinfo (str | None) – 一个文本字符串，用于帮助确定是否应该从输出中删除 AssertionError。默认为异常消息/__str__()。

classmethod for_later()

返回一个未填充的 ExceptionInfo。

fill_unfilled(exc_info)

填充使用 for_later() 创建的未填充 ExceptionInfo。

property type: Type[E]

异常类。

property value: E

异常值。

property tb: TracebackType

异常原始回溯。

property typename: str

异常的类型名称。

property traceback: Traceback

回溯。

exconly(tryshort=False)

以字符串形式返回异常。

当“tryshort”解析为 True 且异常为 AssertionError 时，仅返回异常表示的实际异常部分（因此从开头删除“AssertionError:”）。

errisinstance(exc)

如果异常是 exc 的实例，则返回 True。

考虑改用 isinstance(excinfo.value, exc)。

getrepr(showlocals=False, style='long', abspath=False, tbfilter=True, funcargs=False, truncate_locals=True, chain=True)

返回此异常信息的 str() 可表示形式。

参数：

• showlocals (bool) – 显示每个回溯条目的局部变量。如果 style=="native" 则忽略。

• style (str) – long|short|line|no|native|value 回溯样式。

• abspath (bool) – 路径是否应更改为绝对路径或保持不变。

• tbfilter (bool | Callable[[ExceptionInfo[BaseException]], Traceback]) –

  回溯条目的过滤器。

  • 如果为 false，则不隐藏任何条目。

  • 如果为 true，则隐藏包含局部变量 __tracebackhide__ = True 的内部条目和条目。

  • 如果为可调用对象，则将过滤委托给该可调用对象。

  如果 style 为 "native" 则忽略。

• funcargs (bool) – 显示每个回溯条目的 fixture（“funcargs”用于 legacy 目的）。

• truncate_locals (bool) – 使用 showlocals==True 时，确保局部变量可以安全地表示为字符串。

• chain (bool) – 是否应显示 Python 3 中的链接异常。

在版本 3.9 中更改: 添加了 chain 参数。

match(regexp)

使用 re.search() 检查正则表达式 regexp 是否与异常的字符串表示形式匹配。

如果匹配，则返回 True，否则引发 AssertionError。

group_contains(expected_exception, *, match=None, depth=None)

检查捕获的异常组是否包含匹配的异常。

参数：

• expected_exception (Type[BaseException] | Tuple[Type[BaseException]]) – 预期的异常类型，如果预期有多个可能的异常类型，则为元组。

• match (str | Pattern[str] | None) –

  如果指定，则为包含正则表达式的字符串或正则表达式对象，该字符串或正则表达式对象将使用 re.search() 对异常的字符串表示形式及其 PEP-678 <https://peps.pythonlang.cn/pep-0678/> __notes__ 进行测试。

  要匹配可能包含 特殊字符 的字符串字面量，可以使用 re.escape() 对其进行转义。

• depth (Optional[int]) – 如果为 None，则将在任何嵌套深度搜索匹配的异常。如果 >= 1，则仅当异常位于指定深度时才会匹配（深度 = 1 是最顶层异常组中包含的异常）。

在版本 8.0 中添加。

ExitCode

final class ExitCode(value)

编码 pytest 的有效退出代码。

目前，用户和插件也可以提供其他退出代码。

5.0 版新增。

OK = 0

测试通过。

TESTS_FAILED = 1

测试失败。

INTERRUPTED = 2

pytest 被中断。

INTERNAL_ERROR = 3

内部错误。

USAGE_ERROR = 4

pytest 使用不当。

NO_TESTS_COLLECTED = 5

pytest 找不到测试。

FixtureDef

final class FixtureDef

基类：Generic[FixtureValue]

fixture 定义的容器。

注意：目前，只有明确记录的字段和方法才被视为公共稳定 API。

property scope: Literal['session', 'package', 'module', 'class', 'function']

范围字符串，可以是 “function”、“class”、“module”、“package”、“session” 之一。

execute(request)

返回此 fixture 的值，如果未缓存，则执行它。

标记装饰器

class MarkDecorator

用于在测试函数和类上应用标记的装饰器。

标记装饰器 是用 pytest.mark 创建的

mark1 = pytest.mark.NAME  # Simple MarkDecorator
mark2 = pytest.mark.NAME(name1=value)  # Parametrized MarkDecorator

然后可以作为装饰器应用于测试函数

@mark2
def test_function():
    pass

当调用 标记装饰器 时，它会执行以下操作

1. 如果仅使用单个类作为其唯一的位置参数调用，并且没有其他关键字参数，则它会将标记附加到该类，以便自动应用于在该类中找到的所有测试用例。

2. 如果仅使用单个函数作为其唯一的位置参数调用，并且没有其他关键字参数，则它会将标记附加到该函数，其中包含已存储在 标记装饰器 内部的所有参数。

3. 在任何其他情况下调用时，它都会返回一个新的 标记装饰器 实例，其中原始 标记装饰器 的内容已使用传递给此调用的参数进行了更新。

注意：以上规则阻止 标记装饰器 仅存储单个函数或类引用作为其位置参数，而没有其他关键字或位置参数。您可以使用 with_args() 来解决此问题。

property name: str

mark.name 的别名。

property args: Tuple[Any, ...]

mark.args 的别名。

property kwargs: Mapping[str, Any]

mark.kwargs 的别名。

with_args(*args, **kwargs)

返回添加了额外参数的 MarkDecorator。

与调用 MarkDecorator 不同，即使唯一参数是可调用对象/类，也可以使用 with_args()。

标记生成器

final class MarkGenerator

MarkDecorator 对象的工厂 - 作为 pytest.mark 单例实例公开。

例子

import pytest


@pytest.mark.slowtest
def test_function():
    pass

在 test_function 上应用“slowtest” Mark。

标记

final class Mark

pytest 标记。

name: str

标记的名称。

args: Tuple[Any, ...]

标记装饰器的 positional 参数。

kwargs: Mapping[str, Any]

标记装饰器的关键字参数。

combined_with(other)

返回一个新的 Mark，它是此 Mark 与另一个 Mark 的组合。

通过追加 args 和合并 kwargs 来组合。

参数：

other (Mark) – 要组合的标记。

返回类型：

Mark

元函数

final class Metafunc

传递给 pytest_generate_tests 钩子的对象。

它们有助于检查测试函数，并根据测试配置或在定义测试函数的类或模块中指定的值生成测试。

definition

访问底层 _pytest.python.FunctionDefinition。

config

访问测试会话的 pytest.Config 对象。

模块

定义测试函数的模块对象。

函数

底层 Python 测试函数。

fixturenames

测试函数所需的 fixture 名称集合。

cls

定义测试函数的类对象，或者为 None。

parametrize(argnames, argvalues, indirect=False, ids=None, scope=None, *, _param_mark=None)

使用给定参数名称 (argnames) 的参数值 (argvalues) 列表，为底层测试函数添加新的调用。参数化在收集阶段执行。如果您需要设置昂贵的资源，请考虑设置 indirect 来在测试设置阶段而不是收集时进行设置。

可以对每个测试函数调用多次（但只能使用不同的参数名称），在这种情况下，每次调用都会参数化所有先前的参数化，例如：

unparametrized:         t
parametrize ["x", "y"]: t[x], t[y]
parametrize [1, 2]:     t[x-1], t[x-2], t[y-1], t[y-2]

参数：

• argnames (str | Sequence[str]) – 表示一个或多个参数名称的逗号分隔字符串，或参数字符串的列表/元组。

• argvalues (Iterable[ParameterSet | Sequence[object] | object]) –

  参数值 (argvalues) 列表决定了使用不同参数值调用测试的频率。

  如果只指定了一个参数名称 (argname)，则参数值 (argvalues) 是一个值列表。如果指定了 N 个参数名称，则参数值 (argvalues) 必须是一个 N 元组列表，其中每个元组元素为其各自的参数名称指定一个值。

• indirect (bool | Sequence[str]) – 参数名称列表（参数名称的子集）或布尔值。如果为 True，则列表包含参数名称中的所有名称。与此列表中的参数名称相对应的每个参数值都将作为 request.param 传递给其各自的参数名称 fixture 函数，以便它可以在测试的设置阶段而不是收集时执行更昂贵的设置。

• ids (Iterable[object | None] | Callable[[Any], object | None] | None) –

  argvalues 的 id 序列（或生成器），或为每个参数值返回部分 id 的可调用对象。

  对于序列（和像 itertools.count() 这样的生成器），返回的 id 应该是 string、int、float、bool 或 None 类型。它们映射到 argvalues 中的相应索引。None 表示使用自动生成的 id。

  如果它是一个可调用对象，它将为 argvalues 中的每个条目调用，返回值将用作整个集合的自动生成 ID 的一部分（其中各部分用短划线（“-”）连接）。这对于为某些项目（例如日期）提供更具体的 ID 非常有用。返回 None 将使用自动生成的 ID。

  如果未提供 ID，则将根据 argvalues 自动生成。

• scope (Literal['session', 'package', 'module', 'class', 'function'] | None) – 如果指定，则表示参数的范围。范围用于按参数实例对测试进行分组。它还将覆盖任何由 fixture 函数定义的范围，从而允许使用测试上下文或配置设置动态范围。

解析器

final class Parser

用于命令行参数和 ini 文件值的解析器。

变量：

extra_info – 通用参数的字典 -> 在处理命令行参数时出错的情况下显示的值。

getgroup(name, description='', after=None)

获取（或创建）一个命名的选项组。

参数：

• name (str) – 选项组的名称。

• description (str) – –help 输出的长描述。

• after (str | None) – 另一个组的名称，用于排序 –help 输出。

返回值：

选项组。

返回类型：

OptionGroup

返回的组对象有一个 addoption 方法，其签名与 parser.addoption 相同，但将在 pytest --help 的输出中显示在相应的组中。

addoption(*opts, **attrs)

注册一个命令行选项。

参数：

• opts (str) – 选项名称，可以是短选项或长选项。

• attrs (Any) – 与 argparse 库的 add_argument() 函数接受的属性相同。

命令行解析后，可以通过 config.option.NAME 在 pytest 配置对象上获取选项，其中 NAME 通常通过传递 dest 属性来设置，例如 addoption("--long", dest="NAME", ...)。

parse_known_args(args, namespace=None)

解析当前已知的参数。

返回值：

一个 argparse 命名空间对象。

返回类型：

命名空间

parse_known_and_unknown_args(args, namespace=None)

解析当前已知的参数，并返回剩余的未知参数。

返回值：

一个元组，包含已知参数的 argparse 命名空间对象和未知参数的列表。

返回类型：

元组[命名空间, 列表[str]]

addini(name, help, type=None, default=<notset>)

注册一个 ini 文件选项。

参数：

• name (str) – ini 变量的名称。

• type (Literal['string', 'paths', 'pathlist', 'args', 'linelist', 'bool'] | None) –

  变量的类型。可以是

  • string：字符串

  • bool：布尔值

  • args：字符串列表，以 shell 中的方式分隔

  • linelist：字符串列表，以换行符分隔

  • paths：pathlib.Path 列表，以 shell 中的方式分隔

  • pathlist：py.path 列表，以 shell 中的方式分隔

  对于 paths 和 pathlist 类型，它们被认为是相对于 ini 文件的。如果在没有定义 ini 文件的情况下执行，它们将被认为是相对于当前工作目录的（例如使用 --override-ini）。

  7.0 版新增: paths 变量类型。

  8.1 版新增: 在没有 ini 文件的情况下，使用当前工作目录来解析 paths 和 pathlist。

  如果为 None 或未传递，则默认为 string。

• default (任何) – 如果 ini 文件选项不存在但被查询，则使用默认值。

可以通过调用 config.getini(name) 来检索 ini 变量的值。

选项组

class OptionGroup

在它自己的部分中显示的一组选项。

addoption(*opts, **attrs)

向该组添加一个选项。

如果指定了长选项的缩写版本，则它将在帮助中被抑制。 addoption('--twowords', '--two-words') 导致帮助只显示 --two-words，但 --twowords 会被接受，并且自动目标在 args.twowords 中。

参数：

• opts (str) – 选项名称，可以是短选项或长选项。

• attrs (Any) – 与 argparse 库的 add_argument() 函数接受的属性相同。

PytestPluginManager

final class PytestPluginManager

基类： PluginManager

具有 pytest 特定功能的 pluggy.PluginManager

• 从命令行、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) 将在所有钩子调用之前被调用，并接收一个钩子调用器实例、一个 HookImpl 实例列表和钩子调用的关键字参数。

after(outcome, hook_name, hook_impls, kwargs) 接收与 before 相同的参数，但还接收一个 Result 对象，该对象表示整个钩子调用的结果。

add_hookspecs(module_or_class)

添加在给定 module_or_class 中定义的新钩子规范。

如果函数已使用匹配的 HookspecMarker 进行装饰，则它们将被识别为钩子规范。

check_pending()

验证所有尚未根据钩子规范进行验证的钩子是否都是可选的，否则引发 PluginValidationError。

enable_tracing()

启用钩子调用跟踪。

返回一个撤销函数，调用该函数将移除添加的跟踪。

get_canonical_name(plugin)

返回插件对象的规范名称。

请注意，插件可以使用 register(plugin, name) 的调用者指定的不同名称进行注册。要获取已注册插件的名称，请改用 get_name(plugin)。

get_hookcallers(plugin)

获取指定插件的所有钩子调用器。

返回值：

钩子调用器，如果 plugin 未在此插件管理器中注册，则为 None。

返回类型：

列表[HookCaller] | 无

get_name(plugin)

返回插件注册时使用的名称，如果未注册，则返回 None。

get_plugin(name)

返回使用给定名称注册的插件（如果有）。

get_plugins()

返回所有已注册插件对象的集合。

has_plugin(name)

返回是否注册了具有给定名称的插件。

is_blocked(name)

返回给定的插件名称是否被阻止。

is_registered(plugin)

返回插件是否已注册。

list_name_plugin()

返回所有已注册插件的 (名称, 插件) 对列表。

list_plugin_distinfo()

返回所有 setuptools 注册插件的 (插件, distinfo) 对列表。

load_setuptools_entrypoints(group, name=None)

从查询指定的 setuptools group 加载模块。

参数：

• group (str) – 要加载插件的入口点组。

• name (str | None) – 如果给出，则仅加载具有给定 name 的插件。

返回值：

此调用加载的插件数量。

返回类型：

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]

跟踪入口点。请参阅 内置跟踪。

测试报告

final class TestReport

基类： BaseReport

基本测试报告对象（如果设置和拆卸调用失败，也用于这些调用）。

报告可以包含任意额外的属性。

nodeid: str

标准化集合节点 ID。

location: Tuple[str, int | None, str]

一个 (filesystempath, lineno, domaininfo) 元组，指示测试项的实际位置 - 它可能与收集到的位置不同，例如，如果一个方法是从不同的模块继承的。filesystempath 可以是相对于 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

无或失败表示。

when: str | None

“setup”、“call”、“teardown” 中的一个，用于指示运行测试阶段。

user_properties

用户属性是一个元组列表 (名称，值)，用于保存测试的用户定义属性。

sections: List[Tuple[str, str]]

包含字符串元组 (标题, 内容) 的元组，其中包含测试报告的额外信息。pytest 使用它来添加从 stdout、stderr 和拦截的日志事件中捕获的文本。其他插件可以使用它向报告添加任意信息。

duration: float

仅运行测试所需的时间。

start: float

调用开始时的系统时间，以自纪元以来的秒数表示。

stop: float

调用结束时的系统时间，以自纪元以来的秒数表示。

classmethod from_item_and_call(item, call)

使用标准项目和调用信息创建并填充 TestReport。

参数：

• item (Item) – 项目。

• call (CallInfo[None]) – 调用信息。

property caplog: str

如果启用了日志捕获，则返回捕获的日志行。

3.5 版新增。

property capstderr: str

如果启用了捕获，则返回从 stderr 捕获的文本。

3.0 版新增。

property capstdout: str

如果启用了捕获，则返回从 stdout 捕获的文本。

3.0 版新增。

property count_towards_summary: bool

实验性的 此报告是否应计入测试会话结束时显示的总数：“1 次通过，1 次失败等”。

注意

此函数被认为是实验性的，因此请注意，即使在补丁版本中，它也可能会发生变化。

property failed: bool

结果是否失败。

property fspath: str

报告节点的路径部分，以字符串形式表示。

property head_line: str | None

实验性的 此报告的 longrepr 输出中显示的标题行，更常见于失败期间的回溯表示

________ Test.foo ________

在上面的例子中，head_line 是“Test.foo”。

注意

此函数被认为是实验性的，因此请注意，即使在补丁版本中，它也可能会发生变化。

property longreprtext: str

只读属性，返回 longrepr 的完整字符串表示形式。

3.0 版新增。

property passed: bool

结果是否通过。

property 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 的别名

结果

在 钩子包装器 中使用的结果对象，更多信息请参阅 pluggy 文档 中 的 Result。

存储

class Stash

Stash 是一种类型安全的异构可变映射，它允许在创建它（Stash）的位置之外单独定义键和值的类型。

通常，您会得到一个带有 Stash 的对象，例如 Config 或 Node

stash: Stash = some_object.stash

如果模块或插件想要在这个 Stash 中存储数据，它会为它的键创建 StashKey（在模块级别）

# At the top-level of the module
some_str_key = StashKey[str]()
some_bool_key = StashKey[bool]()

存储信息

# Value type must match the key.
stash[some_str_key] = "value"
stash[some_bool_key] = True

检索信息

# The static type of some_str is str.
some_str = stash[some_str_key]
# The static type of some_bool is 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__()

返回存储中存在的项目数量。

class StashKey

基类：Generic[T]

StashKey 是一个用作 Stash 键的对象。

StashKey 与键的值的类型 T 相关联。

StashKey 是唯一的，不能与其他键冲突。

7.0 版新增。

全局变量

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

collect_ignore

教程：自定义测试收集

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

collect_ignore = ["setup.py"]

collect_ignore_glob

教程：自定义测试收集

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

collect_ignore_glob = ["*_ignore.py"]

pytest_plugins

教程：在测试模块或 conftest 文件中要求/加载插件

可以在 测试模块 和 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]

环境变量

可用于更改 pytest 行为的环境变量。

CI

设置后（无论值是什么），pytest 都会识别它正在 CI 进程中运行。 BUILD_NUMBER 变量的替代方案。

BUILD_NUMBER

设置后（无论值是什么），pytest 都会识别它正在 CI 进程中运行。 CI 变量的替代方案。

PYTEST_ADDOPTS

这包含一个命令行（由 py:mod:shlex 模块解析），它将被**添加到**用户给出的命令行之前，更多信息请参阅 内置配置文件选项。

PYTEST_VERSION

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

PYTEST_CURRENT_TEST

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

PYTEST_DEBUG

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

PYTEST_DISABLE_PLUGIN_AUTOLOAD

设置后，将禁用通过 setuptools 入口点自动加载插件。只会加载明确指定的插件。

PYTEST_PLUGINS

包含应作为插件加载的模块的逗号分隔列表

export PYTEST_PLUGINS=mymodule.plugin,xdist

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。

异常

final exception UsageError

基类：Exception

pytest 使用或调用中的错误。

final exception FixtureLookupError

基类：LookupError

无法返回请求的 fixture（缺失或无效）。

警告

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

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 PytestReturnNotNoneWarning

基类：PytestWarning

当测试函数返回 None 以外的值时发出的警告。

class PytestRemovedIn9Warning

基类：PytestDeprecationWarning

针对将在 pytest 9 中删除的功能的警告类。

class PytestUnhandledCoroutineWarning

基类：PytestReturnNotNoneWarning

针对未处理的协程发出的警告。

收集测试函数时遇到了协程，但没有任何异步感知插件处理它。协程测试函数本身不受支持。

class PytestUnknownMarkWarning

基类：PytestWarning

使用未知标记时发出警告。

有关详细信息，请参阅如何使用属性标记测试函数。

class PytestUnraisableExceptionWarning

基类：PytestWarning

报告了一个不可引发的异常。

不可引发的异常是在 __del__ 实现和类似情况下引发的异常，此时无法像正常情况那样引发异常。

class PytestUnhandledThreadExceptionWarning

基类：PytestWarning

Thread 中发生了一个未处理的异常。

此类异常不会正常传播。

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

配置选项

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

要详细查看每种文件格式，请参阅配置文件格式。

警告

不建议使用 setup.cfg，除非是非常简单的用例。 .cfg 文件使用的解析器与 pytest.ini 和 tox.ini 不同，这可能会导致难以跟踪问题。如果可能，建议使用后者文件或 pyproject.toml 来保存 pytest 配置。

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

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

addopts

将指定的 OPTS 添加到命令行参数集中，就好像它们是由用户指定的。示例：如果您的 ini 文件内容如下

# content of pytest.ini
[pytest]
addopts = --maxfail=2 -rf  # exit after 2 failures, report fail info

则发出 pytest test_hello.py 实际上意味着

pytest --maxfail=2 -rf test_hello.py

默认是不添加任何选项。

cache_dir

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

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，但将进度显示为已完成测试的数量而不是百分比。

默认值为 progress，但如果更喜欢经典模式或新模式导致意外问题，则可以回退到 classic

# content of pytest.ini
[pytest]
console_output_style = classic

doctest_encoding

用于解码带有文档字符串的文本文件的默认编码。 请参阅 pytest 如何处理文档测试。

doctest_optionflags

来自标准 doctest 模块的一个或多个 doctest 标志名称。 请参阅 pytest 如何处理文档测试。

empty_parameter_set_mark

允许在参数化中选择空参数集的操作

• skip 跳过具有空参数集的测试（默认）

• xfail 将具有空参数集的测试标记为 xfail(run=False)

• fail_at_collect 如果参数化收集到空参数集，则引发异常

# content of pytest.ini
[pytest]
empty_parameter_set_mark = xfail

注意

此选项的默认值计划在未来版本中更改为 xfail，因为这被认为不太容易出错，请参阅 问题 #3155 了解更多详细信息。

faulthandler_timeout

如果测试运行时间超过 X 秒（包括夹具设置和拆卸），则转储所有线程的回溯。 使用 faulthandler.dump_traceback_later() 函数实现，因此所有注意事项均适用。

# content of pytest.ini
[pytest]
faulthandler_timeout=5

有关更多信息，请参阅 故障处理程序。

filterwarnings

设置应采取的匹配警告的过滤器和操作列表。 默认情况下，测试会话期间发出的所有警告都将在测试会话结束时显示在摘要中。

# content of 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：仅写入 logging 捕获的输出。

• system-out：写入捕获的 stdout 内容。

• system-err：写入捕获的 stderr 内容。

• out-err：写入捕获的 stdout 和 stderr 内容。

• all：写入捕获的 logging、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 [值] 和配置选项 log_auto_indent = [值] 来设置所有日志记录的自动缩进行为。

[值] 可以是

• True 或 “On” - 动态自动缩进多行日志消息

• False 或 “Off” 或 0 - 不要自动缩进多行日志消息（默认行为）

• [正整数] - 将多行日志消息自动缩进 [值] 个空格

[pytest]
log_auto_indent = False

支持将关键字参数 extra={"auto_indent": [值]} 传递给对 logging.log() 的调用，以指定日志中特定条目的自动缩进行为。 extra 关键字参数会覆盖在命令行或配置中指定的值。

log_cli

在测试运行期间启用日志显示（也称为 “实时日志记录”）。默认值为 False。

[pytest]
log_cli = True

log_cli_date_format

设置一个 time.strftime() 兼容的字符串，用于在格式化实时日志记录的日期时使用。

[pytest]
log_cli_date_format = %Y-%m-%d %H:%M:%S

有关更多信息，请参阅 实时日志。

log_cli_format

设置一个 logging 兼容的字符串，用于格式化实时日志消息。

[pytest]
log_cli_format = %(asctime)s %(levelname)s %(message)s

有关更多信息，请参阅 实时日志。

log_cli_level

设置应捕获以进行实时日志记录的最低日志消息级别。可以使用整数值或级别的名称。

[pytest]
log_cli_level = INFO

有关更多信息，请参阅 实时日志。

log_date_format

设置一个 time.strftime() 兼容的字符串，用于在格式化日志捕获的日期时使用。

[pytest]
log_date_format = %Y-%m-%d %H:%M:%S

有关更多信息，请参阅 如何管理日志记录。

log_file

设置相对于当前工作目录的文件名，除了活动的其它日志记录工具外，日志消息也应写入该文件。

[pytest]
log_file = logs/pytest-logs.txt

有关更多信息，请参阅 如何管理日志记录。

log_file_date_format

设置一个 time.strftime() 兼容的字符串，用于在格式化日志文件的日期时使用。

[pytest]
log_file_date_format = %Y-%m-%d %H:%M:%S

有关更多信息，请参阅 如何管理日志记录。

log_file_format

设置一个 logging 兼容的字符串，用于格式化重定向到日志文件的日志消息。

[pytest]
log_file_format = %(asctime)s %(levelname)s %(message)s

有关更多信息，请参阅 如何管理日志记录。

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 版本。

# content of pytest.ini
[pytest]
minversion = 3.0  # will fail if we run with pytest-2.8

norecursedirs

设置在递归进行测试发现时要避免的目录基名模式。各个（fnmatch 样式的）模式应用于目录的基名，以决定是否递归到该目录中。模式匹配字符

*       matches everything
?       matches any single character
[seq]   matches any character in seq
[!seq]  matches any char not in seq

默认模式为 '*.egg'、'.*'、'_darcs'、'build'、'CVS'、'dist'、'node_modules'、'venv'、'{arch}'。设置 norecursedirs 将替换默认值。以下是如何避免某些目录的示例

[pytest]
norecursedirs = .svn _build tmp*

这将告诉 pytest 不要查找典型的 subversion 或 sphinx-build 目录，也不要查找任何以 tmp 为前缀的目录。

此外，pytest 会尝试通过是否存在激活脚本来智能地识别和忽略虚拟环境。除非给出 --collect-in-virtualenv 选项，否则在测试收集期间不会考虑任何被认为是虚拟环境根目录的目录。另请注意，norecursedirs 优先于 --collect-in-virtualenv；例如，如果您打算在基目录与 '.*' 匹配的虚拟环境中运行测试，则除了使用 --collect-in-virtualenv 标志外，还*必须*覆盖 norecursedirs。

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

注意

pythonpath 不会影响一些很早就发生的导入，尤其是使用 -p 命令行选项加载的插件。

required_plugins

pytest 运行所必需的插件的空格分隔列表。插件可以在其名称后直接列出，带或不带版本说明符。不允许在不同的版本说明符之间使用空格。如果未找到任何一个插件，则发出错误。

[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 fixture 创建的哪些目录会被保留，具体取决于测试结果。

• all：保留所有测试的目录，无论结果如何。

• failed：仅保留结果为 error 或 failed 的测试的目录。

• none：无论结果如何，目录总是在每次测试结束后删除。

[pytest]
tmp_path_retention_policy = "all"

默认值：all

usefixtures

将应用于所有测试函数的 fixture 列表；这在语义上等同于将 @pytest.mark.usefixtures 标记应用于所有测试函数。

[pytest]
usefixtures =
    clean_db

verbosity_assertions

专门为断言相关的输出设置详细级别，覆盖应用程序范围的级别。

[pytest]
verbosity_assertions = 2

默认为应用程序范围的详细级别（通过 -v 命令行选项）。可以使用特殊值“auto”来显式使用全局详细级别。

verbosity_test_cases

专门为测试用例执行相关的输出设置详细级别，覆盖应用程序范围的级别。

[pytest]
verbosity_test_cases = 2

默认为应用程序范围的详细级别（通过 -v 命令行选项）。可以使用特殊值“auto”来显式使用全局详细级别。

xfail_strict

如果设置为 True，则标记为 @pytest.mark.xfail 但实际成功的测试默认情况下将导致测试套件失败。有关更多信息，请参阅 strict 参数。

[pytest]
xfail_strict = True

命令行标志

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

$ pytest --help
usage: pytest [options] [file_or_dir] [file_or_dir] [...]

positional arguments:
  file_or_dir

general:
  -k EXPRESSION         Only run tests which match the given substring
                        expression. An expression is a Python evaluatable
                        expression where all names are substring-matched
                        against test names and their parent classes.
                        Example: -k 'test_method or test_other' matches all
                        test functions and classes whose name contains
                        'test_method' or 'test_other', while -k 'not
                        test_method' matches those that don't contain
                        'test_method' in their names. -k 'not test_method
                        and not test_other' will eliminate the matches.
                        Additionally keywords are matched to classes and
                        functions containing extra names in their
                        'extra_keyword_matches' set, as well as functions
                        which have names assigned directly to them. The
                        matching is case-insensitive.
  -m MARKEXPR           Only run tests matching given mark expression. For
                        example: -m 'mark1 and not mark2'.
  --markers             show markers (builtin, plugin and per-project ones).
  -x, --exitfirst       Exit instantly on first error or failed test
  --fixtures, --funcargs
                        Show available fixtures, sorted by plugin appearance
                        (fixtures with leading '_' are only shown with '-v')
  --fixtures-per-test   Show fixtures per test
  --pdb                 Start the interactive Python debugger on errors or
                        KeyboardInterrupt
  --pdbcls=modulename:classname
                        Specify a custom interactive Python debugger for use
                        with --pdb.For example:
                        --pdbcls=IPython.terminal.debugger:TerminalPdb
  --trace               Immediately break when running each test
  --capture=method      Per-test capturing method: one of fd|sys|no|tee-sys
  -s                    Shortcut for --capture=no
  --runxfail            Report the results of xfail tests as if they were
                        not marked
  --lf, --last-failed   Rerun only the tests that failed at the last run (or
                        all if none failed)
  --ff, --failed-first  Run all tests, but run the last failures first. This
                        may re-order tests and thus lead to repeated fixture
                        setup/teardown.
  --nf, --new-first     Run tests from new files first, then the rest of the
                        tests sorted by file mtime
  --cache-show=[CACHESHOW]
                        Show cache contents, don't perform collection or
                        tests. Optional argument: glob (default: '*').
  --cache-clear         Remove all cache contents at start of test run
  --lfnf={all,none}, --last-failed-no-failures={all,none}
                        With ``--lf``, determines whether to execute tests
                        when there are no previously (known) failures or
                        when no cached ``lastfailed`` data was found.
                        ``all`` (the default) runs the full test suite
                        again. ``none`` just emits a message about no known
                        failures and exits successfully.
  --sw, --stepwise      Exit on test failure and continue from last failing
                        test next time
  --sw-skip, --stepwise-skip
                        Ignore the first failing test but stop on the next
                        failing test. Implicitly enables --stepwise.

Reporting:
  --durations=N         Show N slowest setup/test durations (N=0 for all)
  --durations-min=N     Minimal duration in seconds for inclusion in slowest
                        list. Default: 0.005.
  -v, --verbose         Increase verbosity
  --no-header           Disable header
  --no-summary          Disable summary
  -q, --quiet           Decrease verbosity
  --verbosity=VERBOSE   Set verbosity. Default: 0.
  -r chars              Show extra test summary info as specified by chars:
                        (f)ailed, (E)rror, (s)kipped, (x)failed, (X)passed,
                        (p)assed, (P)assed with output, (a)ll except passed
                        (p/P), or (A)ll. (w)arnings are enabled by default
                        (see --disable-warnings), 'N' can be used to reset
                        the list. (default: 'fE').
  --disable-warnings, --disable-pytest-warnings
                        Disable warnings summary
  -l, --showlocals      Show locals in tracebacks (disabled by default)
  --no-showlocals       Hide locals in tracebacks (negate --showlocals
                        passed through addopts)
  --tb=style            Traceback print mode
                        (auto/long/short/line/native/no)
  --show-capture={no,stdout,stderr,log,all}
                        Controls how captured stdout/stderr/log is shown on
                        failed tests. Default: all.
  --full-trace          Don't cut any tracebacks (default is to cut)
  --color=color         Color terminal output (yes/no/auto)
  --code-highlight={yes,no}
                        Whether code should be highlighted (only if --color
                        is also enabled). Default: yes.
  --pastebin=mode       Send failed|all info to bpaste.net pastebin service
  --junit-xml=path      Create junit-xml style report file at given path
  --junit-prefix=str    Prepend prefix to classnames in junit-xml output

pytest-warnings:
  -W PYTHONWARNINGS, --pythonwarnings=PYTHONWARNINGS
                        Set which warnings to report, see -W option of
                        Python itself
  --maxfail=num         Exit after first num failures or errors
  --strict-config       Any warnings encountered while parsing the `pytest`
                        section of the configuration file raise errors
  --strict-markers      Markers not registered in the `markers` section of
                        the configuration file raise errors
  --strict              (Deprecated) alias to --strict-markers
  -c FILE, --config-file=FILE
                        Load configuration from `FILE` instead of trying to
                        locate one of the implicit configuration files.
  --continue-on-collection-errors
                        Force test execution even if collection errors occur
  --rootdir=ROOTDIR     Define root directory for tests. Can be relative
                        path: 'root_dir', './root_dir',
                        'root_dir/another_dir/'; absolute path:
                        '/home/user/root_dir'; path with variables:
                        '$HOME/root_dir'.

collection:
  --collect-only, --co  Only collect tests, don't execute them
  --pyargs              Try to interpret all arguments as Python packages
  --ignore=path         Ignore path during collection (multi-allowed)
  --ignore-glob=path    Ignore path pattern during collection (multi-
                        allowed)
  --deselect=nodeid_prefix
                        Deselect item (via node id prefix) during collection
                        (multi-allowed)
  --confcutdir=dir      Only load conftest.py's relative to specified dir
  --noconftest          Don't load any conftest.py files
  --keep-duplicates     Keep duplicate tests
  --collect-in-virtualenv
                        Don't ignore tests in a local virtualenv directory
  --import-mode={prepend,append,importlib}
                        Prepend/append to sys.path when importing test
                        modules and conftest files. Default: prepend.
  --doctest-modules     Run doctests in all .py modules
  --doctest-report={none,cdiff,ndiff,udiff,only_first_failure}
                        Choose another output format for diffs on doctest
                        failure
  --doctest-glob=pat    Doctests file matching pattern, default: test*.txt
  --doctest-ignore-import-errors
                        Ignore doctest collection errors
  --doctest-continue-on-failure
                        For a given doctest, continue to run after the first
                        failure

test session debugging and configuration:
  --basetemp=dir        Base temporary directory for this test run.
                        (Warning: this directory is removed if it exists.)
  -V, --version         Display pytest version and information about
                        plugins. When given twice, also display information
                        about plugins.
  -h, --help            Show help message and configuration info
  -p name               Early-load given plugin module name or entry point
                        (multi-allowed). To avoid loading of plugins, use
                        the `no:` prefix, e.g. `no:doctest`.
  --trace-config        Trace considerations of conftest.py files
  --debug=[DEBUG_FILE_NAME]
                        Store internal tracing debug information in this log
                        file. This file is opened with 'w' and truncated as
                        a result, care advised. Default: pytestdebug.log.
  -o OVERRIDE_INI, --override-ini=OVERRIDE_INI
                        Override ini option with "option=value" style, e.g.
                        `-o xfail_strict=True -o cache_dir=cache`.
  --assert=MODE         Control assertion debugging tools.
                        'plain' performs no assertion debugging.
                        'rewrite' (the default) rewrites assert statements
                        in test modules on import to provide assert
                        expression information.
  --setup-only          Only setup fixtures, do not execute tests
  --setup-show          Show setup of fixtures while executing tests
  --setup-plan          Show what fixtures and tests would be executed but
                        don't execute anything

logging:
  --log-level=LEVEL     Level of messages to catch/display. Not set by
                        default, so it depends on the root/parent log
                        handler's effective level, where it is "WARNING" by
                        default.
  --log-format=LOG_FORMAT
                        Log format used by the logging module
  --log-date-format=LOG_DATE_FORMAT
                        Log date format used by the logging module
  --log-cli-level=LOG_CLI_LEVEL
                        CLI logging level
  --log-cli-format=LOG_CLI_FORMAT
                        Log format used by the logging module
  --log-cli-date-format=LOG_CLI_DATE_FORMAT
                        Log date format used by the logging module
  --log-file=LOG_FILE   Path to a file when logging will be written to
  --log-file-mode={w,a}
                        Log file open mode
  --log-file-level=LOG_FILE_LEVEL
                        Log file logging level
  --log-file-format=LOG_FILE_FORMAT
                        Log format used by the logging module
  --log-file-date-format=LOG_FILE_DATE_FORMAT
                        Log date format used by the logging module
  --log-auto-indent=LOG_AUTO_INDENT
                        Auto-indent multiline messages passed to the logging
                        module. Accepts true|on, false|off or an integer.
  --log-disable=LOGGER_DISABLE
                        Disable a logger by name. Can be passed multiple
                        times.

[pytest] ini-options in the first pytest.ini|tox.ini|setup.cfg|pyproject.toml file found:

  markers (linelist):   Register new markers for test functions
  empty_parameter_set_mark (string):
                        Default marker for empty parametersets
  norecursedirs (args): Directory patterns to avoid for recursion
  testpaths (args):     Directories to search for tests when no files or
                        directories are given on the command line
  filterwarnings (linelist):
                        Each line specifies a pattern for
                        warnings.filterwarnings. Processed after
                        -W/--pythonwarnings.
  consider_namespace_packages (bool):
                        Consider namespace packages when resolving module
                        names during import
  usefixtures (args):   List of default fixtures to be used with this
                        project
  python_files (args):  Glob-style file patterns for Python test module
                        discovery
  python_classes (args):
                        Prefixes or glob names for Python test class
                        discovery
  python_functions (args):
                        Prefixes or glob names for Python test function and
                        method discovery
  disable_test_id_escaping_and_forfeit_all_rights_to_community_support (bool):
                        Disable string escape non-ASCII characters, might
                        cause unwanted side effects(use at your own risk)
  console_output_style (string):
                        Console output: "classic", or with additional
                        progress information ("progress" (percentage) |
                        "count" | "progress-even-when-capture-no" (forces
                        progress even when capture=no)
  verbosity_test_cases (string):
                        Specify a verbosity level for test case execution,
                        overriding the main level. Higher levels will
                        provide more detailed information about each test
                        case executed.
  xfail_strict (bool):  Default for the strict parameter of xfail markers
                        when not given explicitly (default: False)
  tmp_path_retention_count (string):
                        How many sessions should we keep the `tmp_path`
                        directories, according to
                        `tmp_path_retention_policy`.
  tmp_path_retention_policy (string):
                        Controls which directories created by the `tmp_path`
                        fixture are kept around, based on test outcome.
                        (all/failed/none)
  enable_assertion_pass_hook (bool):
                        Enables the pytest_assertion_pass hook. Make sure to
                        delete any previously generated pyc cache files.
  verbosity_assertions (string):
                        Specify a verbosity level for assertions, overriding
                        the main level. Higher levels will provide more
                        detailed explanation when an assertion fails.
  junit_suite_name (string):
                        Test suite name for JUnit report
  junit_logging (string):
                        Write captured log messages to JUnit report: one of
                        no|log|system-out|system-err|out-err|all
  junit_log_passing_tests (bool):
                        Capture log information for passing tests to JUnit
                        report:
  junit_duration_report (string):
                        Duration time to report: one of total|call
  junit_family (string):
                        Emit XML for schema: one of legacy|xunit1|xunit2
  doctest_optionflags (args):
                        Option flags for doctests
  doctest_encoding (string):
                        Encoding used for doctest files
  cache_dir (string):   Cache directory path
  log_level (string):   Default value for --log-level
  log_format (string):  Default value for --log-format
  log_date_format (string):
                        Default value for --log-date-format
  log_cli (bool):       Enable log display during test run (also known as
                        "live logging")
  log_cli_level (string):
                        Default value for --log-cli-level
  log_cli_format (string):
                        Default value for --log-cli-format
  log_cli_date_format (string):
                        Default value for --log-cli-date-format
  log_file (string):    Default value for --log-file
  log_file_mode (string):
                        Default value for --log-file-mode
  log_file_level (string):
                        Default value for --log-file-level
  log_file_format (string):
                        Default value for --log-file-format
  log_file_date_format (string):
                        Default value for --log-file-date-format
  log_auto_indent (string):
                        Default value for --log-auto-indent
  pythonpath (paths):   Add paths to sys.path
  faulthandler_timeout (string):
                        Dump the traceback of all threads if a test takes
                        more than TIMEOUT seconds to finish
  addopts (args):       Extra command line options
  minversion (string):  Minimally required pytest version
  required_plugins (args):
                        Plugins that must be present for pytest to run

Environment variables:
  PYTEST_ADDOPTS           Extra command line options
  PYTEST_PLUGINS           Comma-separated plugins to load during startup
  PYTEST_DISABLE_PLUGIN_AUTOLOAD Set to disable plugin auto-loading
  PYTEST_DEBUG             Set to enable debug tracing of pytest's internals


to see available markers type: pytest --markers
to see available fixtures type: pytest --fixtures
(shown according to specified file_or_dir or current dir if not specified; fixtures with leading '_' are only shown with the '-v' option