Fixture functions using “yield” / context manager integration¶
New in version 2.4.
pytest-2.4 allows fixture functions to seamlessly use a
return statement to provide a fixture value while otherwise
fully supporting all other fixture features.
“yielding” fixture values is an experimental feature and its exact declaration may change later but earliest in a 2.5 release. You can thus safely use this feature in the 2.4 series but may need to adapt later. Test functions themselves will not need to change (as a general feature, they are ignorant of how fixtures are setup).
Let’s look at a simple standalone-example using the new
# 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 finalization through registering callbacks, our fixture function used a
statement to provide the lines of the
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.00 seconds
We can also seamlessly use the new syntax with
Let’s simplify the above
# 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
f will be closed after the test finished execution
because the Python
file object supports finalization when
with statement ends.
Note that the new syntax is fully integrated with using
params and other fixture features. Changing existing
fixture functions to use
yield is thus straight forward.
Discussion and future considerations / feedback¶
The yield-syntax has been discussed by pytest users extensively.
In general, the advantages of the using a
yield fixture syntax are:
- easy provision of fixtures in conjunction with context managers.
- no need to register a callback, providing for more synchronous
control flow in the fixture function. Also there is no need to accept
requestobject into the fixture function just for providing finalization code.
However, there are also limitations or foreseeable irritations:
yieldis 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 fixture parametrization mechanisms together with
yieldsyntax is similar to what
contextlib.contextmanager()decorated functions provide. With pytest fixture functions, the “after yield” part will always be invoked, independently from the exception status of the test function which uses the fixture. The pytest behaviour makes sense if you consider that many different test functions might use a module or session scoped fixture. Some test functions might raise exceptions and others not, so how could pytest re-raise a single exception at the
yieldpoint in the fixture function?
yieldintroduces more than one way to write fixture functions, so what’s the obvious way to a newcomer? Newcomers reading the docs will see feature examples using the
returnstyle so should use that, if in doubt. Others can start experimenting with writing yield-style fixtures and possibly help evolving them further.
If you want to feedback or participate in the ongoing discussion, please join our Contact channels. you are most welcome.