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)[source]¶

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

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

>>> 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])[source]¶

使用给定的消息显式地使正在执行的测试失败。

参数:

reason (str) – 向用户显示的失败原因消息。
pytrace (bool) – 如果为 False，则 msg 表示完整的失败信息，并且不会报告 python 回溯。

Raises:

pytest.fail.Exception – 引发的异常。

class pytest.fail.Exception¶: pytest.fail() 引发的异常。

pytest.skip¶

skip(reason[, allow_module_level=False])[source]¶

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

此函数应仅在测试期间（setup、call 或 teardown）或在收集期间通过使用 allow_module_level 标志调用。此函数也可以在 doctests 中调用。

参数:

reason (str) – 向用户显示的跳过原因消息。
allow_module_level (bool) –
允许在模块级别调用此函数。在模块级别引发 skip 异常将停止模块的执行，并阻止收集模块中的所有测试，即使是那些在 skip 调用之前定义的测试。

默认为 False。

Raises:

pytest.skip.Exception – 引发的异常。

注意

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

class pytest.skip.Exception¶: pytest.skip() 引发的异常。

pytest.importorskip¶

importorskip(modname, minversion=None, reason=None, *, exc_type=None)[source]¶

导入并返回请求的模块 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 的默认行为。

Returns:

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

Raises:

pytest.skip.Exception – 如果无法导入模块。

Return type:

Any

示例

docutils = pytest.importorskip("docutils")

在 8.2 版本中添加: exc_type 参数。

pytest.xfail¶

xfail(reason='')[source]¶

使用给定的原因以命令方式将正在执行的测试或 setup 函数标记为 xfail。

此函数应仅在测试期间（setup、call 或 teardown）调用。

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

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

注意

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

Raises:: pytest.xfail.Exception – 引发的异常。

class pytest.xfail.Exception¶: pytest.xfail() 引发的异常。

pytest.exit¶

exit(reason[, returncode=None])[source]¶

退出测试过程。

参数:

reason (str) – 显示为退出 pytest 的原因的消息。reason 仅在 msg 已弃用时才具有默认值。
returncode (int | None) – 退出 pytest 时要使用的返回代码。None 与 0（无错误）相同，与 sys.exit() 相同。

Raises:

pytest.exit.Exception – 引发的异常。

class pytest.exit.Exception¶: pytest.exit() 引发的异常。

pytest.main¶

教程: 从 Python 代码调用 pytest

main(args=None, plugins=None)[source]¶

执行进程内测试运行。

参数:

args (list[str] | PathLike[str] | None) – 命令行参数列表。如果为 None 或未给定，则默认为直接从进程命令行 (sys.argv) 读取参数。
plugins (Sequence[str | object] | None) – 在初始化期间要自动注册的插件对象列表。

Returns:

退出代码。

Return type:

int | ExitCode

pytest.param¶

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

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

@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 (object) – 参数集值的可变参数，按顺序排列。
marks (MarkDecorator | Collection[MarkDecorator | Mark]) – 应用于此参数集的单个标记或标记列表。
id (str | None) – 赋予此参数集的 ID。

pytest.raises¶

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

with raises(expected_exception: type[E] | tuple[type[E], ...], *, match: str | Pattern[str] | None = ...) → RaisesContext[E] as excinfo[source]¶

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

使用 with 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[source]¶

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)[source]¶

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

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

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

pytest.warns¶

教程: 使用 warns 函数断言警告

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

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...

使用 with pytest.mark.parametrize

当使用 pytest.mark.parametrize 时，可以参数化测试，以便某些运行引发警告，而另一些则不引发警告。

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

pytest.freeze_includes¶

教程: 冻结 pytest

freeze_includes()[source]¶

返回 cx_freeze 应包含的 pytest 使用的模块名称列表。

标记¶

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

pytest.mark.filterwarnings¶

教程: @pytest.mark.filterwarnings

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

pytest.mark.filterwarnings(filter)¶

参数:

filter (str) –

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

例如

@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 or str) – 如果应跳过条件，则为 True/False，或者为条件字符串。
reason (str) – 跳过测试函数的原因。

pytest.mark.usefixtures¶

教程: 在类和模块中使用 usefixtures

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

pytest.mark.usefixtures(*names)¶

参数:: args – 要使用的 fixture 的名称，以字符串形式表示。

注意

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

另请注意，此标记应用于 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 或 condition string)。如果为 bool 类型，您还必须指定 reason (参见 condition string)。
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，然后可以使用 fixtures 或 hooks 通过 Node.iter_markers 访问它。 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 参考文档

Fixtures 通过将它们声明为参数名称，被测试函数或其他 fixtures 请求。

需要 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[source]¶

@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 func 将为所有可以看到它的测试激活。如果为 False（默认值），则需要显式引用才能激活 fixture。
ids – ids 序列，每个 id 对应于 params，以便它们成为测试 id 的一部分。如果没有提供 ids，将从 params 自动生成它们。
name – fixture 的名称。默认值为被装饰函数的名称。如果 fixture 在定义它的同一模块中使用，则 fixture 的函数名称将被请求 fixture 的函数参数所遮蔽；解决此问题的一种方法是将装饰的函数命名为 fixture_<fixturename>，然后使用 @pytest.fixture(name='<fixturename>')。

capfd¶

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

capfd()[source]¶

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

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

返回 CaptureFixture[str] 的实例。

示例

def test_system_echo(capfd):
    os.system('echo "hello"')
    captured = capfd.readouterr()
    assert captured.out == "hello\n"

capfdbinary¶

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

capfdbinary()[source]¶

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

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

返回 CaptureFixture[bytes] 的实例。

示例

def test_system_echo(capfdbinary):
    os.system('echo "hello"')
    captured = capfdbinary.readouterr()
    assert captured.out == b"hello\n"

caplog¶

教程: 如何管理日志记录

caplog()[source]¶

访问和控制日志捕获。

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

* 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[source]¶

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

property handler: LogCaptureHandler¶: 获取 fixture 使用的日志处理程序。

get_records(when)[source]¶

获取可能测试阶段之一的日志记录。

参数:: when (Literal['setup', 'call', 'teardown']) – 要从中获取记录的测试阶段。有效值为：“setup”、“call” 和 “teardown”。
Returns:: 给定阶段捕获的记录列表。
Return type:: 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()[source]¶

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

set_level(level, logger=None)[source]¶

为测试期间设置 logger 的阈值级别。

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

在 3.4 版本中更改: 由此函数更改的 logger 的级别将在测试结束时恢复为其初始值。

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

参数:

level (int | str) – 日志级别。
logger (str | None) – 要更新的 logger。如果未给定，则为 root logger。

with at_level(level, logger=None)[source]¶

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

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

参数:

level (int | str) – 日志级别。
logger (str | None) – 要更新的 logger。如果未给定，则为 root logger。

with filtering(filter_)[source]¶

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

参数:: filter – 自定义的 logging.Filter 对象。

在 7.5 版本中新增。

capsys¶

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

capsys()[source]¶

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

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

返回 CaptureFixture[str] 的实例。

示例

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

class CaptureFixture[source]¶

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

readouterr()[source]¶

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

Returns:: 捕获的内容作为一个命名元组返回，包含 out 和 err 字符串属性。
Return type:: CaptureResult

with disabled()[source]¶

在 with 语句块内临时禁用捕获。

capsysbinary¶

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

capsysbinary()[source]¶

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

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

返回 CaptureFixture[bytes] 的实例。

示例

def test_output(capsysbinary):
    print("hello")
    captured = capsysbinary.readouterr()
    assert captured.out == b"hello\n"

config.cache¶

教程: 如何重新运行失败的测试并在测试运行之间保持状态

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

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

config.cache 是 pytest.Cache 的一个实例

final class Cache[source]¶

cache fixture 的实例。

mkdir(name)[source]¶

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

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

在 7.0 版本中添加。

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

get(key, default)[source]¶

返回给定键的缓存值。

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

参数:

key (str) – 必须是 / 分隔的值。通常，第一个名称是您的插件或应用程序的名称。
default – 在缓存未命中或缓存值无效的情况下返回的值。

set(key, value)[source]¶

保存给定键的值。

参数:

key (str) – 必须是 / 分隔的值。通常，第一个名称是您的插件或应用程序的名称。
value (object) – 必须是基本 python 类型的任意组合，包括嵌套类型，如字典列表。

doctest_namespace¶

教程: 如何运行 doctest

doctest_namespace()[source]¶

Fixture，返回一个 dict，它将被注入到 doctest 的命名空间中。

通常，此 fixture 与另一个 autouse fixture 结合使用

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

更多详情: ‘doctest_namespace’ fixture。

monkeypatch¶

教程: 如何 monkeypatch/mock 模块和环境

monkeypatch()[source]¶

一个方便进行 monkey-patching 的 fixture。

此 fixture 提供了这些方法来修改对象、字典或 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()

所有修改将在请求测试函数或 fixture 完成后撤销。raising 参数确定如果 set/deletion 操作没有指定的目标，是否会引发 KeyError 或 AttributeError。

要在包含的作用域中撤销 fixture 所做的修改，请使用 context()。

返回一个 MonkeyPatch 实例。

final class MonkeyPatch[source]¶

帮助方便地 monkeypatch 属性/条目/环境变量/syspath 的类。

由 monkeypatch fixture 返回。

在 6.2 版本中变更: 现在也可以直接用作 pytest.MonkeyPatch()，在 fixture 不可用时使用。在这种情况下，请使用 with MonkeyPatch.context() as mp: 或记住显式调用 undo()。

classmethod with context()[source]¶

上下文管理器，返回一个新的 MonkeyPatch 对象，该对象在退出时撤销在 with 语句块内完成的任何 patching 操作。

示例

import functools


def test_partial(monkeypatch):
    with monkeypatch.context() as m:
        m.setattr(functools, "partial", 3)

