| Current File : //usr/share/doc/pytest-2.7.0/html/en/customize.html |
<!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>Basic test configuration</title>
<link rel="stylesheet" href="_static/flasky.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.7.0',
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="shortcut icon" href="_static/pytest1favi.ico"/>
<link rel="top" title="None" href="index.html" />
<link rel="up" title="pytest reference documentation" href="apiref.html" />
<link rel="next" title="The writing and reporting of assertions in tests" href="assert.html" />
<link rel="prev" title="Pytest API and builtin fixtures" href="builtin.html" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="assert.html" title="The writing and reporting of assertions in tests"
accesskey="N">next</a></li>
<li class="right" >
<a href="builtin.html" title="Pytest API and builtin fixtures"
accesskey="P">previous</a> |</li>
<li><a href="contents.html">pytest-2.7.0</a> »</li>
<li><a href="apiref.html" accesskey="U">pytest reference documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="basic-test-configuration">
<h1>Basic test configuration<a class="headerlink" href="#basic-test-configuration" title="Permalink to this headline">¶</a></h1>
<div class="section" id="command-line-options-and-configuration-file-settings">
<h2>Command line options and configuration file settings<a class="headerlink" href="#command-line-options-and-configuration-file-settings" title="Permalink to this headline">¶</a></h2>
<p>You can get help on command line options and values in INI-style
configurations files by using the general help option:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">py</span><span class="o">.</span><span class="n">test</span> <span class="o">-</span><span class="n">h</span> <span class="c"># prints options _and_ config file settings</span>
</pre></div>
</div>
<p>This will display command line and configuration file settings
which were registered by installed plugins.</p>
</div>
<div class="section" id="initialization-determining-rootdir-and-inifile">
<span id="inifiles"></span><span id="rootdir"></span><h2>initialization: determining rootdir and inifile<a class="headerlink" href="#initialization-determining-rootdir-and-inifile" title="Permalink to this headline">¶</a></h2>
<p class="versionadded">
<span class="versionmodified">New in version 2.7.</span></p>
<p>pytest determines a “rootdir” for each test run which depends on
the command line arguments (specified test files, paths) and on
the existence of inifiles. The determined rootdir and ini-file are
printed as part of the pytest header. The rootdir is used for constructing
“nodeids” during collection and may also be used by plugins to store
project/testrun-specific information.</p>
<p>Here is the algorithm which finds the rootdir from <tt class="docutils literal"><span class="pre">args</span></tt>:</p>
<ul class="simple">
<li>determine the common ancestor directory for the specified <tt class="docutils literal"><span class="pre">args</span></tt>.</li>
<li>look for <tt class="docutils literal"><span class="pre">pytest.ini</span></tt>, <tt class="docutils literal"><span class="pre">tox.ini</span></tt> and <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> files in the
ancestor directory and upwards. If one is matched, it becomes the
ini-file and its directory becomes the rootdir. An existing
<tt class="docutils literal"><span class="pre">pytest.ini</span></tt> file will always be considered a match whereas
<tt class="docutils literal"><span class="pre">tox.ini</span></tt> and <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> will only match if they contain
a <tt class="docutils literal"><span class="pre">[pytest]</span></tt> section.</li>
<li>if no ini-file was found, look for <tt class="docutils literal"><span class="pre">setup.py</span></tt> upwards from
the common ancestor directory to determine the <tt class="docutils literal"><span class="pre">rootdir</span></tt>.</li>
<li>if no ini-file and no <tt class="docutils literal"><span class="pre">setup.py</span></tt> was found, use the already
determined common ancestor as root directory. This allows to
work with pytest in structures that are not part of a package
and don’t have any particular ini-file configuration.</li>
</ul>
<p>Note that options from multiple ini-files candidates are never merged,
the first one wins (<tt class="docutils literal"><span class="pre">pytest.ini</span></tt> always wins even if it does not
contain a <tt class="docutils literal"><span class="pre">[pytest]</span></tt> section).</p>
<p>The <tt class="docutils literal"><span class="pre">config</span></tt> object will subsequently carry these attributes:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">config.rootdir</span></tt>: the determined root directory, guaranteed to exist.</li>
<li><tt class="docutils literal"><span class="pre">config.inifile</span></tt>: the determined ini-file, may be <tt class="docutils literal"><span class="pre">None</span></tt>.</li>
</ul>
<p>The rootdir is used a reference directory for constructing test
addresses (“nodeids”) and can be used also by plugins for storing
per-testrun information.</p>
<p>Example:</p>
<div class="highlight-python"><pre>py.test path/to/testdir path/other/</pre>
</div>
<p>will determine the common ancestor as <tt class="docutils literal"><span class="pre">path</span></tt> and then
check for ini-files as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># first look for pytest.ini files</span>
<span class="n">path</span><span class="o">/</span><span class="n">pytest</span><span class="o">.</span><span class="n">ini</span>
<span class="n">path</span><span class="o">/</span><span class="n">setup</span><span class="o">.</span><span class="n">cfg</span> <span class="c"># must also contain [pytest] section to match</span>
<span class="n">path</span><span class="o">/</span><span class="n">tox</span><span class="o">.</span><span class="n">ini</span> <span class="c"># must also contain [pytest] section to match</span>
<span class="n">pytest</span><span class="o">.</span><span class="n">ini</span>
<span class="o">...</span> <span class="c"># all the way down to the root</span>
<span class="c"># now look for setup.py</span>
<span class="n">path</span><span class="o">/</span><span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="n">setup</span><span class="o">.</span><span class="n">py</span>
<span class="o">...</span> <span class="c"># all the way down to the root</span>
</pre></div>
</div>
</div>
<div class="section" id="adding-default-options">
<span id="how-to-change-command-line-options-defaults"></span><span id="id1"></span><h2>How to change command line options defaults<a class="headerlink" href="#adding-default-options" title="Permalink to this headline">¶</a></h2>
<p>It can be tedious to type the same series of command line options
every time you use <tt class="docutils literal"><span class="pre">pytest</span></tt>. For example, if you always want to see
detailed info on skipped and xfailed tests, as well as have terser “dot”
progress output, you can write it into a configuration file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of pytest.ini</span>
<span class="c"># (or tox.ini or setup.cfg)</span>
<span class="p">[</span><span class="n">pytest</span><span class="p">]</span>
<span class="n">addopts</span> <span class="o">=</span> <span class="o">-</span><span class="n">rsxX</span> <span class="o">-</span><span class="n">q</span>
</pre></div>
</div>
<p>Alternatively, you can set a PYTEST_ADDOPTS environment variable to add command
line options while the environment is in use:</p>
<div class="highlight-python"><pre>export PYTEST_ADDOPTS="-rsxX -q"</pre>
</div>
<p>From now on, running <tt class="docutils literal"><span class="pre">pytest</span></tt> will add the specified options.</p>
</div>
<div class="section" id="builtin-configuration-file-options">
<h2>Builtin configuration file options<a class="headerlink" href="#builtin-configuration-file-options" title="Permalink to this headline">¶</a></h2>
<dl class="confval">
<dt id="confval-minversion">
<tt class="descname">minversion</tt><a class="headerlink" href="#confval-minversion" title="Permalink to this definition">¶</a></dt>
<dd><p>Specifies a minimal pytest version required for running tests.</p>
<blockquote>
<div>minversion = 2.1 # will fail if we run with pytest-2.0</div></blockquote>
</dd></dl>
<dl class="confval">
<dt id="confval-addopts">
<tt class="descname">addopts</tt><a class="headerlink" href="#confval-addopts" title="Permalink to this definition">¶</a></dt>
<dd><p>Add the specified <tt class="docutils literal"><span class="pre">OPTS</span></tt> to the set of command line arguments as if they
had been specified by the user. Example: if you have this ini file content:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">pytest</span><span class="p">]</span>
<span class="n">addopts</span> <span class="o">=</span> <span class="o">--</span><span class="n">maxfail</span><span class="o">=</span><span class="mi">2</span> <span class="o">-</span><span class="n">rf</span> <span class="c"># exit after 2 failures, report fail info</span>
</pre></div>
</div>
<p>issuing <tt class="docutils literal"><span class="pre">py.test</span> <span class="pre">test_hello.py</span></tt> actually means:</p>
<div class="highlight-python"><pre>py.test --maxfail=2 -rf test_hello.py</pre>
</div>
<p>Default is to add no options.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-norecursedirs">
<tt class="descname">norecursedirs</tt><a class="headerlink" href="#confval-norecursedirs" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the directory basename patterns to avoid when recursing
for test discovery. The individual (fnmatch-style) patterns are
applied to the basename of a directory to decide if to recurse into it.
Pattern matching characters:</p>
<div class="highlight-python"><pre>* matches everything
? matches any single character
[seq] matches any character in seq
[!seq] matches any char not in seq</pre>
</div>
<p>Default patterns are <tt class="docutils literal"><span class="pre">'.*',</span> <span class="pre">'CVS',</span> <span class="pre">'_darcs',</span> <span class="pre">'{arch}',</span> <span class="pre">'*.egg'</span></tt>.
Setting a <tt class="docutils literal"><span class="pre">norecursedirs</span></tt> replaces the default. Here is an example of
how to avoid certain directories:</p>
<div class="highlight-python"><pre># content of setup.cfg
[pytest]
norecursedirs = .svn _build tmp*</pre>
</div>
<p>This would tell <tt class="docutils literal"><span class="pre">pytest</span></tt> to not look into typical subversion or
sphinx-build directories or into any <tt class="docutils literal"><span class="pre">tmp</span></tt> prefixed directory.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-python_files">
<tt class="descname">python_files</tt><a class="headerlink" href="#confval-python_files" title="Permalink to this definition">¶</a></dt>
<dd><p>One or more Glob-style file patterns determining which python files
are considered as test modules.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-python_classes">
<tt class="descname">python_classes</tt><a class="headerlink" href="#confval-python_classes" title="Permalink to this definition">¶</a></dt>
<dd><p>One or more name prefixes or glob-style patterns determining which classes
are considered for test collection. Here is an example of how to collect
tests from classes that end in <tt class="docutils literal"><span class="pre">Suite</span></tt>:</p>
<div class="highlight-python"><pre># content of pytest.ini
[pytest]
python_classes = *Suite</pre>
</div>
<p>Note that <tt class="docutils literal"><span class="pre">unittest.TestCase</span></tt> derived classes are always collected
regardless of this option, as <tt class="docutils literal"><span class="pre">unittest</span></tt>‘s own collection framework is used
to collect those tests.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-python_functions">
<tt class="descname">python_functions</tt><a class="headerlink" href="#confval-python_functions" title="Permalink to this definition">¶</a></dt>
<dd><p>One or more name prefixes or glob-patterns determining which test functions
and methods are considered tests. Here is an example of how
to collect test functions and methods that end in <tt class="docutils literal"><span class="pre">_test</span></tt>:</p>
<div class="highlight-python"><pre># content of pytest.ini
[pytest]
python_functions = *_test</pre>
</div>
<p>Note that this has no effect on methods that live on a <tt class="docutils literal"><span class="pre">unittest</span>
<span class="pre">.TestCase</span></tt> derived class, as <tt class="docutils literal"><span class="pre">unittest</span></tt>‘s own collection framework is used
to collect those tests.</p>
<p>See <a class="reference internal" href="example/pythoncollection.html#change-naming-conventions"><em>Changing naming conventions</em></a> for more detailed examples.</p>
</dd></dl>
<dl class="confval">
<dt id="confval-doctest_optionflags">
<tt class="descname">doctest_optionflags</tt><a class="headerlink" href="#confval-doctest_optionflags" title="Permalink to this definition">¶</a></dt>
<dd><p>One or more doctest flag names from the standard <tt class="docutils literal"><span class="pre">doctest</span></tt> module.
<a class="reference internal" href="doctest.html"><em>See how py.test handles doctests</em></a>.</p>
</dd></dl>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="contents.html">
<img class="logo" src="_static/pytest1.png" alt="Logo"/>
</a></p><h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="contents.html">Contents</a></li>
<li><a href="getting-started.html">Install</a></li>
<li><a href="example/index.html">Examples</a></li>
<li><a href="#">Customize</a></li>
<li><a href="contact.html">Contact</a></li>
<li><a href="talks.html">Talks/Posts</a></li>
<li><a href="changelog.html">Changelog</a></li>
</ul>
<hr>
<ul>
<li><a class="reference internal" href="#">Basic test configuration</a><ul>
<li><a class="reference internal" href="#command-line-options-and-configuration-file-settings">Command line options and configuration file settings</a></li>
<li><a class="reference internal" href="#initialization-determining-rootdir-and-inifile">initialization: determining rootdir and inifile</a></li>
<li><a class="reference internal" href="#adding-default-options">How to change command line options defaults</a></li>
<li><a class="reference internal" href="#builtin-configuration-file-options">Builtin configuration file options</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="contents.html">Documentation overview</a><ul>
<li><a href="apiref.html">pytest reference documentation</a><ul>
<li>Previous: <a href="builtin.html" title="previous chapter">Pytest API and builtin fixtures</a></li>
<li>Next: <a href="assert.html" title="next chapter">The writing and reporting of assertions in tests</a></li>
</ul></li>
</ul></li>
</ul><h3>Useful Links</h3>
<ul>
<li><a href="index.html">The pytest Website</a></li>
<li><a href="contributing.html">Contribution Guide</a></li>
<li><a href="https://pypi.python.org/pypi/pytest">pytest @ PyPI</a></li>
<li><a href="https://bitbucket.org/pytest-dev/pytest/">pytest @ Bitbucket</a></li>
<li><a href="http://pytest.org/latest/plugins_index/index.html">3rd party plugins</a></li>
<li><a href="https://bitbucket.org/pytest-dev/pytest/issues?status=new&status=open">Issue Tracker</a></li>
<li><a href="http://pytest.org/latest/pytest.pdf">PDF Documentation</a>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2014, holger krekel.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</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>
</body>
</html>