<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Working with custom markers</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2.2.4',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="None" href="../index.html" />
<link rel="up" title="Usages and Examples" href="index.html" />
<link rel="next" title="Changing standard (Python) test discovery" href="pythoncollection.html" />
<link rel="prev" title="Parametrizing tests" href="parametrize.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../py-modindex.html" title="Python Module Index"
>modules</a></li>
<li class="right" >
<a href="pythoncollection.html" title="Changing standard (Python) test discovery"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="parametrize.html" title="Parametrizing tests"
accesskey="P">previous</a> |</li>
<li><a href="../contents.html">pytest-2.2.4</a> »</li>
<li><a href="index.html" accesskey="U">Usages and Examples</a> »</li>
<g:plusone></g:plusone>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<div id="searchbox" style="display: none">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Search" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
<h3>quicklinks</h3>
<div style="text-align: left; font-size: 100%; vertical-align: middle;">
<table>
<tr>
<td>
<a href="../index.html">home</a>
</td><td>
<a href="../contents.html">TOC/contents</a>
</td></tr><tr><td>
<a href="../getting-started.html">install</a>
</td><td>
<a href="../changelog.html">changelog</a>
</td></tr><tr><td>
<a href="index.html">examples</a>
</td><td>
<a href="../customize.html">customize</a>
</td></tr><tr><td>
<a href="https://bitbucket.org/hpk42/pytest/issues?status=new&status=open">issues[bb]</a>
</td><td>
<a href="../contact.html">contact</a>
</td></tr></table>
</div>
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Working with custom markers</a><ul>
<li><a class="reference internal" href="#marking-test-functions-and-selecting-them-for-a-run">Marking test functions and selecting them for a run</a></li>
<li><a class="reference internal" href="#registering-markers">Registering markers</a></li>
<li><a class="reference internal" href="#marking-whole-classes-or-modules">Marking whole classes or modules</a></li>
<li><a class="reference internal" href="#using-k-text-to-select-tests">Using <tt class="docutils literal"><span class="pre">-k</span> <span class="pre">TEXT</span></tt> to select tests</a></li>
<li><a class="reference internal" href="#custom-marker-and-command-line-option-to-control-test-runs">Custom marker and command line option to control test runs</a></li>
<li><a class="reference internal" href="#reading-markers-which-were-set-from-multiple-places">Reading markers which were set from multiple places</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="parametrize.html"
title="previous chapter">Parametrizing tests</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="pythoncollection.html"
title="next chapter">Changing standard (Python) test discovery</a></p>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="working-with-custom-markers">
<span id="mark-examples"></span><h1>Working with custom markers<a class="headerlink" href="#working-with-custom-markers" title="Permalink to this headline">¶</a></h1>
<p>Here are some example using the <a class="reference internal" href="../mark.html#mark"><em>Marking test functions with attributes</em></a> mechanism.</p>
<div class="section" id="marking-test-functions-and-selecting-them-for-a-run">
<h2>Marking test functions and selecting them for a run<a class="headerlink" href="#marking-test-functions-and-selecting-them-for-a-run" title="Permalink to this headline">¶</a></h2>
<p>You can “mark” a test function with custom metadata like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_server.py</span>
<span class="kn">import</span> <span class="nn">pytest</span>
<span class="nd">@pytest.mark.webtest</span>
<span class="k">def</span> <span class="nf">test_send_http</span><span class="p">():</span>
<span class="k">pass</span> <span class="c"># perform some webtest test for your app</span>
<span class="k">def</span> <span class="nf">test_something_quick</span><span class="p">():</span>
<span class="k">pass</span>
</pre></div>
</div>
<p class="versionadded">
<span class="versionmodified">New in version 2.2.</span></p>
<p>You can then restrict a test run to only run tests marked with <tt class="docutils literal"><span class="pre">webtest</span></tt>:</p>
<div class="highlight-python"><pre>$ py.test -v -m webtest
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.2.2 -- /Users/hpk/venv/0/bin/python
collecting ... collected 2 items
test_server.py:3: test_send_http PASSED
=================== 1 tests deselected by "-m 'webtest'" ===================
================== 1 passed, 1 deselected in 0.01 seconds ==================</pre>
</div>
<p>Or the inverse, running all tests except the webtest ones:</p>
<div class="highlight-python"><pre>$ py.test -v -m "not webtest"
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.2.2 -- /Users/hpk/venv/0/bin/python
collecting ... collected 2 items
test_server.py:6: test_something_quick PASSED
================= 1 tests deselected by "-m 'not webtest'" =================
================== 1 passed, 1 deselected in 0.02 seconds ==================</pre>
</div>
</div>
<div class="section" id="registering-markers">
<h2>Registering markers<a class="headerlink" href="#registering-markers" title="Permalink to this headline">¶</a></h2>
<p class="versionadded">
<span class="versionmodified">New in version 2.2.</span></p>
<p>Registering markers for your test suite is simple:</p>
<div class="highlight-python"><pre># content of pytest.ini
[pytest]
markers =
webtest: mark a test as a webtest.</pre>
</div>
<p>You can ask which markers exist for your test suite - the list includes our just defined <tt class="docutils literal"><span class="pre">webtest</span></tt> markers:</p>
<div class="highlight-python"><pre>$ py.test --markers
@pytest.mark.webtest: mark a test as a webtest.
@pytest.mark.skipif(*conditions): skip the given test function if evaluation of all conditions has a True value. Evaluation happens within the module global context. Example: skipif('sys.platform == "win32"') skips the test if we are on the win32 platform.
@pytest.mark.xfail(*conditions, reason=None, run=True): mark the the test function as an expected failure. Optionally specify a reason and run=False if you don't even want to execute the test function. Any positional condition strings will be evaluated (like with skipif) and if one is False the marker will not be applied.
@pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in multiple different argument value sets. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.
@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.</pre>
</div>
<p>For an example on how to add and work with markers from a plugin, see
<a class="reference internal" href="#adding-a-custom-marker-from-a-plugin"><em>Custom marker and command line option to control test runs</em></a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>It is recommended to explicitely register markers so that:</p>
<ul class="last simple">
<li>there is one place in your test suite defining your markers</li>
<li>asking for existing markers via <tt class="docutils literal"><span class="pre">py.test</span> <span class="pre">--markers</span></tt> gives good output</li>
<li>typos in function markers are treated as an error if you use
the <tt class="docutils literal"><span class="pre">--strict</span></tt> option. Later versions of py.test are probably
going to treat non-registered markers as an error.</li>
</ul>
</div>
</div>
<div class="section" id="marking-whole-classes-or-modules">
<span id="scoped-marking"></span><h2>Marking whole classes or modules<a class="headerlink" href="#marking-whole-classes-or-modules" title="Permalink to this headline">¶</a></h2>
<p>If you are programming with Python 2.6 or later you may use <tt class="docutils literal"><span class="pre">pytest.mark</span></tt>
decorators with classes to apply markers to all of its test methods:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_mark_classlevel.py</span>
<span class="kn">import</span> <span class="nn">pytest</span>
<span class="nd">@pytest.mark.webtest</span>
<span class="k">class</span> <span class="nc">TestClass</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">test_startup</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">pass</span>
<span class="k">def</span> <span class="nf">test_startup_and_more</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>This is equivalent to directly applying the decorator to the
two test functions.</p>
<p>To remain backward-compatible with Python 2.4 you can also set a
<tt class="docutils literal"><span class="pre">pytestmark</span></tt> attribute on a TestClass like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pytest</span>
<span class="k">class</span> <span class="nc">TestClass</span><span class="p">:</span>
<span class="n">pytestmark</span> <span class="o">=</span> <span class="n">pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">webtest</span>
</pre></div>
</div>
<p>or if you need to use multiple markers you can use a list:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pytest</span>
<span class="k">class</span> <span class="nc">TestClass</span><span class="p">:</span>
<span class="n">pytestmark</span> <span class="o">=</span> <span class="p">[</span><span class="n">pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">webtest</span><span class="p">,</span> <span class="n">pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">slowtest</span><span class="p">]</span>
</pre></div>
</div>
<p>You can also set a module level marker:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pytest</span>
<span class="n">pytestmark</span> <span class="o">=</span> <span class="n">pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">webtest</span>
</pre></div>
</div>
<p>in which case it will be applied to all functions and
methods defined in the module.</p>
</div>
<div class="section" id="using-k-text-to-select-tests">
<h2>Using <tt class="docutils literal"><span class="pre">-k</span> <span class="pre">TEXT</span></tt> to select tests<a class="headerlink" href="#using-k-text-to-select-tests" title="Permalink to this headline">¶</a></h2>
<p>You can use the <tt class="docutils literal"><span class="pre">-k</span></tt> command line option to only run tests with names matching
the given argument:</p>
<div class="highlight-python"><pre>$ py.test -k send_http # running with the above defined examples
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.2.2
collecting ... collected 4 items
test_server.py .
=================== 3 tests deselected by '-ksend_http' ====================
================== 1 passed, 3 deselected in 0.02 seconds ==================</pre>
</div>
<p>And you can also run all tests except the ones that match the keyword:</p>
<div class="highlight-python"><pre>$ py.test -k-send_http
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.2.2
collecting ... collected 4 items
test_mark_classlevel.py ..
test_server.py .
=================== 1 tests deselected by '-k-send_http' ===================
================== 3 passed, 1 deselected in 0.03 seconds ==================</pre>
</div>
<p>Or to only select the class:</p>
<div class="highlight-python"><pre>$ py.test -kTestClass
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.2.2
collecting ... collected 4 items
test_mark_classlevel.py ..
=================== 2 tests deselected by '-kTestClass' ====================
================== 2 passed, 2 deselected in 0.03 seconds ==================</pre>
</div>
</div>
<div class="section" id="custom-marker-and-command-line-option-to-control-test-runs">
<span id="adding-a-custom-marker-from-a-plugin"></span><h2>Custom marker and command line option to control test runs<a class="headerlink" href="#custom-marker-and-command-line-option-to-control-test-runs" title="Permalink to this headline">¶</a></h2>
<p>Plugins can provide custom markers and implement specific behaviour
based on it. This is a self-contained example which adds a command
line option and a parametrized test function marker to run tests
specifies via named environments:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of conftest.py</span>
<span class="kn">import</span> <span class="nn">pytest</span>
<span class="k">def</span> <span class="nf">pytest_addoption</span><span class="p">(</span><span class="n">parser</span><span class="p">):</span>
<span class="n">parser</span><span class="o">.</span><span class="n">addoption</span><span class="p">(</span><span class="s">"-E"</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s">"env"</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">"store"</span><span class="p">,</span> <span class="n">metavar</span><span class="o">=</span><span class="s">"NAME"</span><span class="p">,</span>
<span class="n">help</span><span class="o">=</span><span class="s">"only run tests matching the environment NAME."</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">pytest_configure</span><span class="p">(</span><span class="n">config</span><span class="p">):</span>
<span class="c"># register an additional marker</span>
<span class="n">config</span><span class="o">.</span><span class="n">addinivalue_line</span><span class="p">(</span><span class="s">"markers"</span><span class="p">,</span>
<span class="s">"env(name): mark test to run only on named environment"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">pytest_runtest_setup</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
<span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="n">item</span><span class="o">.</span><span class="n">Function</span><span class="p">):</span>
<span class="k">return</span>
<span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">item</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="s">'env'</span><span class="p">):</span>
<span class="n">envmarker</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">item</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="s">'env'</span><span class="p">)</span>
<span class="n">envname</span> <span class="o">=</span> <span class="n">envmarker</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
<span class="k">if</span> <span class="n">envname</span> <span class="o">!=</span> <span class="n">item</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">option</span><span class="o">.</span><span class="n">env</span><span class="p">:</span>
<span class="n">pytest</span><span class="o">.</span><span class="n">skip</span><span class="p">(</span><span class="s">"test requires env </span><span class="si">%r</span><span class="s">"</span> <span class="o">%</span> <span class="n">envname</span><span class="p">)</span>
</pre></div>
</div>
<p>A test file using this local plugin:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_someenv.py</span>
<span class="kn">import</span> <span class="nn">pytest</span>
<span class="nd">@pytest.mark.env</span><span class="p">(</span><span class="s">"stage1"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_basic_db_operation</span><span class="p">():</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>and an example invocations specifying a different environment than what
the test needs:</p>
<div class="highlight-python"><pre>$ py.test -E stage2
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.2.2
collecting ... collected 1 items
test_someenv.py s
======================== 1 skipped in 0.02 seconds =========================</pre>
</div>
<p>and here is one that specifies exactly the environment needed:</p>
<div class="highlight-python"><pre>$ py.test -E stage1
=========================== test session starts ============================
platform darwin -- Python 2.7.1 -- pytest-2.2.2
collecting ... collected 1 items
test_someenv.py .
========================= 1 passed in 0.02 seconds =========================</pre>
</div>
<p>The <tt class="docutils literal"><span class="pre">--markers</span></tt> option always gives you a list of available markers:</p>
<div class="highlight-python"><pre>$ py.test --markers
@pytest.mark.env(name): mark test to run only on named environment
@pytest.mark.skipif(*conditions): skip the given test function if evaluation of all conditions has a True value. Evaluation happens within the module global context. Example: skipif('sys.platform == "win32"') skips the test if we are on the win32 platform.
@pytest.mark.xfail(*conditions, reason=None, run=True): mark the the test function as an expected failure. Optionally specify a reason and run=False if you don't even want to execute the test function. Any positional condition strings will be evaluated (like with skipif) and if one is False the marker will not be applied.
@pytest.mark.parametrize(argnames, argvalues): call a test function multiple times passing in multiple different argument value sets. Example: @parametrize('arg1', [1,2]) would lead to two calls of the decorated test function, one with arg1=1 and another with arg1=2.
@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.</pre>
</div>
</div>
<div class="section" id="reading-markers-which-were-set-from-multiple-places">
<h2>Reading markers which were set from multiple places<a class="headerlink" href="#reading-markers-which-were-set-from-multiple-places" title="Permalink to this headline">¶</a></h2>
<p>If you are heavily using markers in your test suite you may encounter the case where a marker is applied several times to a test function. From plugin
code you can read over all such settings. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_mark_three_times.py</span>
<span class="kn">import</span> <span class="nn">pytest</span>
<span class="n">pytestmark</span> <span class="o">=</span> <span class="n">pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="s">"module"</span><span class="p">,</span> <span class="n">x</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="nd">@pytest.mark.glob</span><span class="p">(</span><span class="s">"class"</span><span class="p">,</span> <span class="n">x</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">TestClass</span><span class="p">:</span>
<span class="nd">@pytest.mark.glob</span><span class="p">(</span><span class="s">"function"</span><span class="p">,</span> <span class="n">x</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_something</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">pass</span>
</pre></div>
</div>
<p>Here we have the marker “glob” applied three times to the same
test function. From a conftest file we can read it like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of conftest.py</span>
<span class="k">def</span> <span class="nf">pytest_runtest_setup</span><span class="p">(</span><span class="n">item</span><span class="p">):</span>
<span class="n">g</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">item</span><span class="o">.</span><span class="n">obj</span><span class="p">,</span> <span class="s">'glob'</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
<span class="k">if</span> <span class="n">g</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span>
<span class="k">for</span> <span class="n">info</span> <span class="ow">in</span> <span class="n">g</span><span class="p">:</span>
<span class="k">print</span> <span class="p">(</span><span class="s">"glob args=</span><span class="si">%s</span><span class="s"> kwargs=</span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span><span class="p">(</span><span class="n">info</span><span class="o">.</span><span class="n">args</span><span class="p">,</span> <span class="n">info</span><span class="o">.</span><span class="n">kwargs</span><span class="p">))</span>
</pre></div>
</div>
<p>Let’s run this without capturing output and see what we get:</p>
<div class="highlight-python"><pre>$ py.test -q -s
collecting ... collected 2 items
..
2 passed in 0.02 seconds
glob args=('function',) kwargs={'x': 3}
glob args=('class',) kwargs={'x': 2}
glob args=('module',) kwargs={'x': 1}</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../py-modindex.html" title="Python Module Index"
>modules</a></li>
<li class="right" >
<a href="pythoncollection.html" title="Changing standard (Python) test discovery"
>next</a> |</li>
<li class="right" >
<a href="parametrize.html" title="Parametrizing tests"
>previous</a> |</li>
<li><a href="../contents.html">pytest-2.2.4</a> »</li>
<li><a href="index.html" >Usages and Examples</a> »</li>
<g:plusone></g:plusone>
</ul>
</div>
<div class="footer">
© Copyright 2011, holger krekel et alii.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-7597274-13']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
</body>
</html>
distrib
>
Mandriva
>
2010.2
>
i586
>
media
>
contrib-backports
>
by-pkgid
>
85556a06d0b40546e6bb4676359ced2e
>
files
>
185