在需要在测试结束前撤销某些补丁的情况下很有用，例如 mocking 可能会破坏 pytest 自身的 stdlib 函数（有关示例，请参见 #3290）。

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

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

在 target 上设置属性值，并记住旧值。

例如

import os

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

上面的代码将 os.getcwd() 函数替换为一个始终返回 "/" 的 lambda。

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

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

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

在哪里打补丁

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

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

delattr(target, name=<notset>, raising=True)[source]¶

从 target 中删除属性 name。

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

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

setitem(dic, name, value)[source]¶

将字典条目 name 设置为 value。

delitem(dic, name, raising=True)[source]¶

从字典中删除 name。

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

setenv(name, value, prepend=None)[source]¶

将环境变量 name 设置为 value。

如果 prepend 是一个字符，则读取当前环境变量值，并将 value 与 prepend 字符连接后前置。

delenv(name, raising=True)[source]¶

从环境中删除 name。

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

syspath_prepend(path)[source]¶

将 path 前置到 sys.path 导入位置列表。

chdir(path)[source]¶

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

参数:: path (str | PathLike[str]) – 要更改为的路径。

undo()[source]¶

撤销之前的更改。

此调用会消耗撤销堆栈。第二次调用它没有任何效果，除非您在 undo 调用后执行更多 monkeypatching 操作。

通常无需调用 undo()，因为它会在 tear-down 期间自动调用。

注意

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

建议改用 context()。

pytestconfig¶

pytestconfig()[source]¶

会话作用域的 fixture，返回会话的 pytest.Config 对象。

示例

def test_foo(pytestconfig):
    if pytestconfig.get_verbosity() > 0:
        ...

pytester¶

在 6.2 版本中新增。

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

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

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

pytest_plugins = "pytester"

final class Pytester[source]¶

用于编写测试/配置文件，隔离执行 pytest 以及匹配预期输出的功能，非常适合 pytest 插件的黑盒测试。

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

exception TimeoutExpired[source]¶

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

property path: Path¶: 用于创建文件/从中运行测试等的临时目录路径。

make_hook_recorder(pluginmanager)[source]¶

为 PytestPluginManager 创建一个新的 HookRecorder。

chdir()[source]¶

这在实例化时自动完成。

makefile(ext, *args, **kwargs)[source]¶

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

参数:

ext (str) – 文件应使用的扩展名，包括点，例如 .py。
args (str) – 所有 args 都被视为字符串，并使用换行符连接。结果将作为内容写入文件。文件名基于请求此 fixture 的测试函数。
kwargs (str) – 每个关键字都是一个文件名，而其值将作为该文件的内容写入。

Returns:

第一个创建的文件。

Return type:

路径

示例

pytester.makefile(".txt", "line1", "line2")

pytester.makefile(".ini", pytest="[pytest]\naddopts=-rs\n")

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

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

makeconftest(source)[source]¶

写入一个 conftest.py 文件。

参数:: source (str) – 内容。
Returns:: conftest.py 文件。
Return type:: 路径

makeini(source)[source]¶

写入一个 tox.ini 文件。

参数:: source (str) – 内容。
Returns:: tox.ini 文件。
Return type:: 路径

getinicfg(source)[source]¶

从 tox.ini 配置文件中返回 pytest section。

makepyprojecttoml(source)[source]¶

写入一个 pyproject.toml 文件。

参数:: source (str) – 内容。
Returns:: pyproject.ini 文件。
Return type:: 路径

在 6.0 版本中添加。

makepyfile(*args, **kwargs)[source]¶

带有 .py 扩展名的 .makefile() 的快捷方式。

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

示例

def test_something(pytester):
    # Initial file is created test_something.py.
    pytester.makepyfile("foobar")
    # To create multiple files, pass kwargs accordingly.
    pytester.makepyfile(custom="foobar")
    # At this point, both 'test_something.py' & 'custom.py' exist in the test directory.

maketxtfile(*args, **kwargs)[source]¶

带有 .txt 扩展名的 .makefile() 的快捷方式。

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

示例

def test_something(pytester):
    # Initial file is created test_something.txt.
    pytester.maketxtfile("foobar")
    # To create multiple files, pass kwargs accordingly.
    pytester.maketxtfile(custom="foobar")
    # At this point, both 'test_something.txt' & 'custom.txt' exist in the test directory.

syspathinsert(path=None)[source]¶

将目录前置到 sys.path，默认为 path。

当此对象在每个测试结束时消亡时，这将自动撤消。

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

mkdir(name)[source]¶

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

参数:: name (str | PathLike[str]) – 目录名称，相对于 pytester 路径。
Returns:: 创建的目录。
Return type:: pathlib.Path

mkpydir(name)[source]¶

创建一个新的 python 包。

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

copy_example(name=None)[source]¶

从项目目录复制文件到 testdir 中。

参数:: name (str | None) – 要复制的文件名。
Returns:: 复制的目录的路径（在 self.path 内）。
Return type:: pathlib.Path

getnode(config, arg)[source]¶

获取文件的 collection 节点。

参数:

config (Config) – 一个 pytest config。请参阅 parseconfig() 和 parseconfigure() 以创建它。
arg (str | PathLike[str]) – 文件的路径。

Returns:

节点。

Return type:

Collector | Item

getpathnode(path)[source]¶

返回文件的 collection 节点。

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

参数:: path (str | PathLike[str]) – 文件的路径。
Returns:: 节点。
Return type:: Collector | Item

genitems(colitems)[source]¶

从 collection 节点生成所有测试项。

这将递归进入 collection 节点，并返回其中包含的所有测试项的列表。

参数:: colitems (Sequence[Item | Collector]) – collection 节点。
Returns:: 收集的项。
Return type:: list[Item]

runitem(source)[source]¶

运行 “test_func” Item。

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

inline_runsource(source, *cmdlineargs)[source]¶

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

此运行将 “source” 写入临时文件，并在其上运行 pytest.main()，返回结果的 HookRecorder 实例。

参数:

source (str) – 测试模块的源代码。
cmdlineargs – 要使用的任何额外的命令行参数。

inline_genitems(*args)[source]¶

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

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

inline_run(*args, plugins=(), no_reraise_ctrlc=False)[source]¶

在进程内运行 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)[source]¶

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

runpytest(*args, **kwargs)[source]¶

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

parseconfig(*args)[source]¶

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

这会在 _pytest.config 中调用 pytest 引导代码，以创建一个新的 pytest.PytestPluginManager 并调用 pytest_cmdline_parse hook 来创建一个新的 pytest.Config 实例。

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

parseconfigure(*args)[source]¶

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

返回一个新的 pytest.Config 实例，类似于 parseconfig()，但也调用 pytest_configure hook。

getitem(source, funcname='test_func')[source]¶

返回测试函数的测试项。

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

参数:

source (str | PathLike[str]) – 模块源代码。
funcname (str) – 要为其返回测试项的测试函数名称。

Returns:

测试项。

Return type:

Item

getitems(source)[source]¶

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

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

getmodulecol(source, configargs=(), *, withinit=False)[source]¶

返回 source 的模块 collection 节点。

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

参数:

source (str | PathLike[str]) – 要收集的模块的源代码。
configargs – 要传递给 parseconfigure() 的任何额外参数。
withinit (bool) – 是否也写入一个 __init__.py 文件到同一目录，以确保它是一个包。

collect_by_name(modcol, name)[source]¶

从模块 collection 返回名称的 collection 节点。

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

参数:

modcol (Collector) – 模块 collection 节点；请参阅 getmodulecol()。
name (str) – 要返回的节点的名称。

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

调用 subprocess.Popen。

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

您可能想要使用 run() 来代替。

run(*cmdargs, timeout=None, stdin=NotSetType.token)[source]¶

运行带有参数的命令。

使用 subprocess.Popen 运行进程，保存 stdout 和 stderr。

参数:

cmdargs (str | PathLike[str]) – 传递给 subprocess.Popen 的参数序列，其中类路径对象会自动转换为 str。
timeout (float | None) – 超时时间（以秒为单位），超过该时间将超时并引发 Pytester.TimeoutExpired。
stdin (_pytest.compat.NotSetType | bytes | IO[Any] | int) –
可选的标准输入。
- 如果它是 CLOSE_STDIN（默认值），则此方法使用 stdin=subprocess.PIPE 调用 subprocess.Popen，并且在启动新命令后立即关闭标准输入。
- 如果它是 bytes 类型，则这些字节将发送到命令的标准输入。
- 否则，它将传递给 subprocess.Popen。在这种情况下，有关更多信息，请查阅 subprocess.Popen 中 stdin 参数的文档。

Returns:

结果。

Return type:

RunResult

runpython(script)[source]¶

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

runpython_c(command)[source]¶

运行 python -c "command"。

runpytest_subprocess(*args, timeout=None)[source]¶

将 pytest 作为带有给定参数的子进程运行。

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

参数:

args (str | PathLike[str]) – 传递给 pytest 子进程的参数序列。
timeout (float | None) – 超时时间（以秒为单位），超过该时间将超时并引发 Pytester.TimeoutExpired。

Returns:

结果。

Return type:

RunResult

spawn_pytest(string, expect_timeout=10.0)[source]¶

使用 pexpect 运行 pytest。

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

返回 pexpect 子进程。

spawn(cmd, expect_timeout=10.0)[source]¶

使用 pexpect 运行命令。

返回 pexpect 子进程。

final class RunResult[source]¶

从 Pytester 运行命令的结果。

ret: int | ExitCode¶: 返回值。

outlines¶: 从 stdout 捕获的行列表。

errlines¶: 从 stderr 捕获的行列表。

stdout¶

LineMatcher 类型的 stdout。

例如，使用 str(stdout) 重构 stdout，或者使用常用的 stdout.fnmatch_lines() 方法。

