diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index f305cb2c2..c5bf67053 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -73,20 +73,20 @@ marked ``smtp`` fixture function. Running the test looks like this:: platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y rootdir: $REGENDOC_TMPDIR, inifile: collected 1 items - + test_smtpsimple.py F - + ======= FAILURES ======== _______ test_ehlo ________ - + smtp = - + def test_ehlo(smtp): response, msg = smtp.ehlo() assert response == 250 > assert 0 # for demo purposes E assert 0 - + test_smtpsimple.py:11: AssertionError ======= 1 failed in 0.12 seconds ======== @@ -169,7 +169,7 @@ function (in or below the directory where ``conftest.py`` is located):: response, msg = smtp.ehlo() assert response == 250 assert b"smtp.gmail.com" in msg - assert 0 # for demo purposes + assert 0 # for demo purposes def test_noop(smtp): response, msg = smtp.noop() @@ -184,32 +184,32 @@ inspect what is going on and can now run the tests:: platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y rootdir: $REGENDOC_TMPDIR, inifile: collected 2 items - + test_module.py FF - + ======= FAILURES ======== _______ test_ehlo ________ - + smtp = - + def test_ehlo(smtp): response, msg = smtp.ehlo() assert response == 250 assert b"smtp.gmail.com" in msg > assert 0 # for demo purposes E assert 0 - + test_module.py:6: AssertionError _______ test_noop ________ - + smtp = - + def test_noop(smtp): response, msg = smtp.noop() assert response == 250 > assert 0 # for demo purposes E assert 0 - + test_module.py:11: AssertionError ======= 2 failed in 0.12 seconds ======== @@ -260,7 +260,7 @@ Let's execute it:: $ pytest -s -q --tb=no FFteardown smtp - + 2 failed in 0.12 seconds We see that the ``smtp`` instance is finalized after the two @@ -290,7 +290,7 @@ because the ``smtp`` object automatically closes when the ``with`` statement ends. Note that if an exception happens during the *setup* code (before the ``yield`` keyword), the -*teardown* code (after the ``yield``) will not be called. +*teardown* code (after the ``yield``) will not be called. .. note:: @@ -302,7 +302,7 @@ Note that if an exception happens during the *setup* code (before the ``yield`` An alternative option for executing *teardown* code is to make use of the ``addfinalizer`` method of the `request-context`_ object to register -finalization functions. +finalization functions. Here's the ``smtp`` fixture changed to use ``addfinalizer`` for cleanup: @@ -321,7 +321,8 @@ Here's the ``smtp`` fixture changed to use ``addfinalizer`` for cleanup: request.addfinalizer(fin) return smtp # provide the fixture value -Both ``yield`` and ``addfinalizer`` methods work similar by calling their code after the test + +Both ``yield`` and ``addfinalizer`` methods work similarly by calling their code after the test ends, but ``addfinalizer`` has two key differences over ``yield``: 1. It is possible to register multiple finalizer functions. @@ -340,7 +341,8 @@ ends, but ``addfinalizer`` has two key differences over ``yield``: return r In the example above, if ``"C28"`` fails with an exception, ``"C1"`` and ``"C3"`` will still - be properly closed. + be properly closed. Of course, if an exception happens before the finalize function is + registered then it will not be executed. .. _`request-context`: @@ -371,7 +373,7 @@ again, nothing much has changed:: $ pytest -s -q --tb=no FFfinalizing (smtp.gmail.com) - + 2 failed in 0.12 seconds Let's quickly create another test module that actually sets the @@ -439,51 +441,51 @@ So let's just do another run:: FFFF ======= FAILURES ======== _______ test_ehlo[smtp.gmail.com] ________ - + smtp = - + def test_ehlo(smtp): response, msg = smtp.ehlo() assert response == 250 assert b"smtp.gmail.com" in msg > assert 0 # for demo purposes E assert 0 - + test_module.py:6: AssertionError _______ test_noop[smtp.gmail.com] ________ - + smtp = - + def test_noop(smtp): response, msg = smtp.noop() assert response == 250 > assert 0 # for demo purposes E assert 0 - + test_module.py:11: AssertionError _______ test_ehlo[mail.python.org] ________ - + smtp = - + def test_ehlo(smtp): response, msg = smtp.ehlo() assert response == 250 > assert b"smtp.gmail.com" in msg E AssertionError: assert b'smtp.gmail.com' in b'mail.python.org\nSIZE 51200000\nETRN\nSTARTTLS\nENHANCEDSTATUSCODES\n8BITMIME\nDSN\nSMTPUTF8' - + test_module.py:5: AssertionError -------------------------- Captured stdout setup --------------------------- finalizing _______ test_noop[mail.python.org] ________ - + smtp = - + def test_noop(smtp): response, msg = smtp.noop() assert response == 250 > assert 0 # for demo purposes E assert 0 - + test_module.py:11: AssertionError ------------------------- Captured stdout teardown ------------------------- finalizing @@ -555,7 +557,7 @@ Running the above tests results in the following test IDs being used:: - + ======= no tests ran in 0.12 seconds ======== .. _`interdependent fixtures`: @@ -594,10 +596,10 @@ Here we declare an ``app`` fixture which receives the previously defined cachedir: .cache rootdir: $REGENDOC_TMPDIR, inifile: collecting ... collected 2 items - + test_appsetup.py::test_smtp_exists[smtp.gmail.com] PASSED test_appsetup.py::test_smtp_exists[mail.python.org] PASSED - + ======= 2 passed in 0.12 seconds ======== Due to the parametrization of ``smtp`` the test will run twice with two @@ -663,26 +665,26 @@ Let's run the tests in verbose mode and with looking at the print-output:: cachedir: .cache rootdir: $REGENDOC_TMPDIR, inifile: collecting ... collected 8 items - + test_module.py::test_0[1] SETUP otherarg 1 RUN test0 with otherarg 1 PASSED TEARDOWN otherarg 1 - + test_module.py::test_0[2] SETUP otherarg 2 RUN test0 with otherarg 2 PASSED TEARDOWN otherarg 2 - + test_module.py::test_1[mod1] SETUP modarg mod1 RUN test1 with modarg mod1 PASSED test_module.py::test_2[1-mod1] SETUP otherarg 1 RUN test2 with otherarg 1 and modarg mod1 PASSED TEARDOWN otherarg 1 - + test_module.py::test_2[2-mod1] SETUP otherarg 2 RUN test2 with otherarg 2 and modarg mod1 PASSED TEARDOWN otherarg 2 - + test_module.py::test_1[mod2] TEARDOWN modarg mod1 SETUP modarg mod2 RUN test1 with modarg mod2 @@ -690,13 +692,13 @@ Let's run the tests in verbose mode and with looking at the print-output:: test_module.py::test_2[1-mod2] SETUP otherarg 1 RUN test2 with otherarg 1 and modarg mod2 PASSED TEARDOWN otherarg 1 - + test_module.py::test_2[2-mod2] SETUP otherarg 2 RUN test2 with otherarg 2 and modarg mod2 PASSED TEARDOWN otherarg 2 TEARDOWN modarg mod2 - - + + ======= 8 passed in 0.12 seconds ======== You can see that the parametrized module-scoped ``modarg`` resource caused an