Fixtures 参考

另请参阅

关于 fixtures

另请参阅

如何使用 fixtures

内置 fixtures

Fixtures 使用 @pytest.fixture 装饰器定义。Pytest 有几个有用的内置 fixtures

capfd

捕获文件描述符 1 和 2 的输出为文本。

capfdbinary

捕获文件描述符 1 和 2 的输出为字节。

caplog

控制日志记录和访问日志条目。

capsys

捕获 sys.stdout 和 sys.stderr 的输出为文本。

capsysbinary

捕获 sys.stdout 和 sys.stderr 的输出为字节。

cache

跨 pytest 运行存储和检索值。

doctest_namespace

提供一个注入到 doctests 命名空间中的字典。

monkeypatch

临时修改类、函数、字典、os.environ 和其他对象。

pytestconfig

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

record_property

向测试添加额外的属性。

record_testsuite_property

向测试套件添加额外的属性。

recwarn

记录测试函数发出的警告。

request

提供有关正在执行的测试函数的信息。

testdir

提供一个临时测试目录，以帮助运行和测试 pytest 插件。

tmp_path

提供一个指向临时目录的 pathlib.Path 对象，该目录对于每个测试函数都是唯一的。

tmp_path_factory

创建会话范围的临时目录并返回 pathlib.Path 对象。

tmpdir

提供一个指向临时目录的 py.path.local 对象，该目录对于每个测试函数都是唯一的；已被 tmp_path 替换。

tmpdir_factory

创建会话范围的临时目录并返回 py.path.local 对象；已被 tmp_path_factory 替换。

Fixture 可用性

Fixture 的可用性是从测试的角度确定的。只有当 fixture 位于定义的 scope 中时，fixture 才可供测试请求。如果 fixture 在类内部定义，则只能由该类内部的测试请求。但是，如果 fixture 在模块的全局 scope 内定义，则该模块中的每个测试（即使在类内部定义）都可以请求它。

同样，只有当测试与 autouse fixture 位于相同的 scope 中时，测试才会受到 autouse fixture 的影响（请参阅 Autouse fixtures 在其 scope 内首先执行）。

Fixture 还可以请求任何其他 fixture，无论其定义位置如何，只要请求它们的测试可以看到所有涉及的 fixture。

例如，这是一个测试文件，其中包含一个 fixture (outer)，该 fixture 请求一个来自未定义 scope 的 fixture (inner)

from __future__ import annotations

import pytest


@pytest.fixture
def order():
    return []


@pytest.fixture
def outer(order, inner):
    order.append("outer")


class TestOne:
    @pytest.fixture
    def inner(self, order):
        order.append("one")

    def test_order(self, order, outer):
        assert order == ["one", "outer"]


class TestTwo:
    @pytest.fixture
    def inner(self, order):
        order.append("two")

    def test_order(self, order, outer):
        assert order == ["two", "outer"]

从测试的角度来看，它们可以毫无问题地看到它们所依赖的每个 fixture

因此，当它们运行时，outer 将毫无问题地找到 inner，因为 pytest 从测试的角度搜索。

注意

fixture 定义的 scope 与其实例化的顺序无关：顺序由 此处 描述的逻辑决定。

conftest.py：跨多个文件共享 fixtures

conftest.py 文件用作为整个目录提供 fixtures 的一种手段。conftest.py 中定义的 Fixtures 可以被该包中的任何测试使用，而无需导入它们（pytest 将自动发现它们）。

您可以拥有多个嵌套目录/包，其中包含您的测试，并且每个目录都可以有自己的 conftest.py 及其自己的 fixtures，添加到父目录中 conftest.py 文件提供的 fixtures 中。

例如，给定如下测试文件结构

tests/
    __init__.py

    conftest.py
        # content of tests/conftest.py
        import pytest

        @pytest.fixture
        def order():
            return []

        @pytest.fixture
        def top(order, innermost):
            order.append("top")

    test_top.py
        # content of tests/test_top.py
        import pytest

        @pytest.fixture
        def innermost(order):
            order.append("innermost top")

        def test_order(order, top):
            assert order == ["innermost top", "top"]

    subpackage/
        __init__.py

        conftest.py
            # content of tests/subpackage/conftest.py
            import pytest

            @pytest.fixture
            def mid(order):
                order.append("mid subpackage")

        test_subpackage.py
            # content of tests/subpackage/test_subpackage.py
            import pytest

            @pytest.fixture
            def innermost(order, mid):
                order.append("innermost subpackage")

            def test_order(order, top):
                assert order == ["mid subpackage", "innermost subpackage", "top"]

scope 的边界可以像这样可视化

目录变成它们自己的 scope 种类，其中在目录中的 conftest.py 文件中定义的 fixtures 可用于整个 scope。

