263 lines
9.1 KiB
Plaintext
263 lines
9.1 KiB
Plaintext
==============================================================
|
|
Injecting objects into test functions (funcargs)
|
|
==============================================================
|
|
|
|
.. currentmodule:: _pytest.python
|
|
|
|
|
|
.. _`funcargs`:
|
|
.. _`funcarg mechanism`:
|
|
|
|
Dependency injection through function arguments
|
|
=================================================
|
|
|
|
py.test lets you inject objects into test functions and precisely
|
|
control their life cycle in relation to the test execution. It is
|
|
also possible to run a test function multiple times with different objects.
|
|
|
|
The basic mechanism for injecting objects is also called the
|
|
*funcarg mechanism* because objects are ultimatly injected
|
|
by calling a test function with it as an argument. Unlike the
|
|
classical xUnit approach *funcargs* relate more to `Dependency Injection`_
|
|
because they help to de-couple test code from objects required for
|
|
them to execute.
|
|
|
|
.. _`Dependency injection`: http://en.wikipedia.org/wiki/Dependency_injection
|
|
|
|
To create a value with which to call a test function a factory function
|
|
is called which gets full access to the test function context and can
|
|
register finalizers or invoke lifecycle-caching helpers. The factory
|
|
can be implemented in same test class or test module, or in a
|
|
per-directory ``conftest.py`` file or even in an external plugin. This
|
|
allows full de-coupling of test code and objects needed for test
|
|
execution.
|
|
|
|
A test function may be invoked multiple times in which case we
|
|
speak of :ref:`parametrized testing <parametrizing-tests>`. This can be
|
|
very useful if you want to test e.g. against different database backends
|
|
or with multiple numerical arguments sets and want to reuse the same set
|
|
of test functions.
|
|
|
|
py.test comes with :ref:`builtinfuncargs` and there are some refined usages in the examples section.
|
|
|
|
.. _funcarg:
|
|
|
|
Basic injection example
|
|
--------------------------------
|
|
|
|
Let's look at a simple self-contained test module::
|
|
|
|
# content of ./test_simplefactory.py
|
|
def pytest_funcarg__myfuncarg(request):
|
|
return 42
|
|
|
|
def test_function(myfuncarg):
|
|
assert myfuncarg == 17
|
|
|
|
This test function needs an injected object named ``myfuncarg``.
|
|
py.test will discover and call the factory named
|
|
``pytest_funcarg__myfuncarg`` within the same module in this case.
|
|
|
|
Running the test looks like this::
|
|
|
|
$ py.test test_simplefactory.py
|
|
=========================== test session starts ============================
|
|
platform darwin -- Python 2.7.1 -- pytest-2.1.3
|
|
collecting ... collected 1 items
|
|
|
|
test_simplefactory.py F
|
|
|
|
================================= FAILURES =================================
|
|
______________________________ test_function _______________________________
|
|
|
|
myfuncarg = 42
|
|
|
|
def test_function(myfuncarg):
|
|
> assert myfuncarg == 17
|
|
E assert 42 == 17
|
|
|
|
test_simplefactory.py:5: AssertionError
|
|
========================= 1 failed in 0.02 seconds =========================
|
|
|
|
This means that indeed the test function was called with a ``myfuncarg``
|
|
argument value of ``42`` and the assert fails. Here is how py.test
|
|
comes to call the test function this way:
|
|
|
|
1. py.test :ref:`finds <test discovery>` the ``test_function`` because
|
|
of the ``test_`` prefix. The test function needs a function argument
|
|
named ``myfuncarg``. A matching factory function is discovered by
|
|
looking for the name ``pytest_funcarg__myfuncarg``.
|
|
|
|
2. ``pytest_funcarg__myfuncarg(request)`` is called and
|
|
returns the value for ``myfuncarg``.
|
|
|
|
3. the test function can now be called: ``test_function(42)``.
|
|
This results in the above exception because of the assertion
|
|
mismatch.
|
|
|
|
Note that if you misspell a function argument or want
|
|
to use one that isn't available, you'll see an error
|
|
with a list of available function arguments.
|
|
|
|
You can always issue::
|
|
|
|
py.test --funcargs test_simplefactory.py
|
|
|
|
to see available function arguments (which you can also
|
|
think of as "resources").
|
|
|
|
|
|
.. _`parametrizing tests, generalized`: http://tetamap.wordpress.com/2009/05/13/parametrizing-python-tests-generalized/
|
|
|
|
.. _`blog post about the monkeypatch funcarg`: http://tetamap.wordpress.com/2009/03/03/monkeypatching-in-unit-tests-done-right/
|
|
.. _`xUnit style`: xunit_setup.html
|
|
|
|
|
|
.. _`funcarg factory`:
|
|
.. _factory:
|
|
|
|
The funcarg **request** object
|
|
=============================================
|
|
|
|
Each funcarg factory receives a **request** object which is tied to a
|
|
specific test function call. A request object is passed to a funcarg
|
|
factory and provides access to test configuration and context:
|
|
|
|
.. autoclass:: _pytest.python.FuncargRequest()
|
|
:members: function,cls,module,keywords,config
|
|
|
|
.. _`useful caching and finalization helpers`:
|
|
|
|
.. automethod:: FuncargRequest.addfinalizer
|
|
|
|
.. automethod:: FuncargRequest.cached_setup
|
|
|
|
.. automethod:: FuncargRequest.applymarker
|
|
|
|
.. automethod:: FuncargRequest.getfuncargvalue
|
|
|
|
|
|
.. _`test generators`:
|
|
.. _`parametrizing-tests`:
|
|
.. _`parametrized test functions`:
|
|
|
|
Parametrizing multiple calls to a test function
|
|
===========================================================
|
|
|
|
You can parametrize multiple runs of the same test
|
|
function by adding new test function calls with different
|
|
function argument values. Let's look at a simple self-contained
|
|
example:
|
|
|
|
Basic generated test example
|
|
----------------------------
|
|
|
|
Let's consider a test module which uses the ``pytest_generate_tests``
|
|
hook to generate several calls to the same test function::
|
|
|
|
# content of test_example.py
|
|
def pytest_generate_tests(metafunc):
|
|
if "numiter" in metafunc.funcargnames:
|
|
for i in range(10):
|
|
metafunc.addcall(funcargs=dict(numiter=i))
|
|
|
|
def test_func(numiter):
|
|
assert numiter < 9
|
|
|
|
Running this::
|
|
|
|
$ py.test test_example.py
|
|
=========================== test session starts ============================
|
|
platform darwin -- Python 2.7.1 -- pytest-2.1.3
|
|
collecting ... collected 10 items
|
|
|
|
test_example.py .........F
|
|
|
|
================================= FAILURES =================================
|
|
_______________________________ test_func[9] _______________________________
|
|
|
|
numiter = 9
|
|
|
|
def test_func(numiter):
|
|
> assert numiter < 9
|
|
E assert 9 < 9
|
|
|
|
test_example.py:7: AssertionError
|
|
==================== 1 failed, 9 passed in 0.04 seconds ====================
|
|
|
|
Note that the ``pytest_generate_tests(metafunc)`` hook is called during
|
|
the test collection phase which is separate from the actual test running.
|
|
Let's just look at what is collected::
|
|
|
|
$ py.test --collectonly test_example.py
|
|
=========================== test session starts ============================
|
|
platform darwin -- Python 2.7.1 -- pytest-2.1.3
|
|
collecting ... collected 10 items
|
|
<Module 'test_example.py'>
|
|
<Function 'test_func[0]'>
|
|
<Function 'test_func[1]'>
|
|
<Function 'test_func[2]'>
|
|
<Function 'test_func[3]'>
|
|
<Function 'test_func[4]'>
|
|
<Function 'test_func[5]'>
|
|
<Function 'test_func[6]'>
|
|
<Function 'test_func[7]'>
|
|
<Function 'test_func[8]'>
|
|
<Function 'test_func[9]'>
|
|
|
|
============================= in 0.01 seconds =============================
|
|
|
|
If you want to select only the run with the value ``7`` you could do::
|
|
|
|
$ py.test -v -k 7 test_example.py # or -k test_func[7]
|
|
=========================== test session starts ============================
|
|
platform darwin -- Python 2.7.1 -- pytest-2.1.3 -- /Users/hpk/venv/0/bin/python
|
|
collecting ... collected 10 items
|
|
|
|
test_example.py:6: test_func[0] PASSED
|
|
test_example.py:6: test_func[1] PASSED
|
|
test_example.py:6: test_func[2] PASSED
|
|
test_example.py:6: test_func[3] PASSED
|
|
test_example.py:6: test_func[4] PASSED
|
|
test_example.py:6: test_func[5] PASSED
|
|
test_example.py:6: test_func[6] PASSED
|
|
test_example.py:6: test_func[7] PASSED
|
|
test_example.py:6: test_func[8] PASSED
|
|
test_example.py:6: test_func[9] FAILED
|
|
|
|
================================= FAILURES =================================
|
|
_______________________________ test_func[9] _______________________________
|
|
|
|
numiter = 9
|
|
|
|
def test_func(numiter):
|
|
> assert numiter < 9
|
|
E assert 9 < 9
|
|
|
|
test_example.py:7: AssertionError
|
|
==================== 1 failed, 9 passed in 0.05 seconds ====================
|
|
|
|
You might want to look at :ref:`more parametrization examples <paramexamples>`.
|
|
|
|
.. _`metafunc object`:
|
|
|
|
The **metafunc** object
|
|
-------------------------------------------
|
|
|
|
metafunc objects are passed to the ``pytest_generate_tests`` hook.
|
|
They help to inspect a testfunction and to generate tests
|
|
according to test configuration or values specified
|
|
in the class or module where a test function is defined:
|
|
|
|
``metafunc.funcargnames``: set of required function arguments for given function
|
|
|
|
``metafunc.function``: underlying python test function
|
|
|
|
``metafunc.cls``: class object where the test function is defined in or None.
|
|
|
|
``metafunc.module``: the module object where the test function is defined in.
|
|
|
|
``metafunc.config``: access to command line opts and general config
|
|
|
|
.. automethod:: Metafunc.addcall(funcargs=None, id=_notexists, param=_notexists)
|