stderr¶: LineMatcher 类型的 stderr。

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 (Sequence[str]) – 要匹配的字符串模式。
consecutive (bool) – 连续匹配行？

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[源代码]¶

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

Hook 记录器由 Pytester 创建。

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

getcalls(names)[源代码]¶

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

matchreport(inamepart='', names=('pytest_runtest_logreport', 'pytest_collectreport'), when=None)[源代码]¶

返回其点式导入路径匹配的 testreport。

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¶

教程: 记录警告

recwarn()[源代码]¶

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

有关警告类别的更多信息，请参阅如何捕获警告。

class WarningsRecorder[源代码]¶

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

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

改编自 warnings.catch_warnings。

注意

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

property list: list[WarningMessage]¶: 记录的警告列表。

__getitem__(i)[源代码]¶

按索引获取记录的警告。

__iter__()[源代码]¶

迭代记录的警告。

__len__()[源代码]¶

记录的警告的数量。

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 config 对象。

property function¶: 如果请求具有 function 作用域，则为测试函数对象。

property cls¶: 收集测试函数的类（可以为 None）。

property instance¶: 收集测试函数的实例（可以为 None）。

property module¶: 收集测试函数的 Python 模块对象。

property path: Path¶: 收集测试函数的路径。

property keywords: MutableMapping[str, Any]¶: 底层节点的关键字/标记字典。

property session: Session¶: Pytest session 对象。

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 名称。
Raises:: pytest.FixtureLookupError – 如果找不到给定的 fixture。

testdir¶

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

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

final class Testdir[source]

类似于 Pytester，但此类适用于旧式的 legacy_path 对象。

所有方法都只是转发到一个内部的 Pytester 实例，并在必要时将结果转换为 legacy_path 对象。

exception TimeoutExpired

property tmpdir: LocalPath: 测试执行的临时目录。

make_hook_recorder(pluginmanager)[source]

参见 Pytester.make_hook_recorder()。

chdir()[source]

参见 Pytester.chdir()。

makefile(ext, *args, **kwargs)[source]

参见 Pytester.makefile()。

makeconftest(source)[source]

参见 Pytester.makeconftest()。

makeini(source)[source]

参见 Pytester.makeini()。

getinicfg(source)[source]

参见 Pytester.getinicfg()。

makepyprojecttoml(source)[source]

参见 Pytester.makepyprojecttoml()。

makepyfile(*args, **kwargs)[source]

参见 Pytester.makepyfile()。

maketxtfile(*args, **kwargs)[source]

参见 Pytester.maketxtfile()。

syspathinsert(path=None)[source]

参见 Pytester.syspathinsert()。

mkdir(name)[source]

参见 Pytester.mkdir()。

mkpydir(name)[source]

参见 Pytester.mkpydir()。

copy_example(name=None)[source]

参见 Pytester.copy_example()。

getnode(config, arg)[source]

参见 Pytester.getnode()。

getpathnode(path)[source]: 参见 Pytester.getpathnode()。

genitems(colitems)[source]

参见 Pytester.genitems()。

runitem(source)[source]: 参见 Pytester.runitem()。

inline_runsource(source, *cmdlineargs)[source]: 参见 Pytester.inline_runsource()。

inline_genitems(*args)[source]: 参见 Pytester.inline_genitems()。

inline_run(*args, plugins=(), no_reraise_ctrlc=False)[source]

参见 Pytester.inline_run()。

runpytest_inprocess(*args, **kwargs)[source]

参见 Pytester.runpytest_inprocess()。

runpytest(*args, **kwargs)[source]

参见 Pytester.runpytest()。

parseconfig(*args)[source]

参见 Pytester.parseconfig()。

parseconfigure(*args)[source]

参见 Pytester.parseconfigure()。

getitem(source, funcname='test_func')[source]: 参见 Pytester.getitem()。

getitems(source)[source]: 参见 Pytester.getitems()。

getmodulecol(source, configargs=(), withinit=False)[source]: 参见 Pytester.getmodulecol()。

collect_by_name(modcol, name)[source]

参见 Pytester.collect_by_name()。

popen(cmdargs, stdout=-1, stderr=-1, stdin=NotSetType.token, **kw)[source]: 参见 Pytester.popen()。

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

参见 Pytester.run()。

runpython(script)[source]

参见 Pytester.runpython()。

runpython_c(command)[source]: 参见 Pytester.runpython_c()。

runpytest_subprocess(*args, timeout=None)[source]

参见 Pytester.runpytest_subprocess()。

spawn_pytest(string, expect_timeout=10.0)[source]

参见 Pytester.spawn_pytest()。

spawn(cmd, expect_timeout=10.0)[source]

参见 Pytester.spawn()。

tmp_path¶

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

tmp_path()[source]¶

返回一个临时目录（作为 pathlib.Path 对象），该目录对于每个测试函数调用都是唯一的。临时目录创建为基本临时目录的子目录，具有可配置的保留策略，如临时目录位置和保留中所述。

tmp_path_factory¶

教程： tmp_path_factory fixture 示例

tmp_path_factory 是 TempPathFactory 的一个实例

final class TempPathFactory[source]¶

用于在公共基本临时目录下创建临时目录的工厂，如临时目录位置和保留中所述。

mktemp(basename, numbered=True)[source]¶

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

参数:

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

Returns:

新目录的路径。

Return type:

路径

getbasetemp()[source]¶

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

Returns:: 基本临时目录。
Return type:: 路径

tmpdir¶

教程： tmpdir 和 tmpdir_factory fixtures

tmpdir()¶

返回一个临时目录（作为 legacy_path 对象），该目录对于每个测试函数调用都是唯一的。临时目录创建为基本临时目录的子目录，具有可配置的保留策略，如临时目录位置和保留中所述。

注意

现在，建议使用 tmp_path。

关于 tmpdir 和 tmpdir_factory fixtures.

tmpdir_factory¶

教程： tmpdir 和 tmpdir_factory fixtures

tmpdir_factory 是 TempdirFactory 的一个实例

final class TempdirFactory[source]¶

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

注意

现在，建议使用 tmp_path_factory。

关于 tmpdir 和 tmpdir_factory fixtures.

mktemp(basename, numbered=True)[source]¶

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

getbasetemp()[source]¶

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

Hooks¶

教程：编写插件

引用可以通过 conftest.py 文件和插件实现的所有 hooks。

@pytest.hookimpl¶

@pytest.hookimpl¶

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

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

@pytest.hookspec¶

@pytest.hookspec¶

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

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

引导 hooks¶

为尽早注册的插件（内部和第三方插件）调用的引导 hooks。

pytest_load_initial_conftests(early_config, parser, args)[source]¶

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

参数:

early_config (Config) – pytest 配置对象。
args (list[str]) – 在命令行上传递的参数。
parser (Parser) – 用于添加命令行选项。

在 conftest 插件中使用¶

此 hook 不会为 conftest 文件调用。

pytest_cmdline_parse(pluginmanager, args)[source]¶

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

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

注意

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

参数:

pluginmanager (PytestPluginManager) – pytest 插件管理器。
args (list[str]) – 命令行上传递的参数列表。

Returns:

一个 pytest 配置对象。

Return type:

Config | None

在 conftest 插件中使用¶

此 hook 不会为 conftest 文件调用。

pytest_cmdline_main(config)[source]¶

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

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

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

参数:: config (Config) – pytest 配置对象。
Returns:: 退出代码。
Return type:: ExitCode | int | None

在 conftest 插件中使用¶

此钩子仅为初始 conftest 调用。

初始化钩子¶

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

pytest_addoption(parser, pluginmanager)[source]¶

参数:

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 时会立即调用它。

此钩子仅为初始 conftest 调用。

pytest_addhooks(pluginmanager)[source]¶

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

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

注意

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

在 conftest 插件中使用¶

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

pytest_configure(config)[source]¶

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

注意

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

参数:: config (Config) – pytest 配置对象。

在 conftest 插件中使用¶

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

pytest_unconfigure(config)[source]¶

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

参数:: config (Config) – pytest 配置对象。

在 conftest 插件中使用¶

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

pytest_sessionstart(session)[source]¶

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

参数:: session (Session) – pytest session 对象。

在 conftest 插件中使用¶

此钩子仅为初始 conftest 调用。

pytest_sessionfinish(session, exitstatus)[source]¶

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

参数:

session (Session) – pytest session 对象。
exitstatus (int | ExitCode) – pytest 将返回给系统的状态。

在 conftest 插件中使用¶

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

pytest_plugin_registered(plugin, plugin_name, manager)[source]¶

注册了一个新的 pytest 插件。

参数:

plugin (_PluggyPlugin) – 插件模块或实例。
plugin_name (str) – 插件注册的名称。
manager (PytestPluginManager) – pytest 插件管理器。

注意

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

在 conftest 插件中使用¶

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

收集钩子¶

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

pytest_collection(session)[source]¶

为给定的 session 执行收集阶段。

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

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

从 session 作为初始收集器开始

pytest_collectstart(collector)

report = pytest_make_collect_report(collector)

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

对于每个收集的节点

如果是 item，则 pytest_itemcollected(item)

如果是 collector，则递归进入。

pytest_collectreport(report)

pytest_collection_modifyitems(session, config, items)

对于任何取消选择的 item，pytest_deselected(items) （可能被多次调用）

pytest_collection_finish(session)
将 session.items 设置为收集的 item 列表
将 session.testscollected 设置为收集的 item 数量

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

参数:: session (Session) – pytest session 对象。

在 conftest 插件中使用¶

此钩子仅为初始 conftest 调用。

pytest_ignore_collect(collection_path, path, config)[source]¶

返回 True 以忽略此路径进行收集。

返回 None 以让其他插件忽略此路径进行收集。

返回 False 将强制不忽略此路径进行收集，而不给其他插件忽略此路径的机会。

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

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

