Add autouse fixture order information (#3404).

A case with a fixture use both as an autouse and explititly
was raised. This case sounds too narrow to add to documentation
(and could be misleading for people learning pytest with explicitely
using an autouse fixture). At the same time there was no documentation
on the autouse vs regular fixture order, therefore this commit adds
such an information. Code sample grew and it was extracted to the file.

2 files changed, 48 insertions, 31 deletions

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