From 689176f30c8e8a92cc8f8d22f4821d7fa7c7fe75 Mon Sep 17 00:00:00 2001
From: aizpurua23a <57321880+aizpurua23a@users.noreply.github.com>
Date: Tue, 26 Jul 2022 21:22:15 +0200
Subject: [PATCH] Update fixtures.rst with finalizer execution order

Add note to clarify the difference in execution order between after-yield finalizers and `request.addfinalizer` finalizers.
---
 doc/en/how-to/fixtures.rst | 61 ++++++++++++++++++++++++++++++++++----
 1 file changed, 56 insertions(+), 5 deletions(-)

diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst
index b90b40619..d4aa13a7d 100644
--- a/doc/en/how-to/fixtures.rst
+++ b/doc/en/how-to/fixtures.rst
@@ -729,15 +729,66 @@ Here's how the previous example would look using the ``addfinalizer`` method:
         assert email in receiving_user.inbox
 
 
-It's a bit longer than yield fixtures and a bit more complex, but it
-does offer some nuances for when you're in a pinch.
+Here's how the previous example would look using the ``addfinalizer`` method:
+ It's a bit longer than yield fixtures and a bit more complex, but it
+ does offer some nuances for when you're in a pinch.
+
+Note on finalizer order
+""""""""""""""""""""""""
+
+Finalizers are executed in a first-in-last-out order, while operations after yield are executed sequentially.
+Consider the differences in the following examples:
+
+.. code-block:: python
+
+    import pytest
+    from functools import partial
+
+
+    @pytest.fixture
+    def fix_w_finalizers(request):
+        request.addfinalizer(partial(print, "finalizer_2"))
+        request.addfinalizer(partial(print, "finalizer_1"))
+
+    @pytest.fixture
+    def fix_w_yield():
+        yield
+        print("after_yield_1")
+        print("after_yield_2")
+
+
+    def test_foo(fix_w_finalizers):
+        print("test_foo")
+        pass
+
+
+    def test_bar(fix_w_yield):
+        print("test_bar")
+        pass
+
+
 
 .. code-block:: pytest
 
-   $ pytest -q test_emaillib.py
-   .                                                                    [100%]
-   1 passed in 0.12s
+    $ pytest test_module.py
+    =========================== test session starts ============================
+    platform linux -- Python 3.x.y, pytest-7.x.y, pluggy-1.x.y
+    collected 2 items
 
+    main.py
+    test_foo
+    .finalizer_1
+    finalizer_2
+
+    test_bar
+    .after_yield_1
+    after_yield_2
+
+
+.. code-block:: pytest
+   $ pytest -q test_emaillib.py
+  .                                                                    [100%]
+  1 passed in 0.12s
 .. _`safe teardowns`:
 
 Safe teardowns