参数:

collection_path (pathlib.Path) – 要分析的路径。
path (LEGACY_PATH) – 要分析的路径（已弃用）。
config (Config) – pytest 配置对象。

在 7.0.0 版本中变更: collection_path 参数已添加，作为 pathlib.Path 等效于 path 参数。path 参数已被弃用。

在 conftest 插件中使用¶

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

pytest_collect_directory(path, parent)[source]¶

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

在 8.0 版本中添加。

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

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

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

参数:: path (pathlib.Path) – 要分析的路径。

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

在 conftest 插件中使用¶

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

pytest_collect_file(file_path, path, parent)[source]¶

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

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

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

参数:

file_path (pathlib.Path) – 要分析的路径。
path (LEGACY_PATH) – 要收集的路径（已弃用）。

在 7.0.0 版本中变更: file_path 参数已添加，作为 pathlib.Path 等效于 path 参数。path 参数已被弃用。

在 conftest 插件中使用¶

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

pytest_pycollect_makemodule(module_path, path, parent)[source]¶

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

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

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

参数:

module_path (pathlib.Path) – 要收集的模块的路径。
path (LEGACY_PATH) – 要收集的模块的路径（已弃用）。

在 7.0.0 版本中变更: module_path 参数已添加，作为 pathlib.Path 等效于 path 参数。

path 参数已被弃用，推荐使用 fspath。

在 conftest 插件中使用¶

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

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

pytest_pycollect_makeitem(collector, name, obj)[source]¶

为模块中的 Python 对象返回自定义 item/collector，如果无关，则返回 None。

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

参数:

collector (Module | Class) – 模块/类收集器。
name (str) – 模块/类中对象的名称。
obj (object) – 对象。

Returns:

创建的 item/collector。

Return type:

None | Item | Collector | list[Item | Collector]

在 conftest 插件中使用¶

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

pytest_generate_tests(metafunc)[source]¶

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

参数:: metafunc (Metafunc) – 测试函数的 Metafunc 助手。

在 conftest 插件中使用¶

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

pytest_make_parametrize_id(config, val, argname)[source]¶

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

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

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

参数:

config (Config) – pytest 配置对象。
val (object) – 参数化的值。
argname (str) – pytest 产生的自动参数名称。

在 conftest 插件中使用¶

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

影响测试跳过的钩子

pytest_markeval_namespace(config)[source]¶

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

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

在 6.2 版本中新增。

参数:: config (Config) – pytest 配置对象。
Returns:: 要添加的其他全局变量的字典。
Return type:: dict[str, Any]

在 conftest 插件中使用¶

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

收集完成后，您可以修改 item 的顺序，删除或以其他方式修改测试 item

pytest_collection_modifyitems(session, config, items)[source]¶

在执行收集后调用。可以就地过滤或重新排序 item。

当 item 被取消选择（从 items 中过滤掉）时，必须显式调用钩子 pytest_deselected 与取消选择的 item，以正确通知其他插件，例如使用 config.hook.pytest_deselected(items=deselected_items)。

参数:

session (Session) – pytest session 对象。
config (Config) – pytest 配置对象。
items (list[Item]) – item 对象列表。

在 conftest 插件中使用¶

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

注意

如果此钩子在 conftest.py 文件中实现，它总是接收所有收集的 item，而不仅仅是它实现的 conftest.py 下的 item。

pytest_collection_finish(session)[source]¶

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

参数:: session (Session) – pytest session 对象。

在 conftest 插件中使用¶

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

测试运行 (runtest) 钩子¶

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

pytest_runtestloop(session)[source]¶

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

除非收集失败或设置了 collectonly pytest 选项，否则默认钩子实现为 session 中收集的所有 item (session.items) 执行 runtest 协议。

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

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

参数:: session (Session) – pytest session 对象。

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

在 conftest 插件中使用¶

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

pytest_runtest_protocol(item, nextitem)[source]¶

为单个测试 item 执行 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 协议的测试 item。
nextitem (Item | None) – 计划为下一个测试 item (如果这是我的朋友的结局，则为 None)。

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

在 conftest 插件中使用¶

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

pytest_runtest_logstart(nodeid, location)[source]¶

在开始运行单个 item 的 runtest 协议时调用。

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

参数:

nodeid (str) – item 的完整节点 ID。
location (tuple[str, int | None, str]) – (filename, lineno, testname) 的元组，其中 filename 是相对于 config.rootpath 的文件路径，lineno 是从 0 开始的行号。

在 conftest 插件中使用¶

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

pytest_runtest_logfinish(nodeid, location)[source]¶

在运行单个 item 的 runtest 协议结束时调用。

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

参数:

nodeid (str) – item 的完整节点 ID。
location (tuple[str, int | None, str]) – (filename, lineno, testname) 的元组，其中 filename 是相对于 config.rootpath 的文件路径，lineno 是从 0 开始的行号。

在 conftest 插件中使用¶

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

pytest_runtest_setup(item)[source]¶

调用以执行测试 item 的 setup 阶段。

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

参数:: item (Item) – item。

在 conftest 插件中使用¶

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

pytest_runtest_call(item)[source]¶

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

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

参数:: item (Item) – item。

在 conftest 插件中使用¶

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

pytest_runtest_teardown(item, nextitem)[源代码]¶

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

默认实现运行 finalizer，并在 item 及其所有父级（需要被 teardown）上调用 teardown()。这包括运行 item 所需 fixture 的 teardown 阶段（如果它们超出作用域）。

参数:

item (Item) – item。
nextitem (Item | None) – 计划成为下一个测试项的项 (如果没有计划进一步的测试项，则为 None)。此参数用于执行精确的 teardown，即仅调用足够的 finalizer，以便 nextitem 只需要调用 setup 函数。

在 conftest 插件中使用¶

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

pytest_runtest_makereport(item, call)[源代码]¶

调用以为测试项的 setup、call 和 teardown runtest 阶段创建 TestReport。

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

参数:

item (Item) – item。
call (CallInfo[None]) – 阶段的 CallInfo。

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

在 conftest 插件中使用¶

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

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

pytest_pyfunc_call(pyfuncitem)[源代码]¶

调用底层测试函数。

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

参数:: pyfuncitem (Function) – 函数项。

在 conftest 插件中使用¶

任何 conftest 文件都可以实现此钩子。对于给定的 item，仅咨询 item 目录及其父目录中的 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) – item。

在 conftest 插件中使用¶

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

pytest_collectreport(report)[源代码]¶

收集器完成收集。

参数:: report (CollectReport) – 收集报告。

在 conftest 插件中使用¶

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

pytest_deselected(items)[源代码]¶

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

请注意，此钩子对于插件有两个集成方面

它可以被实现，以接收取消选择项的通知
当项被取消选择时，必须从 pytest_collection_modifyitems 实现中调用（以正确通知其他插件）。

可能会被多次调用。

参数:: items (Sequence[Item]) – 项。

在 conftest 插件中使用¶

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

pytest_report_header(config, start_path, startdir)[源代码]¶

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

参数:

config (Config) – pytest 配置对象。
start_path (pathlib.Path) – 起始目录。
startdir (LEGACY_PATH) – 起始目录（已弃用）。

注意

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

在 7.0.0 版本中变更: start_path 参数被添加为 pathlib.Path，等同于 startdir 参数。startdir 参数已被弃用。

在 conftest 插件中使用¶

此钩子仅为初始 conftest 调用。

pytest_report_collectionfinish(config, start_path, startdir, items)[源代码]¶

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

这些字符串将显示在标准的 “collected X items” 消息之后。

在 3.2 版本中添加。

参数:

config (Config) – pytest 配置对象。
start_path (pathlib.Path) – 起始目录。
startdir (LEGACY_PATH) – 起始目录（已弃用）。
items (Sequence[Item]) – 将要执行的 pytest 项的列表；此列表不应被修改。

注意

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

在 7.0.0 版本中变更: start_path 参数被添加为 pathlib.Path，等同于 startdir 参数。startdir 参数已被弃用。

在 conftest 插件中使用¶

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

pytest_report_teststatus(report, config)[源代码]¶

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

结果类别是用于计数结果的类别，例如 “passed”、“skipped”、“error” 或空字符串。

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

详细单词在详细模式下测试进行时显示，例如 “PASSED”、“SKIPPED”、“ERROR” 或空字符串。

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

参数:

report (CollectReport | TestReport) – 要返回其状态的报告对象。
config (Config) – pytest 配置对象。

Returns:

测试状态。

Return type:

TestShortLogReport | tuple[str, str, 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) – 将报告回 OS 的退出状态。
config (Config) – pytest 配置对象。

在 4.2 版本中添加: config 参数。

在 conftest 插件中使用¶

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

pytest_fixture_setup(fixturedef, request)[源代码]¶

执行 fixture setup 执行。

参数:

fixturedef (FixtureDef[Any]) – fixture 定义对象。
request (SubRequest) – fixture 请求对象。

Returns:

调用 fixture 函数的返回值。

Return type:

object | None

在第一个非 None 结果处停止，请参阅 firstresult: 在第一个非 None 结果处停止。

注意

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

在 conftest 插件中使用¶

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

pytest_fixture_post_finalizer(fixturedef, request)[源代码]¶

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

参数:

fixturedef (FixtureDef[Any]) – fixture 定义对象。
request (SubRequest) – fixture 请求对象。

在 conftest 插件中使用¶

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

pytest_warning_recorded(warning_message, when, nodeid, location)[源代码]¶

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

参数:

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)[源代码]¶

处理为项的 setup、call 和 teardown runtest 阶段生成的 TestReport。

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

在 conftest 插件中使用¶

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

断言相关的钩子

pytest_assertrepr_compare(config, op, left, right)[源代码]¶

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

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

参数:

config (Config) – pytest 配置对象。
op (str) – 运算符，例如 "==", "!=", "not in"。
left (object) – 左操作数。
right (object) – 右操作数。