测试允许向上搜索（ stepping outside a circle ）fixtures，但永远不能向下（stepping inside a circle）继续搜索。因此，tests/subpackage/test_subpackage.py::test_order 将能够找到在 tests/subpackage/test_subpackage.py 中定义的 innermost fixture，但 tests/test_top.py 中定义的 fixture 将不可用，因为它必须向下步进一个级别（step inside a circle）才能找到它。

测试找到的第一个 fixture 将是被使用的 fixture，因此，如果您需要更改或扩展 fixture 对特定 scope 的作用，fixtures 可以被覆盖。

您还可以使用 conftest.py 文件来实现 本地按目录插件。

来自第三方插件的 Fixtures

Fixtures 不必在此结构中定义才能用于测试。它们也可以由已安装的第三方插件提供，这就是许多 pytest 插件的运作方式。只要安装了这些插件，它们提供的 fixtures 就可以从您的测试套件中的任何位置请求。

因为它们是从您的测试套件结构外部提供的，所以第三方插件实际上并没有提供像 conftest.py 文件和您的测试套件中的目录那样的 scope。因此，pytest 将按照先前解释的方式搜索 fixtures，通过 scope 向外步进，最后 才到达插件中定义的 fixtures。

例如，给定以下文件结构

tests/
    __init__.py

    conftest.py
        # content of tests/conftest.py
        import pytest

        @pytest.fixture
        def order():
            return []

    subpackage/
        __init__.py

        conftest.py
            # content of tests/subpackage/conftest.py
            import pytest

            @pytest.fixture(autouse=True)
            def mid(order, b_fix):
                order.append("mid subpackage")

        test_subpackage.py
            # content of tests/subpackage/test_subpackage.py
            import pytest

            @pytest.fixture
            def inner(order, mid, a_fix):
                order.append("inner subpackage")

            def test_order(order, inner):
                assert order == ["b_fix", "mid subpackage", "a_fix", "inner subpackage"]

如果安装了 plugin_a 并提供了 fixture a_fix，并且安装了 plugin_b 并提供了 fixture b_fix，那么这就是测试对 fixtures 的搜索方式

pytest 将仅在首先在 tests/ 内部的 scope 中搜索 a_fix 和 b_fix 后，才在插件中搜索它们。

Fixture 实例化顺序

当 pytest 想要执行测试时，一旦它知道将要执行哪些 fixtures，它就必须弄清楚它们的执行顺序。为此，它考虑了 3 个因素

1. scope

2. 依赖关系

3. autouse

fixtures 或测试的名称、它们的定义位置、它们的定义顺序以及请求 fixtures 的顺序对执行顺序没有影响，只是巧合。虽然 pytest 会尽力确保这些巧合在每次运行中保持一致，但这不应该被依赖。如果您想控制顺序，最安全的方法是依靠这 3 件事，并确保明确建立依赖关系。

更高 scope 的 fixtures 首先执行

在对 fixtures 的函数请求中，更高 scope 的 fixtures（例如 session）在更低 scope 的 fixtures（例如 function 或 class）之前执行。

这是一个例子

from __future__ import annotations

import pytest


@pytest.fixture(scope="session")
def order():
    return []


@pytest.fixture
def func(order):
    order.append("function")


@pytest.fixture(scope="class")
def cls(order):
    order.append("class")


@pytest.fixture(scope="module")
def mod(order):
    order.append("module")


@pytest.fixture(scope="package")
def pack(order):
    order.append("package")


@pytest.fixture(scope="session")
def sess(order):
    order.append("session")


class TestClass:
    def test_order(self, func, cls, mod, pack, sess, order):
        assert order == ["session", "package", "module", "class", "function"]

测试将通过，因为更大 scope 的 fixtures 首先执行。

顺序分解为这样

相同顺序的 fixtures 基于依赖关系执行

当一个 fixture 请求另一个 fixture 时，另一个 fixture 首先执行。因此，如果 fixture a 请求 fixture b，则 fixture b 将首先执行，因为 a 依赖于 b 并且没有它就无法运行。即使 a 不需要 b 的结果，如果它需要确保在 b 之后执行，它仍然可以请求 b。

例如

from __future__ import annotations

import pytest


@pytest.fixture
def order():
    return []


@pytest.fixture
def a(order):
    order.append("a")


@pytest.fixture
def b(a, order):
    order.append("b")


@pytest.fixture
def c(b, order):
    order.append("c")


@pytest.fixture
def d(c, b, order):
    order.append("d")


@pytest.fixture
def e(d, b, order):
    order.append("e")


@pytest.fixture
def f(e, order):
    order.append("f")


@pytest.fixture
def g(f, c, order):
    order.append("g")


def test_order(g, order):
    assert order == ["a", "b", "c", "d", "e", "f", "g"]

如果我们映射出什么依赖于什么，我们会得到类似这样的东西

每个 fixture 提供的规则（关于每个 fixture 必须在哪些 fixture 之后）都足够全面，可以将其展平为此

必须通过这些请求提供足够的信息，以便 pytest 能够弄清楚清晰的线性依赖链，并因此得出给定测试的操作顺序。如果存在任何歧义，并且操作顺序可以解释为多种方式，您应该假设 pytest 可以在任何时候采用这些解释中的任何一种。

