Add documentation for "invocation" scoped fixture
This commit is contained in:
parent
7a2058e3db
commit
29289b472f
|
@ -603,7 +603,7 @@ first execute with one instance and then finalizers are called
|
|||
before the next fixture instance is created. Among other things,
|
||||
this eases testing of applications which create and use global state.
|
||||
|
||||
The following example uses two parametrized funcargs, one of which is
|
||||
The following example uses two parametrized fixture, one of which is
|
||||
scoped on a per-module basis, and all the functions perform ``print`` calls
|
||||
to show the setup/teardown flow::
|
||||
|
||||
|
@ -863,6 +863,14 @@ All test methods in this TestClass will use the transaction fixture while
|
|||
other test classes or functions in the module will not use it unless
|
||||
they also add a ``transact`` reference.
|
||||
|
||||
invocation-scoped fixtures
|
||||
--------------------------
|
||||
|
||||
pytest 3.0 introduced a new advanced scope for fixtures: ``"invocation"``. Fixtures marked with
|
||||
this scope can be requested from any other scope, providing a version of the fixture for that scope.
|
||||
|
||||
See more in :ref:`invocation_scoped_fixture`.
|
||||
|
||||
Shifting (visibility of) fixture functions
|
||||
----------------------------------------------------
|
||||
|
||||
|
|
|
@ -0,0 +1,61 @@
|
|||
.. _invocation_scoped_fixture:
|
||||
|
||||
Invocation-scoped fixtures
|
||||
==========================
|
||||
|
||||
.. versionadded:: 3.0
|
||||
|
||||
.. note::
|
||||
This feature is experimental, so if decided that it brings too much problems
|
||||
or considered too complicated it might be removed in pytest ``3.1``.
|
||||
|
||||
``tmpdir`` and ``monkeypatch`` might become ``invocation`` scoped
|
||||
fixtures in the future if decided to keep invocation-scoped fixtures.
|
||||
|
||||
Fixtures can be defined with ``invocation`` scope, meaning that the fixture
|
||||
can be requested by fixtures from any scope, but when they do they assume
|
||||
the same scope as the fixture requesting it.
|
||||
|
||||
An ``invocation``-scoped fixture can be requested from different scopes
|
||||
in the same test session, in which case each scope will have its own copy.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
Consider a fixture which manages external process execution:
|
||||
this fixture provides auxiliary methods for tests and fixtures to start external
|
||||
processes while making sure the
|
||||
processes terminate at the appropriate time. Because it makes sense
|
||||
to start a webserver for the entire session and also to execute a numerical
|
||||
simulation for a single test function, the ``process_manager``
|
||||
fixture can be declared as ``invocation``, so each scope gets its own
|
||||
value and can manage processes which will live for the duration of the scope.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import pytest
|
||||
|
||||
@pytest.fixture(scope='invocation')
|
||||
def process_manager():
|
||||
m = ProcessManager()
|
||||
yield m
|
||||
m.shutdown_all()
|
||||
|
||||
|
||||
@pytest.fixture(scope='session')
|
||||
def server(process_manager):
|
||||
process_manager.start(sys.executable, 'server.py')
|
||||
|
||||
|
||||
@pytest.fixture(scope='function')
|
||||
def start_simulation(process_manager):
|
||||
import functools
|
||||
return functools.partial(process_manager.start,
|
||||
sys.executable, 'simulator.py')
|
||||
|
||||
|
||||
In the above code, simulators started using ``start_simulation`` will be
|
||||
terminated when the test function exits, while the server will be kept
|
||||
active for the entire simulation run, being terminated when the test session
|
||||
finishes.
|
||||
|
Loading…
Reference in New Issue