Add autouse fixture order information (#3404).

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"]

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`: