diff --git a/doc/en/example/fixtures/test_fixtures_order.py b/doc/en/example/fixtures/test_fixtures_order.py new file mode 100644 index 000000000..97b3e8005 --- /dev/null +++ b/doc/en/example/fixtures/test_fixtures_order.py @@ -0,0 +1,38 @@ +import pytest + +# fixtures documentation order example +order = [] + + +@pytest.fixture(scope="session") +def s1(): + order.append("s1") + + +@pytest.fixture(scope="module") +def m1(): + order.append("m1") + + +@pytest.fixture +def f1(f3): + order.append("f1") + + +@pytest.fixture +def f3(): + order.append("f3") + + +@pytest.fixture(autouse=True) +def a1(): + order.append("a1") + + +@pytest.fixture +def f2(): + order.append("f2") + + +def test_order(f1, m1, f2, s1): + assert order == ["s1", "m1", "a1", "f3", "f1", "f2"] diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index 852069731..78fef13e8 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -289,51 +289,30 @@ are finalized when the last test of a *package* finishes. Use this new feature sparingly and please make sure to report any issues you find. -Higher-scoped fixtures are instantiated first ---------------------------------------------- +Order: Higher-scoped fixtures are instantiated first +---------------------------------------------------- Within a function request for features, fixture of higher-scopes (such as ``session``) are instantiated first than lower-scoped fixtures (such as ``function`` or ``class``). The relative order of fixtures of same scope follows -the declared order in the test function and honours dependencies between fixtures. +the declared order in the test function and honours dependencies between fixtures. Autouse fixtures will be +instantiated before explicitly used fixtures. Consider the code below: -.. code-block:: python - - @pytest.fixture(scope="session") - def s1(): - pass - - - @pytest.fixture(scope="module") - def m1(): - pass - - - @pytest.fixture - def f1(tmpdir): - pass - - - @pytest.fixture - def f2(): - pass - - - def test_foo(f1, m1, f2, s1): - ... - +.. literalinclude:: example/fixtures/test_fixtures_order.py The fixtures requested by ``test_foo`` will be instantiated in the following order: 1. ``s1``: is the highest-scoped fixture (``session``). 2. ``m1``: is the second highest-scoped fixture (``module``). -3. ``tmpdir``: is a ``function``-scoped fixture, required by ``f1``: it needs to be instantiated at this point because it is a dependency of ``f1``. -4. ``f1``: is the first ``function``-scoped fixture in ``test_foo`` parameter list. -5. ``f2``: is the last ``function``-scoped fixture in ``test_foo`` parameter list. +3. ``a1``: is a ``function``-scoped ``autouse`` fixture: it will be instantiated before other fixtures + within the same scope. +4. ``f3``: is a ``function``-scoped fixture, required by ``f1``: it needs to be instantiated at this point +5. ``f1``: is the first ``function``-scoped fixture in ``test_foo`` parameter list. +6. ``f2``: is the last ``function``-scoped fixture in ``test_foo`` parameter list. .. _`finalization`: