Merge pull request #2736 from xuanluong/issue-2604-documents-mark.with_args

[DOC] Add examples for mark.with_args
This commit is contained in:
Bruno Oliveira 2017-09-06 16:33:01 -03:00 committed by GitHub
commit 549f5c1a47
3 changed files with 45 additions and 1 deletions

View File

@ -173,5 +173,6 @@ Vidar T. Fauske
Vitaly Lashmanov Vitaly Lashmanov
Vlad Dragos Vlad Dragos
Wouter van Ackooy Wouter van Ackooy
Xuan Luong
Xuecong Liao Xuecong Liao
Zoltán Máté Zoltán Máté

1
changelog/2604.doc Normal file
View File

@ -0,0 +1 @@
In examples on working with custom markers, add examples demonstrating the usage of ``pytest.mark.MARKER_NAME.with_args`` in comparison with ``pytest.mark.MARKER_NAME.__call__``

View File

@ -393,7 +393,49 @@ The ``--markers`` option always gives you a list of available markers::
@pytest.mark.tryfirst: mark a hook implementation function such that the plugin machinery will try to call it first/as early as possible. @pytest.mark.tryfirst: mark a hook implementation function such that the plugin machinery will try to call it first/as early as possible.
@pytest.mark.trylast: mark a hook implementation function such that the plugin machinery will try to call it last/as late as possible. @pytest.mark.trylast: mark a hook implementation function such that the plugin machinery will try to call it last/as late as possible.
.. _`passing callables to custom markers`:
Passing a callable to custom markers
--------------------------------------------
.. regendoc:wipe
Below is the config file that will be used in the next examples::
# content of conftest.py
import sys
def pytest_runtest_setup(item):
marker = item.get_marker('my_marker')
if marker is not None:
for info in marker:
print('Marker info name={} args={} kwars={}'.format(info.name, info.args, info.kwargs))
sys.stdout.flush()
A custom marker can have its argument set, i.e. ``args`` and ``kwargs`` properties, defined by either invoking it as a callable or using ``pytest.mark.MARKER_NAME.with_args``. These two methods achieve the same effect most of the time.
However, if there is a callable as the single positional argument with no keyword arguments, using the ``pytest.mark.MARKER_NAME(c)`` will not pass ``c`` as a positional argument but decorate ``c`` with the custom marker (see :ref:`MarkDecorator <mark>`). Fortunately, ``pytest.mark.MARKER_NAME.with_args`` comes to the rescue::
# content of test_custom_marker.py
import pytest
def hello_world(*args, **kwargs):
return 'Hello World'
@pytest.mark.my_marker.with_args(hello_world)
def test_with_args():
pass
The output is as follows::
$ pytest -q -s
Marker info name=my_marker args=(<function hello_world at 0x7f0b7b058bf8>,) kwars={}
.
1 passed in 0.01 seconds
We can see that the custom marker has its argument set extended with the function ``hello_world``. This is the key different between creating a custom marker as a callable, which invokes ``__call__`` behind the scenes, and using ``with_args``.
Reading markers which were set from multiple places Reading markers which were set from multiple places
---------------------------------------------------- ----------------------------------------------------