<!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>