在 conftest 插件中使用¶

任何 conftest 文件都可以实现此钩子。对于给定的 item，仅咨询 item 目录及其父目录中的 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 文件都可以实现此钩子。对于给定的 item，仅咨询 item 目录及其父目录中的 conftest 文件。

调试/交互钩子¶

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

pytest_internalerror(excrepr, excinfo)[源代码]¶

为内部错误调用。

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

参数:

excrepr (ExceptionRepr) – 异常 repr 对象。
excinfo (ExceptionInfo[BaseException]) – 异常信息。

在 conftest 插件中使用¶

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

pytest_keyboard_interrupt(excinfo)[源代码]¶

为键盘中断调用。

参数:: excinfo (ExceptionInfo[KeyboardInterrupt | Exit]) – 异常信息。

在 conftest 插件中使用¶

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

pytest_exception_interact(node, call, report)[源代码]¶

当引发异常时调用，该异常可能可以交互式处理。

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

可能在项的 runtest 期间调用（参见 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: LEGACY_PATH¶: path 属性的 LEGACY_PATH 副本。旨在用于尚未迁移到 pathlib.Path 的方法，例如 Item.reportinfo。将在未来的版本中弃用，建议改用 path。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

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)[source]¶

节点的公共构造函数。

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

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

参数:: parent (Node) – 此节点的父节点。

property ihook: HookRelay¶: fspath 敏感的钩子代理，用于调用 pytest 钩子。

warn(warning)[source]¶

为此节点发出警告。

警告将在测试会话结束后显示，除非显式禁止显示。

参数:: warning (Warning) – 要发出的警告实例。
Raises:: ValueError – 如果 warning 实例不是 Warning 的子类。

用法示例

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

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

property nodeid: str¶: 一个使用 :: 分隔的字符串，表示其收集树地址。

for ... in iter_parents()[source]¶

迭代所有父级收集器，从自身开始并包括自身，直到收集树的根节点。

版本 8.1 中新增。

listchain()[source]¶

返回一个列表，其中包含从收集树的根节点开始到自身（包括自身）的所有父级收集器。

add_marker(marker, append=True)[source]¶

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

参数:

marker (str | MarkDecorator) – 标记。
append (bool) – 是否追加标记，或者将其前置。

iter_markers(name=None)[source]¶

迭代节点的所有标记。

参数:: name (str | None) – 如果给定，则按名称属性过滤结果。
Returns:: 节点标记的迭代器。
Return type:: Iterator[Mark]

for ... in iter_markers_with_node(name=None)[source]¶

迭代节点的所有标记。

参数:: name (str | None) – 如果给定，则按名称属性过滤结果。
Returns:: （节点，标记）元组的迭代器。
Return type:: Iterator[tuple[Node, Mark]]

get_closest_marker(name: str) → Mark | None[source]¶

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

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

参数:

default – 如果未找到标记，则返回的默认值。
name – 要按名称过滤。

listextrakeywords()[source]¶

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

addfinalizer(fin)[source]¶

注册一个函数，以便在此节点最终确定时无参数调用它。

此方法只能在此节点在 setup 链中处于活动状态时调用，例如在 self.setup() 期间。

getparent(cls)[source]¶

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

参数:: cls (type[_NodeType]) – 要搜索的节点类。
Returns:: 如果找到，则返回节点。
Return type:: _NodeType | None

repr_failure(excinfo, style=None)[source]¶

返回收集或测试失败的表示。

另请参阅

使用非 Python 测试

参数:: excinfo (ExceptionInfo[BaseException]) – 失败的异常信息。

Collector¶

class Collector[source]¶

基类: Node, ABC

所有收集器的基类。

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

exception CollectError[source]¶

基类: Exception

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

abstractmethod collect()[source]¶

为此收集器收集子项（测试项和收集器）。

repr_failure(excinfo)[source]¶

返回收集失败的表示。

参数:: excinfo (ExceptionInfo[BaseException]) – 失败的异常信息。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

Item¶

class Item[source]¶

基类: Node, ABC

所有测试调用项的基类。

请注意，对于单个函数，可能存在多个测试调用项。

user_properties: list[tuple[str, object]]¶: 一个 (名称, 值) 元组的列表，其中包含此测试的用户定义属性。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

abstractmethod runtest()[source]¶

为此测试项运行测试用例。

必须由子类实现。

另请参阅

使用非 Python 测试

add_report_section(when, key, content)[source]¶

添加一个新的报告部分，类似于内部添加 stdout 和 stderr 捕获输出的方式

item.add_report_section("call", "stdout", "report section contents")

参数:

when (str) – 可能的捕获状态之一，"setup"、"call"、"teardown"。
key (str) – 部分的名称，可以随意自定义。Pytest 内部使用 "stdout" 和 "stderr"。
content (str) – 完整的内容字符串。

reportinfo()[source]¶

获取此测试项的用于测试报告的位置信息。

返回一个包含三个元素的元组

测试的路径（默认为 self.path）
测试的从 0 开始的行号（默认为 None）
要显示的测试名称（默认为 ""）

另请参阅

使用非 Python 测试

property location: tuple[str, int | None, str]¶: 为此测试项返回 (relfspath, lineno, testname) 元组，其中 relfspath 是相对于 config.rootpath 的文件路径，而 lineno 是从 0 开始的行号。

File¶

class File[source]¶

基类: FSCollector, ABC

用于从文件收集测试的基类。

使用非 Python 测试.

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

FSCollector¶

class FSCollector[source]¶

基类: Collector, ABC

文件系统收集器的基类。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

classmethod from_parent(parent, *, fspath=None, path=None, **kw)[source]¶

公共构造函数。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

Session¶

final class Session[source]¶

基类: Collector

收集树的根节点。

Session 收集作为参数传递给 pytest 的初始路径。

exception Interrupted¶

基类: KeyboardInterrupt

表示测试运行被中断的信号。

exception Failed¶

基类: Exception

表示测试运行因失败而停止的信号。

property startpath: Path¶: pytest 被调用的路径。

版本 7.0.0 新增。

isinitpath(path, *, with_parents=False)[source]¶

路径是否为初始路径？

初始路径是在命令行中显式传递给 pytest 的路径。

参数:: with_parents (bool) – 如果设置，当路径是初始路径的父路径时，也返回 True。

版本 8.0 变更: 添加了 with_parents 参数。

perform_collect(args: Sequence[str] | None = None, genitems: Literal[True] = True) → Sequence[Item][source]¶

perform_collect(args: Sequence[str] | None = None, genitems: bool = True) → Sequence[Item | Collector]

为此会话执行收集阶段。

这由默认的 pytest_collection 钩子实现调用；有关更多详细信息，请参阅此钩子的文档。出于测试目的，也可以直接在一个新的 Session 上调用它。

此函数通常递归地展开从会话中收集的任何收集器到它们的项，并且仅返回项。出于测试目的，可以通过传递 genitems=False 来抑制此行为，在这种情况下，返回值包含这些未展开的收集器，并且 session.items 为空。

for ... in collect()[source]¶

为此收集器收集子项（测试项和收集器）。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

Package¶

class Package[source]¶

基类: Directory

Python 包中文件和目录的收集器 – 带有 __init__.py 文件的目录。

注意

没有 __init__.py 文件的目录默认由 Dir 收集。两者都是 Directory 收集器。

版本 8.0 变更: 现在继承自 Directory。

for ... in collect()[source]¶

为此收集器收集子项（测试项和收集器）。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

Module¶

class Module[source]¶

基类: File, PyCollector

Python 模块中测试类和函数的收集器。

collect()[source]¶

为此收集器收集子项（测试项和收集器）。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

Class¶

class Class[source]¶

基类: PyCollector

Python 类中测试方法（和嵌套类）的收集器。

classmethod from_parent(parent, *, name, obj=None, **kw)[source]¶

公共构造函数。

collect()[source]¶

为此收集器收集子项（测试项和收集器）。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

Function¶

class Function[source]¶

基类: PyobjMixin, Item

负责设置和执行 Python 测试函数的项。

参数:

name – 完整的函数名称，包括任何由参数化添加的修饰，例如 (my_func[my_param])。
parent – 父节点。
config – pytest Config 对象。
callspec – 如果给定，则此函数已被参数化，并且 callspec 包含有关参数化的元信息。
callobj – 如果给定，则当调用 Function 时将调用的对象，否则将使用 originalname 从 parent 获取 callobj。
keywords – 绑定到函数对象的关键字，用于 “-k” 匹配。
session – pytest Session 对象。
fixtureinfo – 已在此 fixture 节点解析的 Fixture 信息。
originalname – 用于访问底层函数对象的属性名称。默认为 name。如果 name 与原始名称不同，则设置此项，例如当它包含由参数化添加的修饰时 (my_func[my_param])。

originalname¶: 原始函数名称，不带任何修饰（例如，参数化将 "[...]" 后缀添加到函数名称），用于从 parent 访问底层函数对象（如果未显式给定 callobj）。

版本 3.0 新增。

classmethod from_parent(parent, **kw)[source]¶

公共构造函数。

property function¶: 底层 Python “函数” 对象。

property instance¶

函数绑定到的 Python 实例对象。

如果不是测试方法，例如对于独立测试函数、类或模块，则返回 None。

runtest()[source]¶

执行底层测试函数。

repr_failure(excinfo)[source]¶

返回收集或测试失败的表示。

另请参阅

使用非 Python 测试

参数:: excinfo (ExceptionInfo[BaseException]) – 失败的异常信息。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

FunctionDefinition¶

class FunctionDefinition[source]¶

基类: Function

这个类是一个临时的解决方案，直到我们发展到拥有实际的函数定义节点并设法摆脱 metafunc。

runtest()[source]¶

执行底层测试函数。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

