test_ok1/doc/en/yieldfixture.txt

.. _yieldfixture:

Fixture functions using "yield" / context manager integration
---------------------------------------------------------------

.. versionadded:: 2.4

.. regendoc:wipe

pytest-2.4 allows fixture functions to seamlessly use a ``yield`` instead 
of a ``return`` statement to provide a fixture value while otherwise
fully supporting all other fixture features.

Let's look at a simple standalone-example using the ``yield`` syntax::

    # content of test_yield.py
    
    import pytest

    @pytest.yield_fixture
    def passwd():
        print ("\nsetup before yield")
        f = open("/etc/passwd")
        yield f.readlines()
        print ("teardown after yield")
        f.close()

    def test_has_lines(passwd):
        print ("test called")
        assert passwd

In contrast to :ref:`finalization through registering callbacks
<finalization>`, our fixture function used a ``yield``
statement to provide the lines of the ``/etc/passwd`` file.  
The code after the ``yield`` statement serves as the teardown code, 
avoiding the indirection of registering a teardown callback function.   

Let's run it with output capturing disabled::

    $ py.test -q -s test_yield.py
    
    setup before yield
    test called
    .teardown after yield
    
    1 passed in 0.01 seconds

We can also seamlessly use the new syntax with ``with`` statements.
Let's simplify the above ``passwd`` fixture::

    # content of test_yield2.py
    
    import pytest

    @pytest.yield_fixture
    def passwd():
        with open("/etc/passwd") as f:
            yield f.readlines()

    def test_has_lines(passwd):
        assert len(passwd) >= 1

The file ``f`` will be closed after the test finished execution
because the Python ``file`` object supports finalization when
the ``with`` statement ends. 

Note that the yield fixture form supports all other fixture
features such as ``scope``, ``params``, etc., thus changing existing
fixture functions to use ``yield`` is straightforward.

.. note::

    While the ``yield`` syntax is similar to what
    :py:func:`contextlib.contextmanager` decorated functions
    provide, with pytest fixture functions the part after the
    "yield" will always be invoked, independently from the
    exception status of the test function which uses the fixture.
    This behaviour makes sense if you consider that many different
    test functions might use a module or session scoped fixture.


Discussion and future considerations / feedback
++++++++++++++++++++++++++++++++++++++++++++++++++++

There are some topics that are worth mentioning:

- usually ``yield`` is used for producing multiple values.
  But fixture functions can only yield exactly one value.
  Yielding a second fixture value will get you an error.
  It's possible we can evolve pytest to allow for producing
  multiple values as an alternative to current parametrization.
  For now, you can just use the normal
  :ref:`fixture parametrization <fixture-parametrize>`
  mechanisms together with ``yield``-style fixtures.

- lastly ``yield`` introduces more than one way to write
  fixture functions, so what's the obvious way to a newcomer?

If you want to feedback or participate in discussion of the above
topics, please join our :ref:`contact channels`, you are most welcome.