<!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>Installation and Getting Started</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.3.4.1',
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="Getting started basics" href="overview.html" />
<link rel="next" title="Usage and Invocations" href="usage.html" />
<link rel="prev" title="pytest: helps you write better programs" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="usage.html" title="Usage and Invocations"
accesskey="N">next</a></li>
<li class="right" >
<a href="index.html" title="pytest: helps you write better programs"
accesskey="P">previous</a> |</li>
<li><a href="contents.html">pytest-2.3.4.1</a> »</li>
<li><a href="overview.html" accesskey="U">Getting started basics</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="#">install</a>
</td><td>
<a href="changelog.html">changelog</a>
</td></tr><tr><td>
<a href="example/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="#">Installation and Getting Started</a><ul>
<li><a class="reference internal" href="#installation">Installation</a></li>
<li><a class="reference internal" href="#our-first-test-run">Our first test run</a></li>
<li><a class="reference internal" href="#asserting-that-a-certain-exception-is-raised">Asserting that a certain exception is raised</a></li>
<li><a class="reference internal" href="#grouping-multiple-tests-in-a-class">Grouping multiple tests in a class</a></li>
<li><a class="reference internal" href="#going-functional-requesting-a-unique-temporary-directory">Going functional: requesting a unique temporary directory</a></li>
<li><a class="reference internal" href="#where-to-go-next">Where to go next</a></li>
<li><a class="reference internal" href="#known-installation-issues">Known Installation issues</a><ul>
<li><a class="reference internal" href="#easy-install-or-pip-not-found">easy_install or pip not found?</a></li>
<li><a class="reference internal" href="#py-test-not-found-on-windows-despite-installation">py.test not found on Windows despite installation?</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">pytest: helps you write better programs</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="usage.html"
title="next chapter">Usage and Invocations</a></p>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="installation-and-getting-started">
<h1>Installation and Getting Started<a class="headerlink" href="#installation-and-getting-started" title="Permalink to this headline">¶</a></h1>
<p><strong>Pythons</strong>: Python 2.4-3.3, Jython, PyPy</p>
<p><strong>Platforms</strong>: Unix/Posix and Windows</p>
<p><strong>PyPI package name</strong>: <a class="reference external" href="http://pypi.python.org/pypi/pytest">pytest</a></p>
<p><strong>documentation as PDF</strong>: <a class="reference external" href="http://pytest.org/latest/pytest.pdf">download latest</a></p>
<div class="section" id="installation">
<span id="getstarted"></span><span id="id1"></span><h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>Installation options:</p>
<div class="highlight-python"><pre>pip install -U pytest # or
easy_install -U pytest</pre>
</div>
<p>To check your installation has installed the correct version:</p>
<div class="highlight-python"><pre>$ py.test --version
This is py.test version 2.3.5, imported from /home/hpk/p/pytest/.tox/regen/local/lib/python2.7/site-packages/pytest.py</pre>
</div>
<p>If you get an error checkout <a class="reference internal" href="#installation-issues"><em>Known Installation issues</em></a>.</p>
</div>
<div class="section" id="our-first-test-run">
<span id="simpletest"></span><h2>Our first test run<a class="headerlink" href="#our-first-test-run" title="Permalink to this headline">¶</a></h2>
<p>Let’s create a first test file with a simple test function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_sample.py</span>
<span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
<span class="k">return</span> <span class="n">x</span> <span class="o">+</span> <span class="mi">1</span>
<span class="k">def</span> <span class="nf">test_answer</span><span class="p">():</span>
<span class="k">assert</span> <span class="n">func</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span> <span class="o">==</span> <span class="mi">5</span>
</pre></div>
</div>
<p>That’s it. You can execute the test function now:</p>
<div class="highlight-python"><pre>$ py.test
=========================== test session starts ============================
platform linux2 -- Python 2.7.3 -- pytest-2.3.5
collected 1 items
test_sample.py F
================================= FAILURES =================================
_______________________________ test_answer ________________________________
def test_answer():
> assert func(3) == 5
E assert 4 == 5
E + where 4 = func(3)
test_sample.py:5: AssertionError
========================= 1 failed in 0.01 seconds =========================</pre>
</div>
<p>py.test found the <tt class="docutils literal"><span class="pre">test_answer</span></tt> function by following <a class="reference internal" href="goodpractises.html#test-discovery"><em>standard test discovery rules</em></a>, basically detecting the <tt class="docutils literal"><span class="pre">test_</span></tt> prefixes. We got a failure report because our little <tt class="docutils literal"><span class="pre">func(3)</span></tt> call did not return <tt class="docutils literal"><span class="pre">5</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can simply use the <tt class="docutils literal"><span class="pre">assert</span></tt> statement for asserting test
expectations. pytest’s <a class="reference internal" href="assert.html#assert-introspection"><em>Advanced assertion introspection</em></a> will intelligently
report intermediate values of the assert expression freeing
you from the need to learn the many names of <a class="reference external" href="http://docs.python.org/library/unittest.html#test-cases">JUnit legacy methods</a>.</p>
</div>
</div>
<div class="section" id="asserting-that-a-certain-exception-is-raised">
<h2>Asserting that a certain exception is raised<a class="headerlink" href="#asserting-that-a-certain-exception-is-raised" title="Permalink to this headline">¶</a></h2>
<p>If you want to assert that some code raises an exception you can
use the <tt class="docutils literal"><span class="pre">raises</span></tt> helper:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_sysexit.py</span>
<span class="kn">import</span> <span class="nn">pytest</span>
<span class="k">def</span> <span class="nf">f</span><span class="p">():</span>
<span class="k">raise</span> <span class="ne">SystemExit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_mytest</span><span class="p">():</span>
<span class="k">with</span> <span class="n">pytest</span><span class="o">.</span><span class="n">raises</span><span class="p">(</span><span class="ne">SystemExit</span><span class="p">):</span>
<span class="n">f</span><span class="p">()</span>
</pre></div>
</div>
<p>Running it with, this time in “quiet” reporting mode:</p>
<div class="highlight-python"><pre>$ py.test -q test_sysexit.py
.</pre>
</div>
<div class="admonition-todo admonition" id="index-0">
<p class="first admonition-title">Todo</p>
<p class="last">For further ways to assert exceptions see the <cite>raises</cite></p>
</div>
</div>
<div class="section" id="grouping-multiple-tests-in-a-class">
<h2>Grouping multiple tests in a class<a class="headerlink" href="#grouping-multiple-tests-in-a-class" title="Permalink to this headline">¶</a></h2>
<p>Once you start to have more than a few tests it often makes sense
to group tests logically, in classes and modules. Let’s write a class
containing two tests:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_class.py</span>
<span class="k">class</span> <span class="nc">TestClass</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">test_one</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">x</span> <span class="o">=</span> <span class="s">"this"</span>
<span class="k">assert</span> <span class="s">'h'</span> <span class="ow">in</span> <span class="n">x</span>
<span class="k">def</span> <span class="nf">test_two</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">x</span> <span class="o">=</span> <span class="s">"hello"</span>
<span class="k">assert</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="s">'check'</span><span class="p">)</span>
</pre></div>
</div>
<p>The two tests are found because of the standard <a class="reference internal" href="goodpractises.html#test-discovery"><em>Conventions for Python test discovery</em></a>.
There is no need to subclass anything. We can simply
run the module by passing its filename:</p>
<div class="highlight-python"><pre>$ py.test -q test_class.py
.F
================================= FAILURES =================================
____________________________ TestClass.test_two ____________________________
self = <test_class.TestClass instance at 0x315b488>
def test_two(self):
x = "hello"
> assert hasattr(x, 'check')
E assert hasattr('hello', 'check')
test_class.py:8: AssertionError</pre>
</div>
<p>The first test passed, the second failed. Again we can easily see
the intermediate values used in the assertion, helping us to
understand the reason for the failure.</p>
</div>
<div class="section" id="going-functional-requesting-a-unique-temporary-directory">
<h2>Going functional: requesting a unique temporary directory<a class="headerlink" href="#going-functional-requesting-a-unique-temporary-directory" title="Permalink to this headline">¶</a></h2>
<p>For functional tests one often needs to create some files
and pass them to application objects. pytest provides
<a class="reference internal" href="builtin.html#builtinfixtures"><em>Builtin fixtures/function arguments</em></a> which allow to request arbitrary
resources, for example a unique temporary directory:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># content of test_tmpdir.py</span>
<span class="k">def</span> <span class="nf">test_needsfiles</span><span class="p">(</span><span class="n">tmpdir</span><span class="p">):</span>
<span class="k">print</span> <span class="n">tmpdir</span>
<span class="k">assert</span> <span class="mi">0</span>
</pre></div>
</div>
<p>We list the name <tt class="docutils literal"><span class="pre">tmpdir</span></tt> in the test function signature and
py.test will lookup and call a fixture factory to create the resource
before performing the test function call. Let’s just run it:</p>
<div class="highlight-python"><pre>$ py.test -q test_tmpdir.py
F
================================= FAILURES =================================
_____________________________ test_needsfiles ______________________________
tmpdir = local('/tmp/pytest-322/test_needsfiles0')
def test_needsfiles(tmpdir):
print tmpdir
> assert 0
E assert 0
test_tmpdir.py:3: AssertionError
----------------------------- Captured stdout ------------------------------
/tmp/pytest-322/test_needsfiles0</pre>
</div>
<p>Before the test runs, a unique-per-test-invocation temporary directory
was created. More info at <a class="reference internal" href="tmpdir.html#tmpdir-handling"><em>Temporary directories and files</em></a>.</p>
<p>You can find out what kind of builtin <a class="reference internal" href="fixture.html#fixtures"><em>pytest fixtures: explicit, modular, scalable</em></a> exist by typing:</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">fixtures</span> <span class="c"># shows builtin and custom fixtures</span>
</pre></div>
</div>
</div>
<div class="section" id="where-to-go-next">
<h2>Where to go next<a class="headerlink" href="#where-to-go-next" title="Permalink to this headline">¶</a></h2>
<p>Here are a few suggestions where to go next:</p>
<ul class="simple">
<li><a class="reference internal" href="usage.html#cmdline"><em>Calling pytest through python -m pytest</em></a> for command line invocation examples</li>
<li><a class="reference internal" href="goodpractises.html#goodpractises"><em>good practises</em></a> for virtualenv, test layout, genscript support</li>
<li><a class="reference internal" href="fixture.html#fixtures"><em>pytest fixtures: explicit, modular, scalable</em></a> for providing a functional baseline to your tests</li>
<li><a class="reference internal" href="apiref.html#apiref"><em>py.test reference documentation</em></a> for documentation and examples on using py.test</li>
<li><a class="reference internal" href="plugins.html#plugins"><em>Working with plugins and conftest files</em></a> managing and writing plugins</li>
</ul>
</div>
<div class="section" id="known-installation-issues">
<span id="installation-issues"></span><h2>Known Installation issues<a class="headerlink" href="#known-installation-issues" title="Permalink to this headline">¶</a></h2>
<div class="section" id="easy-install-or-pip-not-found">
<h3>easy_install or pip not found?<a class="headerlink" href="#easy-install-or-pip-not-found" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://www.pip-installer.org/en/latest/index.html">Install pip</a> for a state of the art python package installer.</p>
<p>Or consult <a class="reference external" href="http://pypi.python.org/pypi/distribute">distribute docs</a> to install the <tt class="docutils literal"><span class="pre">easy_install</span></tt>
tool on your machine.</p>
<p>You may also use the older <a class="reference external" href="http://pypi.python.org/pypi/setuptools">setuptools</a> project but it lacks bug fixes
and does not work on Python3.</p>
</div>
<div class="section" id="py-test-not-found-on-windows-despite-installation">
<h3>py.test not found on Windows despite installation?<a class="headerlink" href="#py-test-not-found-on-windows-despite-installation" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><strong>Windows</strong>: If “easy_install” or “py.test” are not found
you need to add the Python script path to your <tt class="docutils literal"><span class="pre">PATH</span></tt>, see here:
<a class="reference external" href="http://www.imladris.com/Scripts/PythonForWindows.html">Python for Windows</a>. You may alternatively use an <a class="reference external" href="http://www.activestate.com/activepython/downloads">ActivePython install</a>
which does this for you automatically.</li>
</ul>
<ul class="simple">
<li><strong>Jython2.5.1 on Windows XP</strong>: <a class="reference external" href="http://bugs.jython.org/issue1491">Jython does not create command line launchers</a>
so <tt class="docutils literal"><span class="pre">py.test</span></tt> will not work correctly. You may install py.test on
CPython and type <tt class="docutils literal"><span class="pre">py.test</span> <span class="pre">--genscript=mytest</span></tt> and then use
<tt class="docutils literal"><span class="pre">jython</span> <span class="pre">mytest</span></tt> to run py.test for your tests to run with Jython.</li>
</ul>
<blockquote>
<div><a class="reference internal" href="example/index.html#examples"><em>Usages and Examples</em></a> for more complex examples</div></blockquote>
</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="usage.html" title="Usage and Invocations"
>next</a></li>
<li class="right" >
<a href="index.html" title="pytest: helps you write better programs"
>previous</a> |</li>
<li><a href="contents.html">pytest-2.3.4.1</a> »</li>
<li><a href="overview.html" >Getting started basics</a> »</li>
<g:plusone></g:plusone>
</ul>
</div>
<div class="footer">
© Copyright 2012, holger krekel.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</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>