setup()¶

执行底层测试函数。

Objects¶

可以从 fixture 或 hook 访问或从 pytest 导入的对象。

CallInfo¶

final class CallInfo[source]¶

函数调用的结果/异常信息。

excinfo: ExceptionInfo[BaseException] | None¶: 调用的捕获异常（如果引发）。

start: float¶: 调用开始时的系统时间，以自 epoch 以来的秒数表示。

stop: float¶: 调用结束时的系统时间，以自 epoch 以来的秒数表示。

duration: float¶: 调用持续时间，以秒为单位。

when: Literal['collect', 'setup', 'call', 'teardown']¶: 调用上下文：“collect”、“setup”、“call” 或 “teardown”。

property result: TResult¶

调用的返回值（如果未引发异常）。

只有当 excinfo 为 None 时才能访问。

classmethod from_call(func, when, reraise=None)[source]¶

调用 func，并将结果包装在 CallInfo 中。

参数:

func (Callable[[], _pytest.runner.TResult]) – 要调用的函数。不带参数调用。
when (Literal['collect', 'setup', 'call', 'teardown']) – 函数被调用的阶段。
reraise (type[BaseException] | tuple[type[BaseException], ...] | None) – 如果函数引发了异常，则应传播的异常或异常，而不是包装在 CallInfo 中。

CollectReport¶

final class CollectReport[source]¶

基类: BaseReport

收集报告对象。

报告可以包含任意的额外属性。

nodeid: str¶: 标准化的收集节点 ID。

outcome: Literal['passed', 'failed', 'skipped']¶: 测试结果，始终为 “passed”，“failed”，“skipped” 之一。

longrepr: None | ExceptionInfo[BaseException] | tuple[str, int, str] | str | TerminalRepr¶: None 或失败表示。

result¶: 收集到的项和收集节点。

sections: list[tuple[str, str]]¶: str 元组 (heading, content)，包含测试报告的额外信息。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¶

实验性功能：此报告的 head line 与 longrepr 输出一起显示，更常见于失败期间的回溯表示中

________ Test.foo ________

在上面的示例中，head_line 是 “Test.foo”。

注意

此功能被认为是实验性的，因此请注意，即使在补丁版本中也可能会发生更改。

property longreprtext: str¶: 只读属性，返回 longrepr 的完整字符串表示形式。

版本 3.0 新增。

property passed: bool¶: 结果是否为通过。

property skipped: bool¶: 结果是否为跳过。

配置¶

final class Config[source]¶

访问配置值、插件管理器和插件钩子。

参数:

pluginmanager (PytestPluginManager) – 一个 pytest PluginManager。
invocation_params (InvocationParams) – 包含有关 pytest.main() 调用参数的对象。

final class InvocationParams(*, args, plugins, dir)[source]¶

保存 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() 的目录。 :type: pathlib.Path

class ArgsSource(*values)[source]¶

指示测试参数的来源。

7.2 版本新增。

ARGS = 1¶: 命令行参数。

INVOCATION_DIR = 2¶: 调用目录。

TESTPATHS = 3¶: “testpaths” 配置值。

option¶

以属性形式访问命令行选项。

类型:: argparse.Namespace

invocation_params¶

pytest 被调用的参数。

类型:: InvocationParams

pluginmanager¶

插件管理器处理插件注册和钩子调用。

类型:: PytestPluginManager

stash¶

插件可以在其中存储有关配置的信息以供自己使用的地方。

类型:: Stash

property rootpath: Path¶

到 rootdir 的路径。

类型:: pathlib.Path

6.1 版本新增。

property inipath: Path | None¶: 到 configfile 的路径。

6.1 版本新增。

add_cleanup(func)[source]¶

添加一个函数，当 config 对象不再使用时（通常与 pytest_unconfigure 一致）调用该函数。

classmethod fromdictargs(option_dict, args)[source]¶

可用于子进程的构造函数。

issue_config_time_warning(warning, stacklevel)[source]¶

在 “configure” 阶段发出并处理警告。

在 pytest_configure 期间，我们无法使用 catch_warnings_for_item 函数捕获警告，因为不可能在 pytest_configure 周围设置钩子包装器。

此函数主要供需要在 pytest_configure（或类似阶段）期间发出警告的插件使用。

参数:

warning (Warning) – 警告实例。
stacklevel (int) – 转发到 warnings.warn 的 stacklevel。

addinivalue_line(name, line)[source]¶

向 ini 文件选项添加一行。该选项必须已声明，但可能尚未设置，在这种情况下，该行将成为其值的第一行。

getini(name)[source]¶

从 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)[source]¶

返回命令行选项值。

参数:

name (str) – 选项的名称。您也可以指定文字 --OPT 选项，而不是 “dest” 选项名称。
default – 如果没有通过 pytest_addoption 声明该名称的选项，则为回退值。请注意，即使选项的值为 None，当选项被声明时，此参数将被忽略。
skip (bool) – 如果为 True，则当选项未声明或值为 None 时，引发 pytest.skip()。请注意，即使为 True，如果指定了默认值，它也将被返回，而不是跳过。

getvalue(name, path=None)[source]¶

已弃用，请改用 getoption()。

getvalueorskip(name, path=None)[source]¶

已弃用，请改用 getoption(skip=True)。

VERBOSITY_ASSERTIONS: Final = 'assertions'¶: 失败断言的详细程度类型（请参阅 verbosity_assertions）。

VERBOSITY_TEST_CASES: Final = 'test_cases'¶: 测试用例执行的详细程度类型（请参阅 verbosity_test_cases）。

get_verbosity(verbosity_type=None)[source]¶

检索精细粒度详细程度类型的详细程度级别。

参数:: verbosity_type (str | None) – 要获取级别的详细程度类型。如果为给定类型配置了级别，则将返回该值。如果给定类型不是已知的详细程度类型，则将返回全局详细程度级别。如果给定类型为 None（默认），则将返回全局详细程度级别。

要为精细粒度详细程度类型配置级别，配置文件应具有配置名称的设置和详细程度级别的数值。特殊值 “auto” 可用于显式使用全局详细程度级别。

示例

# content of pytest.ini
[pytest]
verbosity_assertions = 2

pytest -v

print(config.get_verbosity())  # 1
print(config.get_verbosity(Config.VERBOSITY_ASSERTIONS))  # 2

目录¶

final class Dir[source]¶

文件系统目录中文件的收集器。

在 8.0 版本中添加。

注意

包含 __init__.py 文件的 Python 目录默认由 Package 收集。两者都是 Directory 收集器。

classmethod from_parent(parent, *, path)[source]¶

公共构造函数。

参数:

parent (nodes.Collector) – 此 Dir 的父收集器。
path (pathlib.Path) – 目录的路径。

for ... in collect()[source]¶

为此收集器收集子项（测试项和收集器）。

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

目录¶

class Directory[source]¶

从目录收集文件的基类。

基本目录收集器执行以下操作：遍历目录中的文件和子目录，并通过调用钩子 pytest_collect_directory 和 pytest_collect_file 为它们创建收集器，在检查它们是否未使用 pytest_ignore_collect 忽略之后。

默认目录收集器为 Dir 和 Package。

在 8.0 版本中添加。

使用自定义目录收集器.

name: str¶: 父节点作用域内的唯一名称。

parent¶: 父收集器节点。

config: Config¶: pytest config 对象。

session: Session¶: 此节点所属的 pytest 会话。

path: pathlib.Path¶: 此节点从中收集的文件系统路径（可以为 None）。

ExceptionInfo¶

final class ExceptionInfo[source]¶

包装 sys.exc_info() 对象，并为导航回溯提供帮助。

classmethod from_exception(exception, exprinfo=None)[source]¶

返回现有异常的 ExceptionInfo。

异常必须具有非 None 的 __traceback__ 属性，否则此函数将因断言错误而失败。这意味着异常必须已被引发，或使用 with_traceback() 方法添加了回溯。

参数:: exprinfo (str | None) – 一个文本字符串，帮助确定是否应从输出中去除 AssertionError。默认为异常消息/__str__()。

在版本 7.4 中添加。

classmethod from_exc_info(exc_info, exprinfo=None)[source]¶

类似于 from_exception()，但使用旧式的 exc_info 元组。

classmethod from_current(exprinfo=None)[source]¶

返回与当前回溯匹配的 ExceptionInfo。

警告

实验性 API

参数:: exprinfo (str | None) – 一个文本字符串，帮助确定是否应从输出中去除 AssertionError。默认为异常消息/__str__()。

classmethod for_later()[source]¶

返回一个未填充的 ExceptionInfo。

fill_unfilled(exc_info)[source]¶

填充使用 for_later() 创建的未填充的 ExceptionInfo。

property type: type[E]¶: 异常类。

property value: E¶: 异常值。

property tb: TracebackType¶: 异常原始回溯。

property typename: str¶: 异常的类型名称。

property traceback: Traceback¶: 回溯。

exconly(tryshort=False)[source]¶

将异常作为字符串返回。

当 ‘tryshort’ 解析为 True，且异常为 AssertionError 时，仅返回异常表示的实际异常部分（因此 ‘AssertionError: ’ 会从开头移除）。

errisinstance(exc)[source]¶

如果异常是 exc 的实例，则返回 True。

考虑使用 isinstance(excinfo.value, exc) 代替。

getrepr(showlocals=False, style='long', abspath=False, tbfilter=True, funcargs=False, truncate_locals=True, truncate_args=True, chain=True)[source]¶

返回此异常信息的 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) – 显示每个回溯条目的 fixtures（为兼容旧版本目的，称为 “funcargs”）。
truncate_locals (bool) – 当 showlocals==True 时，确保局部变量可以安全地表示为字符串。
truncate_args (bool) – 当 showargs==True 时，确保 args 可以安全地表示为字符串。
chain (bool) – 是否应显示 Python 3 中的链式异常。