例如，如果 d 没有请求 c，即图表看起来像这样

因为除了 g 之外没有其他任何东西请求 c，并且 g 也请求 f，现在不清楚 c 应该在 f、e 或 d 之前/之后。为 c 设置的唯一规则是它必须在 b 之后和 g 之前执行。

pytest 不知道在这种情况下 c 应该放在哪里，因此应该假设它可以放在 g 和 b 之间的任何位置。

这不一定是坏事，但这是需要记住的事情。如果它们的执行顺序可能会影响测试的目标行为，或者可能以其他方式影响测试结果，则应以允许 pytest 线性化/“展平”该顺序的方式显式定义顺序。

Autouse fixtures 在其 scope 内首先执行

Autouse fixtures 假定适用于可以引用它们的每个测试，因此它们在该 scope 中的其他 fixtures 之前执行。由 autouse fixtures 请求的 fixtures 实际上也变成了 autouse fixtures，用于真正的 autouse fixture 应用于的测试。

因此，如果 fixture a 是 autouse，而 fixture b 不是，但 fixture a 请求 fixture b，则 fixture b 实际上也将成为 autouse fixture，但仅适用于 a 应用于的测试。

在最后一个示例中，如果 d 没有请求 c，则图表变得不清楚。但是，如果 c 是 autouse，则 b 和 a 实际上也将成为 autouse，因为 c 依赖于它们。因此，它们都将在该 scope 内移动到非 autouse fixtures 之上。

因此，如果测试文件看起来像这样

from __future__ import annotations

import pytest


@pytest.fixture
def order():
    return []


@pytest.fixture
def a(order):
    order.append("a")


@pytest.fixture
def b(a, order):
    order.append("b")


@pytest.fixture(autouse=True)
def c(b, order):
    order.append("c")


@pytest.fixture
def d(b, order):
    order.append("d")


@pytest.fixture
def e(d, order):
    order.append("e")


@pytest.fixture
def f(e, order):
    order.append("f")


@pytest.fixture
def g(f, c, order):
    order.append("g")


def test_order_and_g(g, order):
    assert order == ["a", "b", "c", "d", "e", "f", "g"]

图表将看起来像这样

因为现在可以将 c 放在图表中的 d 之上，所以 pytest 可以再次将图表线性化为此

在此示例中，c 使 b 和 a 也成为有效的 autouse fixtures。

但要小心使用 autouse，因为 autouse fixture 将自动为可以访问它的每个测试执行，即使它们没有请求它。例如，考虑以下文件

from __future__ import annotations

import pytest


@pytest.fixture(scope="class")
def order():
    return []


@pytest.fixture(scope="class", autouse=True)
def c1(order):
    order.append("c1")


@pytest.fixture(scope="class")
def c2(order):
    order.append("c2")


@pytest.fixture(scope="class")
def c3(order, c1):
    order.append("c3")


class TestClassWithC1Request:
    def test_order(self, order, c1, c3):
        assert order == ["c1", "c3"]


class TestClassWithoutC1Request:
    def test_order(self, order, c2):
        assert order == ["c1", "c2"]

即使 TestClassWithoutC1Request 中的任何内容都没有请求 c1，它仍然会为其中的测试执行

但是，仅仅因为一个 autouse fixture 请求了一个非 autouse fixture，并不意味着非 autouse fixture 会成为它可以应用的每个上下文的 autouse fixture。它仅有效地成为真正的 autouse fixture（请求非 autouse fixture 的 fixture）可以应用的上下文的 autouse fixture。

例如，看一下这个测试文件

from __future__ import annotations

import pytest


@pytest.fixture
def order():
    return []


@pytest.fixture
def c1(order):
    order.append("c1")


@pytest.fixture
def c2(order):
    order.append("c2")


class TestClassWithAutouse:
    @pytest.fixture(autouse=True)
    def c3(self, order, c2):
        order.append("c3")

    def test_req(self, order, c1):
        assert order == ["c2", "c3", "c1"]

    def test_no_req(self, order):
        assert order == ["c2", "c3"]


class TestClassWithoutAutouse:
    def test_req(self, order, c1):
        assert order == ["c1"]

    def test_no_req(self, order):
        assert order == []

它会分解成这样的东西

对于 TestClassWithAutouse 内的 test_req 和 test_no_req，c3 有效地使 c2 成为 autouse fixture，这就是为什么 c2 和 c3 为两个测试执行，尽管没有被请求，以及为什么 c2 和 c3 在 test_req 的 c1 之前执行。

如果这使得 c2 成为实际的 autouse fixture，那么 c2 也将为 TestClassWithoutAutouse 内的测试执行，因为如果他们愿意，他们可以引用 c2。但事实并非如此，因为从 TestClassWithoutAutouse 测试的角度来看，c2 不是 autouse fixture，因为他们看不到 c3。