Changed in version 3.9: 添加了 chain 参数。

match(regexp)[source]¶

检查正则表达式 regexp 是否使用 re.search() 匹配异常的字符串表示形式。

如果匹配，则返回 True，否则引发 AssertionError。

group_contains(expected_exception, *, match=None, depth=None)[source]¶

检查捕获的异常组是否包含匹配的异常。

参数:

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(*values)[source]¶

编码 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[source]¶

基类：Generic[FixtureValue]

fixture 定义的容器。

注意：目前，只有明确文档记录的字段和方法被认为是公共稳定 API。

property scope: Literal['session', 'package', 'module', 'class', 'function']¶: 作用域字符串，为 “function”、“class”、“module”、“package”、“session” 之一。

execute(request)[source]¶

返回此 fixture 的值，如果未缓存则执行它。

MarkDecorator¶

class MarkDecorator[source]¶

用于在测试函数和类上应用 mark 的装饰器。

MarkDecorators 使用 pytest.mark 创建

mark1 = pytest.mark.NAME  # Simple MarkDecorator
mark2 = pytest.mark.NAME(name1=value)  # Parametrized MarkDecorator

然后可以作为装饰器应用于测试函数

@mark2
def test_function():
    pass

当调用 MarkDecorator 时，它执行以下操作

如果调用时仅使用单个类作为其唯一的位置参数，且没有额外的关键字参数，则它会将 mark 附加到该类，以便自动应用于在该类中找到的所有测试用例。
如果调用时仅使用单个函数作为其唯一的位置参数，且没有额外的关键字参数，则它会将 mark 附加到该函数，其中包含已在 MarkDecorator 内部存储的所有参数。
在任何其他情况下调用时，它会返回一个新的 MarkDecorator 实例，其中原始 MarkDecorator 的内容已使用传递给此调用的参数进行更新。

注意：上述规则阻止 MarkDecorator 仅存储单个函数或类引用作为其位置参数，而没有额外的关键字或位置参数。您可以通过使用 with_args() 来解决此问题。

property name: str¶: mark.name 的别名。

property args: tuple[Any, ...]¶: mark.args 的别名。

property kwargs: Mapping[str, Any]¶: mark.kwargs 的别名。

with_args(*args, **kwargs)[source]¶

返回添加了额外参数的 MarkDecorator。

与调用 MarkDecorator 不同，即使唯一参数是可调用对象/类，也可以使用 with_args()。

MarkGenerator¶

final class MarkGenerator[source]¶

用于 MarkDecorator 对象的工厂 - 作为 pytest.mark 单例实例公开。

示例

import pytest


@pytest.mark.slowtest
def test_function():
    pass

在 test_function 上应用 ‘slowtest’ Mark。

Mark¶

final class Mark[source]¶

一个 pytest mark。

name: str¶: mark 的名称。

args: tuple[Any, ...]¶: mark 装饰器的位置参数。

kwargs: Mapping[str, Any]¶: mark 装饰器的关键字参数。

combined_with(other)[source]¶

返回一个新的 Mark，它是此 Mark 和另一个 Mark 的组合。

通过追加 args 和合并 kwargs 进行组合。

参数:: other (Mark) – 要组合的 mark。
Return type:: Mark

Metafunc¶

final class Metafunc[source]¶

传递给 pytest_generate_tests hook 的对象。

它们帮助检查测试函数，并根据测试配置或在定义测试函数的类或模块中指定的值生成测试。

definition¶: 访问底层的 _pytest.python.FunctionDefinition。

config¶: 访问测试会话的 pytest.Config 对象。

module¶: 在其中定义测试函数的模块对象。

function¶: 底层的 Python 测试函数。

fixturenames¶: 测试函数所需的 fixture 名称集合。

cls¶: 在其中定义测试函数的类对象，或 None。

parametrize(argnames, argvalues, indirect=False, ids=None, scope=None, *, _param_mark=None)[source]¶

使用给定 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[_pytest.mark.structures.ParameterSet | Sequence[object] | object]) –
argvalues 列表确定使用不同参数值调用测试的频率。

如果仅指定了一个 argname，则 argvalues 是值列表。如果指定了 N 个 argnames，则 argvalues 必须是 N 元组的列表，其中每个元组元素指定其各自 argname 的值。
indirect (bool | Sequence[str]) – 参数名称列表（argnames 的子集）或布尔值。如果为 True，则列表包含 argnames 中的所有名称。此列表中 argname 对应的每个 argvalue 将作为 request.param 传递给其各自的 argname fixture 函数，以便它可以在测试的 setup 阶段而不是在收集时执行更昂贵的设置。
ids (Iterable[object | None] | Callable[[Any], object | None] | None) –
用于 argvalues 的 id 序列（或生成器），或者是一个可调用对象，用于为每个 argvalue 返回部分 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 函数定义的作用域，从而允许使用测试上下文或配置设置动态作用域。

Parser¶

final class Parser[source]¶

用于命令行参数和 ini 文件值的解析器。

变量:: extra_info – 通用参数 -> 值的字典，用于在处理命令行参数时显示错误信息。

getgroup(name, description='', after=None)[source]¶

获取（或创建）一个命名的选项组。

参数:

name (str) – 选项组的名称。
description (str) – 用于 –help 输出的详细描述。
after (str | None) – 另一个组的名称，用于排序 –help 输出。

Returns:

选项组。

Return type:

OptionGroup

返回的组对象具有与 parser.addoption 相同的签名的 addoption 方法，但在 pytest --help 的输出中将在相应的组中显示。

addoption(*opts, **attrs)[source]¶

注册一个命令行选项。

参数:

opts (str) – 选项名称，可以是短选项或长选项。
attrs (Any) – 与 argparse 库的 add_argument() 函数接受的属性相同。

在命令行解析之后，可以通过 config.option.NAME 在 pytest config 对象上使用选项，其中 NAME 通常通过传递 dest 属性来设置，例如 addoption("--long", dest="NAME", ...)。

parse_known_args(args, namespace=None)[source]¶

在此点解析已知的参数。

Returns:: 一个 argparse 命名空间对象。
Return type:: Namespace

parse_known_and_unknown_args(args, namespace=None)[source]¶

在此点解析已知的参数，并返回剩余的未知参数。

Returns:: 一个元组，包含已知参数的 argparse 命名空间对象和未知参数的列表。
Return type:: tuple[Namespace, list[str]]

addini(name, help, type=None, default=<notset>)[source]¶

注册一个 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 (Any) – 如果不存在 ini 文件选项但被查询，则为默认值。

可以通过调用 config.getini(name) 来检索 ini 变量的值。

OptionGroup¶

class OptionGroup[source]¶

一组选项，显示在其自己的部分中。

addoption(*opts, **attrs)[source]¶

向此组添加一个选项。

如果指定了长选项的缩短版本，它将在帮助中被抑制。addoption('--twowords', '--two-words') 会导致帮助只显示 --two-words，但 --twowords 会被接受，并且自动目标在 args.twowords 中。

参数:

opts (str) – 选项名称，可以是短选项或长选项。
attrs (Any) – 与 argparse 库的 add_argument() 函数接受的属性相同。

PytestPluginManager¶

final class PytestPluginManager[source]¶

基类: PluginManager

一个 pluggy.PluginManager，具有额外的 pytest 特有功能

从命令行、PYTEST_PLUGINS 环境变量和在加载的插件中找到的 pytest_plugins 全局变量加载插件。
启动期间加载 conftest.py。

register(plugin, name=None)[source]¶

注册一个插件并返回其名称。

参数:: name (str | None) – 用于注册插件的名称。如果未指定，则使用 get_canonical_name() 生成名称。
Returns:: 插件名称。如果名称被阻止注册，则返回 None。
Return type:: str | None

如果插件已注册，则引发 ValueError。

getplugin(name)[source]¶

hasplugin(name)[source]¶

返回是否已注册具有给定名称的插件。

import_plugin(modname, consider_entry_points=False)[source]¶

导入具有 modname 的插件。

如果 consider_entry_points 为 True，则还会考虑入口点名称以查找插件。

add_hookcall_monitoring(before, after)¶

为所有 hook 添加 before/after 跟踪函数。

返回一个撤消函数，调用该函数将删除添加的跟踪器。

before(hook_name, hook_impls, kwargs) 将在所有 hook 调用之前调用，并接收一个 hookcaller 实例、一个 HookImpl 实例列表和 hook 调用的关键字参数。

after(outcome, hook_name, hook_impls, kwargs) 接收与 before 相同的参数，以及一个 Result 对象，该对象表示整个 hook 调用的结果。

add_hookspecs(module_or_class)¶

添加在给定的 module_or_class 中定义的新 hook 规范。

如果函数已使用匹配的 HookspecMarker 进行装饰，则会被识别为 hook 规范。

check_pending()¶

验证所有尚未针对 hook 规范进行验证的 hook 都是可选的，否则引发 PluginValidationError。

enable_tracing()¶

启用 hook 调用的跟踪。

返回一个撤消函数，调用该函数将删除添加的跟踪。

get_canonical_name(plugin)¶

返回插件对象的规范名称。

请注意，插件可以使用 register(plugin, name) 的调用者指定的不同名称注册。要获取已注册插件的名称，请改用 get_name(plugin)。

get_hookcallers(plugin)¶

获取指定插件的所有 hook 调用者。

Returns:: hook 调用者，如果 plugin 未在此插件管理器中注册，则为 None。
Return type:: list[HookCaller] | None

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 的插件。

Returns:

此调用加载的插件数量。

Return type:

int

set_blocked(name)¶

阻止给定名称的注册，如果已注册则取消注册。

subset_hook_caller(name, remove_plugins)¶

为命名方法返回一个代理 HookCaller 实例，该实例管理对除 remove_plugins 中的插件之外的所有已注册插件的调用。

unblock(name)¶

取消阻止一个名称。

返回名称是否实际被阻止。

unregister(plugin=None, name=None)¶

取消注册一个插件及其所有 hook 实现。

可以通过插件对象或插件名称指定插件。如果两者都指定，则它们必须一致。

返回未注册的插件，如果未找到，则返回 None。

project_name: Final¶: 项目名称。

hook: Final¶: “hook 中继”，用于在所有已注册插件上调用 hook。请参阅调用 hook。

trace: Final[_tracing.TagTracerSub]¶: 跟踪入口点。请参阅内置跟踪。

TestReport¶

final class TestReport[source]¶

基类: BaseReport

基本测试报告对象（如果 setup 和 teardown 调用失败，也用于它们）。

报告可以包含任意的额外属性。

nodeid: str¶: 标准化的收集节点 ID。

location: tuple[str, int | None, str]¶: 一个 (filesystempath, lineno, domaininfo) 元组，指示测试项的实际位置 - 它可能与收集到的位置不同，例如，如果一个方法是从不同的模块继承的。filesystempath 可能相对于 config.rootdir。行号是基于 0 的。

keywords: Mapping[str, Any]¶: 一个 name -> value 字典，包含与测试调用关联的所有关键字和标记。

outcome: Literal['passed', 'failed', 'skipped']¶: 测试结果，始终为 “passed”，“failed”，“skipped” 之一。

longrepr: None | ExceptionInfo[BaseException] | tuple[str, int, str] | str | TerminalRepr¶: None 或失败表示。

when: str | None¶: ‘setup’、‘call’、‘teardown’ 之一，用于指示运行测试阶段。

user_properties¶: User properties（用户属性）是一个元组列表 (name, value)，用于保存用户定义的测试属性。

sections: list[tuple[str, str]]¶: str 元组 (heading, content)，包含测试报告的额外信息。pytest 使用它来添加从 stdout，stderr 捕获的文本和拦截的日志事件。其他插件可以使用它向报告添加任意信息。

duration: float¶: 运行测试所花费的时间。

start: float¶: 调用开始时的系统时间，以自 epoch 以来的秒数表示。

stop: float¶: 调用结束时的系统时间，以自 epoch 以来的秒数表示。

classmethod from_item_and_call(item, call)[source]¶

使用标准 item 和 call 信息创建并填充 TestReport。

参数:

item (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¶

实验性功能：此报告的 head line 与 longrepr 输出一起显示，更常见于失败期间的回溯表示中

________ Test.foo ________

在上面的示例中，head_line 是 “Test.foo”。

注意

此功能被认为是实验性的，因此请注意，即使在补丁版本中也可能会发生更改。

property longreprtext: str¶: 只读属性，返回 longrepr 的完整字符串表示形式。

版本 3.0 新增。

property passed: bool¶: 结果是否为通过。

property skipped: bool¶: 结果是否为跳过。

TestShortLogReport¶

class TestShortLogReport[source]¶

用于存储测试状态结果类别、简短字母和详细单词。例如 "rerun", "R", ("RERUN", {"yellow": True})。

变量:

category – 结果的类别，例如 “passed”、 “skipped”、 “error” 或空字符串。
letter – 在测试进行时显示的简短字母，例如 "."、 "s"、 "E" 或空字符串。
word – 在详细模式下测试进行时显示的详细单词，例如 "PASSED"、 "SKIPPED"、 "ERROR" 或空字符串。

category: str¶: 字段编号 0 的别名

letter: str¶: 字段编号 1 的别名

word: str | tuple[str, Mapping[str, bool]]¶: 字段编号 2 的别名

Result¶

在 hook wrappers（钩子包装器）中使用的 Result 对象，有关更多信息，请参阅 pluggy 文档中的 Result。

Stash¶

class Stash[source]¶

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)[source]¶

为键设置值。

__getitem__(key)[source]¶

获取键的值。

如果键之前未设置，则引发 KeyError。

get(key, default)[source]¶

获取键的值，或者如果键之前未设置，则返回 default。

setdefault(key, default)[source]¶

如果已设置，则返回值 key，否则将键的值设置为 default 并返回 default。

__delitem__(key)[source]¶

删除键的值。

如果键之前未设置，则引发 KeyError。

__contains__(key)[source]¶

返回是否设置了键。

__len__()[source]¶

返回 stash 中存在的条目数。

class StashKey[source]¶

基类：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¶

教程：标记整个类或模块

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

import pytest

pytestmark = pytest.mark.webtest

import pytest

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

环境变量¶

可用于更改 pytest 行为的环境变量。

CI¶

当设置（无论值如何）时，pytest 确认正在 CI 进程中运行。 BUILD_NUMBER 变量的替代方案。另请参阅 CI 管道。

BUILD_NUMBER¶

当设置（无论值如何）时，pytest 确认正在 CI 进程中运行。 CI 变量的替代方案。另请参阅 CI 管道。

PYTEST_ADDOPTS¶

这包含一个命令行 (由 py:mod:shlex 模块解析)，它将前置到用户给定的命令行，请参阅内置配置文件选项以获取更多信息。

PYTEST_VERSION¶

此环境变量在 pytest 会话开始时定义，之后未定义。它包含 pytest.__version__ 的值，除其他外，可以用来轻松检查代码是否在 pytest 运行中运行。

PYTEST_CURRENT_TEST¶

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

PYTEST_DEBUG¶

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

PYTEST_DEBUG_TEMPROOT¶

由 fixtures (例如 tmp_path) 生成的临时目录的根目录，如临时目录位置和保留中所述。

PYTEST_DISABLE_PLUGIN_AUTOLOAD¶

设置后，通过 entry point packaging metadata（入口点打包元数据）禁用插件自动加载。仅显式指定的插件将被加载。

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[source]¶

基类: Exception

pytest 使用或调用中的错误。

final exception FixtureLookupError[source]¶

基类： LookupError

无法返回请求的 fixture（缺失或无效）。

警告¶

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

class PytestWarning¶

基类： UserWarning

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

class PytestAssertRewriteWarning¶

基类： PytestWarning

由 pytest assert rewrite 模块发出的警告。

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。

doctest_optionflags¶: 标准 doctest 模块中的一个或多个 doctest 标志名称。请参阅 pytest 如何处理 doctest。

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 秒（包括 fixture 设置和拆卸），则转储所有线程的回溯信息。使用 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（默认值）：报告的持续时间包括 setup、call 和 teardown 时间。
call：报告的持续时间仅包括 call 时间，不包括 setup 和 teardown 时间。

[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 [value] 和配置选项 log_auto_indent = [value] 来为所有日志设置自动缩进行为。

[value] 可以是

True 或 “On” - 动态自动缩进多行日志消息
False 或 “Off” 或 0 - 不自动缩进多行日志消息（默认行为）
[正整数] - 将多行日志消息自动缩进 [value] 个空格

[pytest]
log_auto_indent = False

支持将 kwarg extra={"auto_indent": [value]} 传递给 logging.log() 的调用，以指定日志中特定条目的自动缩进行为。extra kwarg 覆盖命令行或配置中指定的值。

log_cli¶

在测试运行期间启用日志显示（也称为“实时日志”）。默认值为 False。

[pytest]
log_cli = True

log_cli_date_format¶

设置一个与 time.strftime() 兼容的字符串，该字符串将用于格式化实时日志的日期。

[pytest]
log_cli_date_format = %Y-%m-%d %H:%M:%S

有关更多信息，请参阅实时日志。

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 将尝试智能地识别和忽略 virtualenv。任何被认为是 virtual environment 根目录的目录都不会在测试收集期间被考虑，除非给定 --collect-in-virtualenv。另请注意，norecursedirs 优先于 --collect-in-virtualenv；例如，如果您打算在基本目录与 '.*' 匹配的 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¶

设置应在没有在命令行中给出特定目录、文件或测试 ID 的情况下，在从 rootdir 目录执行 pytest 时搜索测试的目录列表。文件系统路径可以使用 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 evaluable
                        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, --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
  --no-fold-skipped     Do not fold skipped tests in short 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)
  --xfail-tb            Show tracebacks for xfail (as long as --tb != 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
  --junitxml, --junit-xml=path
                        Create junit-xml style report file at given path
  --junitprefix, --junit-prefix=str
                        Prepend prefix to classnames in junit-xml output

pytest-warnings:
  -W, --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, --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 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:
  CI                       When set (regardless of value), pytest knows it is running in a CI process and does not truncate summary info
  BUILD_NUMBER             Equivalent to CI
  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

API 参考¶

常量¶

pytest.__version__¶

pytest.version_tuple¶

函数¶

pytest.approx¶

pytest.fail¶

pytest.skip¶

pytest.importorskip¶

pytest.xfail¶

pytest.exit¶

pytest.main¶

pytest.param¶

pytest.raises¶

pytest.deprecated_call¶

pytest.register_assert_rewrite¶

pytest.warns¶

pytest.freeze_includes¶

标记¶

pytest.mark.filterwarnings¶

pytest.mark.parametrize¶

pytest.mark.skip¶

pytest.mark.skipif¶

pytest.mark.usefixtures¶

pytest.mark.xfail¶

自定义标记¶

Fixtures¶

@pytest.fixture¶

capfd¶

capfdbinary¶

caplog¶

capsys¶

capsysbinary¶

config.cache¶

doctest_namespace¶

monkeypatch¶

pytestconfig¶

pytester¶

record_property¶

record_testsuite_property¶

recwarn¶

request¶

testdir¶

tmp_path¶

tmp_path_factory¶

tmpdir¶

tmpdir_factory¶

Hooks¶

@pytest.hookimpl¶

@pytest.hookspec¶

引导 hooks¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

初始化钩子¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

收集钩子¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

测试运行 (runtest) 钩子¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

在 conftest 插件中使用¶

pytest.version¶