Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
unittest.html3170 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="unittest — Unit testing framework" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/unittest.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/unittest/__init__.py(If you are already familiar with the basic concepts of testing, you might want to skip to the list of assert methods.) The unittest unit testing framework was ..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_unittest_7f61b5f1.png" />15<meta property="og:image:alt" content="Source code: Lib/unittest/__init__.py(If you are already familiar with the basic concepts of testing, you might want to skip to the list of assert methods.) The unittest unit testing framework was ..." />16<meta name="description" content="Source code: Lib/unittest/__init__.py(If you are already familiar with the basic concepts of testing, you might want to skip to the list of assert methods.) The unittest unit testing framework was ..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>unittest — Unit testing framework &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="unittest.mock — mock object library" href="unittest.mock.html" />43    <link rel="prev" title="doctest — Test interactive Python examples" href="doctest.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/unittest.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> — Unit testing framework</a><ul>108<li><a class="reference internal" href="#basic-example">Basic example</a></li>109<li><a class="reference internal" href="#command-line-interface">Command-Line Interface</a><ul>110<li><a class="reference internal" href="#command-line-options">Command-line options</a></li>111</ul>112</li>113<li><a class="reference internal" href="#test-discovery">Test Discovery</a></li>114<li><a class="reference internal" href="#organizing-test-code">Organizing test code</a></li>115<li><a class="reference internal" href="#re-using-old-test-code">Re-using old test code</a></li>116<li><a class="reference internal" href="#skipping-tests-and-expected-failures">Skipping tests and expected failures</a></li>117<li><a class="reference internal" href="#distinguishing-test-iterations-using-subtests">Distinguishing test iterations using subtests</a></li>118<li><a class="reference internal" href="#classes-and-functions">Classes and functions</a><ul>119<li><a class="reference internal" href="#test-cases">Test cases</a></li>120<li><a class="reference internal" href="#grouping-tests">Grouping tests</a></li>121<li><a class="reference internal" href="#loading-and-running-tests">Loading and running tests</a><ul>122<li><a class="reference internal" href="#load-tests-protocol">load_tests Protocol</a></li>123</ul>124</li>125</ul>126</li>127<li><a class="reference internal" href="#class-and-module-fixtures">Class and Module Fixtures</a><ul>128<li><a class="reference internal" href="#setupclass-and-teardownclass">setUpClass and tearDownClass</a></li>129<li><a class="reference internal" href="#setupmodule-and-teardownmodule">setUpModule and tearDownModule</a></li>130</ul>131</li>132<li><a class="reference internal" href="#signal-handling">Signal Handling</a></li>133</ul>134</li>135</ul>136 137  </div>138  <div>139    <h4>Previous topic</h4>140    <p class="topless"><a href="doctest.html"141                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> — Test interactive Python examples</a></p>142  </div>143  <div>144    <h4>Next topic</h4>145    <p class="topless"><a href="unittest.mock.html"146                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — mock object library</a></p>147  </div>148  <script>149    document.addEventListener('DOMContentLoaded', () => {150        const title = document.querySelector('meta[property="og:title"]').content;151        const elements = document.querySelectorAll('.improvepage');152        const pageurl = window.location.href.split('?')[0];153        elements.forEach(element => {154            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));155            url.searchParams.set('pagetitle', title);156            url.searchParams.set('pageurl', pageurl);157            url.searchParams.set('pagesource', "library/unittest.rst");158            element.href = url.toString();159        });160    });161  </script>162  <div role="note" aria-label="source link">163    <h3>This page</h3>164    <ul class="this-page-menu">165      <li><a href="../bugs.html">Report a bug</a></li>166      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>167      <li>168        <a href="https://github.com/python/cpython/blob/main/Doc/library/unittest.rst?plain=1"169            rel="nofollow">Show source170        </a>171      </li>172      173    </ul>174  </div>175        </nav>176    </div>177</div>178 179  180    <div class="related" role="navigation" aria-label="Related">181      <h3>Navigation</h3>182      <ul>183        <li class="right" style="margin-right: 10px">184          <a href="../genindex.html" title="General Index"185             accesskey="I">index</a></li>186        <li class="right" >187          <a href="../py-modindex.html" title="Python Module Index"188             >modules</a> |</li>189        <li class="right" >190          <a href="unittest.mock.html" title="unittest.mock — mock object library"191             accesskey="N">next</a> |</li>192        <li class="right" >193          <a href="doctest.html" title="doctest — Test interactive Python examples"194             accesskey="P">previous</a> |</li>195 196          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>197          <li><a href="https://www.python.org/">Python</a> &#187;</li>198          <li class="switchers">199            <div class="language_switcher_placeholder"></div>200            <div class="version_switcher_placeholder"></div>201          </li>202          <li>203              204          </li>205    <li id="cpython-language-and-version">206      <a href="../index.html">3.15.0a6 Documentation</a> &#187;207    </li>208 209          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>210          <li class="nav-item nav-item-2"><a href="development.html" accesskey="U">Development Tools</a> &#187;</li>211        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> — Unit testing framework</a></li>212                <li class="right">213                    214 215    <div class="inline-search" role="search">216        <form class="inline-search" action="../search.html" method="get">217          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">218          <input type="submit" value="Go">219        </form>220    </div>221                     |222                </li>223            <li class="right">224<label class="theme-selector-label">225    Theme226    <select class="theme-selector" oninput="activateTheme(this.value)">227        <option value="auto" selected>Auto</option>228        <option value="light">Light</option>229        <option value="dark">Dark</option>230    </select>231</label> |</li>232            233      </ul>234    </div>    235 236    <div class="document">237      <div class="documentwrapper">238        <div class="bodywrapper">239          <div class="body" role="main">240            241  <section id="module-unittest">242<span id="unittest-unit-testing-framework"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> — Unit testing framework<a class="headerlink" href="#module-unittest" title="Link to this heading">¶</a></h1>243<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/unittest/__init__.py">Lib/unittest/__init__.py</a></p>244<hr class="docutils" />245<p>(If you are already familiar with the basic concepts of testing, you might want246to skip to <a class="reference internal" href="#assert-methods"><span class="std std-ref">the list of assert methods</span></a>.)</p>247<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> unit testing framework was originally inspired by JUnit248and has a similar flavor as major unit testing frameworks in other249languages.  It supports test automation, sharing of setup and shutdown code250for tests, aggregation of tests into collections, and independence of the251tests from the reporting framework.</p>252<p>To achieve this, <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> supports some important concepts in an253object-oriented way:</p>254<dl class="simple">255<dt>test fixture</dt><dd><p>A <em class="dfn">test fixture</em> represents the preparation needed to perform one or more256tests, and any associated cleanup actions.  This may involve, for example,257creating temporary or proxy databases, directories, or starting a server258process.</p>259</dd>260<dt>test case</dt><dd><p>A <em class="dfn">test case</em> is the individual unit of testing.  It checks for a specific261response to a particular set of inputs.  <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> provides a base class,262<a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a>, which may be used to create new test cases.</p>263</dd>264<dt>test suite</dt><dd><p>A <em class="dfn">test suite</em> is a collection of test cases, test suites, or both.  It is265used to aggregate tests that should be executed together.</p>266</dd>267<dt>test runner</dt><dd><p>A <em class="dfn">test runner</em> is a component which orchestrates the execution of tests268and provides the outcome to the user.  The runner may use a graphical interface,269a textual interface, or return a special value to indicate the results of270executing the tests.</p>271</dd>272</dl>273<div class="admonition seealso">274<p class="admonition-title">See also</p>275<dl class="simple">276<dt>Module <a class="reference internal" href="doctest.html#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a></dt><dd><p>Another test-support module with a very different flavor.</p>277</dd>278<dt><a class="reference external" href="https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm">Simple Smalltalk Testing: With Patterns</a></dt><dd><p>Kent Beck’s original paper on testing frameworks using the pattern shared279by <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code>.</p>280</dd>281<dt><a class="reference external" href="https://docs.pytest.org/">pytest</a></dt><dd><p>Third-party unittest framework with a lighter-weight syntax for writing282tests.  For example, <code class="docutils literal notranslate"><span class="pre">assert</span> <span class="pre">func(10)</span> <span class="pre">==</span> <span class="pre">42</span></code>.</p>283</dd>284<dt><a class="reference external" href="https://wiki.python.org/moin/PythonTestingToolsTaxonomy">The Python Testing Tools Taxonomy</a></dt><dd><p>An extensive list of Python testing tools including functional testing285frameworks and mock object libraries.</p>286</dd>287<dt><a class="reference external" href="http://lists.idyll.org/listinfo/testing-in-python">Testing in Python Mailing List</a></dt><dd><p>A special-interest-group for discussion of testing, and testing tools,288in Python.</p>289</dd>290</dl>291<p>The script <code class="file docutils literal notranslate"><span class="pre">Tools/unittestgui/unittestgui.py</span></code> in the Python source distribution is292a GUI tool for test discovery and execution.  This is intended largely for ease of use293for those new to unit testing.  For production environments it is294recommended that tests be driven by a continuous integration system such as295<a class="reference external" href="https://buildbot.net/">Buildbot</a>, <a class="reference external" href="https://www.jenkins.io/">Jenkins</a>,296<a class="reference external" href="https://github.com/features/actions">GitHub Actions</a>, or297<a class="reference external" href="https://www.appveyor.com/">AppVeyor</a>.</p>298</div>299<section id="basic-example">300<span id="unittest-minimal-example"></span><h2>Basic example<a class="headerlink" href="#basic-example" title="Link to this heading">¶</a></h2>301<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> module provides a rich set of tools for constructing and302running tests.  This section demonstrates that a small subset of the tools303suffice to meet the needs of most users.</p>304<p>Here is a short script to test three string methods:</p>305<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">unittest</span>306 307<span class="k">class</span><span class="w"> </span><span class="nc">TestStringMethods</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>308 309    <span class="k">def</span><span class="w"> </span><span class="nf">test_upper</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>310        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="o">.</span><span class="n">upper</span><span class="p">(),</span> <span class="s1">&#39;FOO&#39;</span><span class="p">)</span>311 312    <span class="k">def</span><span class="w"> </span><span class="nf">test_isupper</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>313        <span class="bp">self</span><span class="o">.</span><span class="n">assertTrue</span><span class="p">(</span><span class="s1">&#39;FOO&#39;</span><span class="o">.</span><span class="n">isupper</span><span class="p">())</span>314        <span class="bp">self</span><span class="o">.</span><span class="n">assertFalse</span><span class="p">(</span><span class="s1">&#39;Foo&#39;</span><span class="o">.</span><span class="n">isupper</span><span class="p">())</span>315 316    <span class="k">def</span><span class="w"> </span><span class="nf">test_split</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>317        <span class="n">s</span> <span class="o">=</span> <span class="s1">&#39;hello world&#39;</span>318        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">s</span><span class="o">.</span><span class="n">split</span><span class="p">(),</span> <span class="p">[</span><span class="s1">&#39;hello&#39;</span><span class="p">,</span> <span class="s1">&#39;world&#39;</span><span class="p">])</span>319        <span class="c1"># check that s.split fails when the separator is not a string</span>320        <span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">assertRaises</span><span class="p">(</span><span class="ne">TypeError</span><span class="p">):</span>321            <span class="n">s</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>322 323<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>324    <span class="n">unittest</span><span class="o">.</span><span class="n">main</span><span class="p">()</span>325</pre></div>326</div>327<p>A test case is created by subclassing <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a>.  The three328individual tests are defined with methods whose names start with the letters329<code class="docutils literal notranslate"><span class="pre">test</span></code>.  This naming convention informs the test runner about which methods330represent tests.</p>331<p>The crux of each test is a call to <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertEqual()</span></code></a> to check for an332expected result; <a class="reference internal" href="#unittest.TestCase.assertTrue" title="unittest.TestCase.assertTrue"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertTrue()</span></code></a> or <a class="reference internal" href="#unittest.TestCase.assertFalse" title="unittest.TestCase.assertFalse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertFalse()</span></code></a>333to verify a condition; or <a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertRaises()</span></code></a> to verify that a334specific exception gets raised.  These methods are used instead of the335<a class="reference internal" href="../reference/simple_stmts.html#assert"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">assert</span></code></a> statement so the test runner can accumulate all test results336and produce a report.</p>337<p>The <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a> and <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tearDown()</span></code></a> methods allow you338to define instructions that will be executed before and after each test method.339They are covered in more detail in the section <a class="reference internal" href="#organizing-tests"><span class="std std-ref">Organizing test code</span></a>.</p>340<p>The final block shows a simple way to run the tests. <a class="reference internal" href="#unittest.main" title="unittest.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">unittest.main()</span></code></a>341provides a command-line interface to the test script.  When run from the command342line, the above script produces an output that looks like this:</p>343<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">...</span>344<span class="o">----------------------------------------------------------------------</span>345<span class="n">Ran</span> <span class="mi">3</span> <span class="n">tests</span> <span class="ow">in</span> <span class="mf">0.000</span><span class="n">s</span>346 347<span class="n">OK</span>348</pre></div>349</div>350<p>Passing the <code class="docutils literal notranslate"><span class="pre">-v</span></code> option to your test script will instruct <a class="reference internal" href="#unittest.main" title="unittest.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">unittest.main()</span></code></a>351to enable a higher level of verbosity, and produce the following output:</p>352<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">test_isupper</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">TestStringMethods</span><span class="o">.</span><span class="n">test_isupper</span><span class="p">)</span> <span class="o">...</span> <span class="n">ok</span>353<span class="n">test_split</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">TestStringMethods</span><span class="o">.</span><span class="n">test_split</span><span class="p">)</span> <span class="o">...</span> <span class="n">ok</span>354<span class="n">test_upper</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">TestStringMethods</span><span class="o">.</span><span class="n">test_upper</span><span class="p">)</span> <span class="o">...</span> <span class="n">ok</span>355 356<span class="o">----------------------------------------------------------------------</span>357<span class="n">Ran</span> <span class="mi">3</span> <span class="n">tests</span> <span class="ow">in</span> <span class="mf">0.001</span><span class="n">s</span>358 359<span class="n">OK</span>360</pre></div>361</div>362<p>The above examples show the most commonly used <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> features which363are sufficient to meet many everyday testing needs.  The remainder of the364documentation explores the full feature set from first principles.</p>365<div class="versionchanged">366<p><span class="versionmodified changed">Changed in version 3.11: </span>The behavior of returning a value from a test method (other than the default367<code class="docutils literal notranslate"><span class="pre">None</span></code> value), is now deprecated.</p>368</div>369</section>370<section id="command-line-interface">371<span id="unittest-command-line-interface"></span><h2>Command-Line Interface<a class="headerlink" href="#command-line-interface" title="Link to this heading">¶</a></h2>372<p>The unittest module can be used from the command line to run tests from373modules, classes or even individual test methods:</p>374<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">test_module1</span> <span class="n">test_module2</span>375<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">test_module</span><span class="o">.</span><span class="n">TestClass</span>376<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">test_module</span><span class="o">.</span><span class="n">TestClass</span><span class="o">.</span><span class="n">test_method</span>377</pre></div>378</div>379<p>You can pass in a list with any combination of module names, and fully380qualified class or method names.</p>381<p>Test modules can be specified by file path as well:</p>382<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">tests</span><span class="o">/</span><span class="n">test_something</span><span class="o">.</span><span class="n">py</span>383</pre></div>384</div>385<p>This allows you to use the shell filename completion to specify the test module.386The file specified must still be importable as a module. The path is converted387to a module name by removing the ‘.py’ and converting path separators into ‘.’.388If you want to execute a test file that isn’t importable as a module you should389execute the file directly instead.</p>390<p>You can run tests with more detail (higher verbosity) by passing in the -v flag:</p>391<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="o">-</span><span class="n">v</span> <span class="n">test_module</span>392</pre></div>393</div>394<p>When executed without arguments <a class="reference internal" href="#unittest-test-discovery"><span class="std std-ref">Test Discovery</span></a> is started:</p>395<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span>396</pre></div>397</div>398<p>For a list of all the command-line options:</p>399<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="o">-</span><span class="n">h</span>400</pre></div>401</div>402<div class="versionchanged">403<p><span class="versionmodified changed">Changed in version 3.2: </span>In earlier versions it was only possible to run individual test methods and404not modules or classes.</p>405</div>406<div class="versionadded">407<p><span class="versionmodified added">Added in version 3.14: </span>Output is colorized by default and can be408<a class="reference internal" href="../using/cmdline.html#using-on-controlling-color"><span class="std std-ref">controlled using environment variables</span></a>.</p>409</div>410<section id="command-line-options">411<h3>Command-line options<a class="headerlink" href="#command-line-options" title="Link to this heading">¶</a></h3>412<p><strong class="program">unittest</strong> supports these command-line options:</p>413<dl class="std option">414<dt class="sig sig-object std" id="cmdoption-unittest-b">415<span id="cmdoption-unittest-buffer"></span><span class="sig-name descname"><span class="pre">-b</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--buffer</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-unittest-b" title="Link to this definition">¶</a></dt>416<dd><p>The standard output and standard error streams are buffered during the test417run. Output during a passing test is discarded. Output is echoed normally418on test fail or error and is added to the failure messages.</p>419</dd></dl>420 421<dl class="std option">422<dt class="sig sig-object std" id="cmdoption-unittest-c">423<span id="cmdoption-unittest-catch"></span><span class="sig-name descname"><span class="pre">-c</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--catch</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-unittest-c" title="Link to this definition">¶</a></dt>424<dd><p><kbd class="kbd docutils literal notranslate">Control</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd> during the test run waits for the current test to end and then425reports all the results so far. A second <kbd class="kbd docutils literal notranslate">Control</kbd>-<kbd class="kbd docutils literal notranslate">C</kbd> raises the normal426<a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyboardInterrupt</span></code></a> exception.</p>427<p>See <a class="reference internal" href="#signal-handling">Signal Handling</a> for the functions that provide this functionality.</p>428</dd></dl>429 430<dl class="std option">431<dt class="sig sig-object std" id="cmdoption-unittest-f">432<span id="cmdoption-unittest-failfast"></span><span class="sig-name descname"><span class="pre">-f</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--failfast</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-unittest-f" title="Link to this definition">¶</a></dt>433<dd><p>Stop the test run on the first error or failure.</p>434</dd></dl>435 436<dl class="std option">437<dt class="sig sig-object std" id="cmdoption-unittest-k">438<span class="sig-name descname"><span class="pre">-k</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-unittest-k" title="Link to this definition">¶</a></dt>439<dd><p>Only run test methods and classes that match the pattern or substring.440This option may be used multiple times, in which case all test cases that441match any of the given patterns are included.</p>442<p>Patterns that contain a wildcard character (<code class="docutils literal notranslate"><span class="pre">*</span></code>) are matched against the443test name using <a class="reference internal" href="fnmatch.html#fnmatch.fnmatchcase" title="fnmatch.fnmatchcase"><code class="xref py py-meth docutils literal notranslate"><span class="pre">fnmatch.fnmatchcase()</span></code></a>; otherwise simple case-sensitive444substring matching is used.</p>445<p>Patterns are matched against the fully qualified test method name as446imported by the test loader.</p>447<p>For example, <code class="docutils literal notranslate"><span class="pre">-k</span> <span class="pre">foo</span></code> matches <code class="docutils literal notranslate"><span class="pre">foo_tests.SomeTest.test_something</span></code>,448<code class="docutils literal notranslate"><span class="pre">bar_tests.SomeTest.test_foo</span></code>, but not <code class="docutils literal notranslate"><span class="pre">bar_tests.FooTest.test_something</span></code>.</p>449</dd></dl>450 451<dl class="std option">452<dt class="sig sig-object std" id="cmdoption-unittest-locals">453<span class="sig-name descname"><span class="pre">--locals</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-unittest-locals" title="Link to this definition">¶</a></dt>454<dd><p>Show local variables in tracebacks.</p>455</dd></dl>456 457<dl class="std option">458<dt class="sig sig-object std" id="cmdoption-unittest-durations">459<span class="sig-name descname"><span class="pre">--durations</span></span><span class="sig-prename descclassname"> <span class="pre">N</span></span><a class="headerlink" href="#cmdoption-unittest-durations" title="Link to this definition">¶</a></dt>460<dd><p>Show the N slowest test cases (N=0 for all).</p>461</dd></dl>462 463<div class="versionadded">464<p><span class="versionmodified added">Added in version 3.2: </span>The command-line options <code class="docutils literal notranslate"><span class="pre">-b</span></code>, <code class="docutils literal notranslate"><span class="pre">-c</span></code> and <code class="docutils literal notranslate"><span class="pre">-f</span></code> were added.</p>465</div>466<div class="versionadded">467<p><span class="versionmodified added">Added in version 3.5: </span>The command-line option <code class="docutils literal notranslate"><span class="pre">--locals</span></code>.</p>468</div>469<div class="versionadded">470<p><span class="versionmodified added">Added in version 3.7: </span>The command-line option <code class="docutils literal notranslate"><span class="pre">-k</span></code>.</p>471</div>472<div class="versionadded">473<p><span class="versionmodified added">Added in version 3.12: </span>The command-line option <code class="docutils literal notranslate"><span class="pre">--durations</span></code>.</p>474</div>475<p>The command line can also be used for test discovery, for running all of the476tests in a project or just a subset.</p>477</section>478</section>479<section id="test-discovery">480<span id="unittest-test-discovery"></span><h2>Test Discovery<a class="headerlink" href="#test-discovery" title="Link to this heading">¶</a></h2>481<div class="versionadded">482<p><span class="versionmodified added">Added in version 3.2.</span></p>483</div>484<p>Unittest supports simple test discovery. In order to be compatible with test485discovery, all of the test files must be <a class="reference internal" href="../tutorial/modules.html#tut-modules"><span class="std std-ref">modules</span></a> or486<a class="reference internal" href="../tutorial/modules.html#tut-packages"><span class="std std-ref">packages</span></a> importable from the top-level directory of487the project (this means that their filenames must be valid <a class="reference internal" href="../reference/lexical_analysis.html#identifiers"><span class="std std-ref">identifiers</span></a>).</p>488<p>Test discovery is implemented in <a class="reference internal" href="#unittest.TestLoader.discover" title="unittest.TestLoader.discover"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TestLoader.discover()</span></code></a>, but can also be489used from the command line. The basic command-line usage is:</p>490<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">project_directory</span>491<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">discover</span>492</pre></div>493</div>494<div class="admonition note">495<p class="admonition-title">Note</p>496<p>As a shortcut, <code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">unittest</span></code> is the equivalent of497<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">unittest</span> <span class="pre">discover</span></code>. If you want to pass arguments to test498discovery the <code class="docutils literal notranslate"><span class="pre">discover</span></code> sub-command must be used explicitly.</p>499</div>500<p>The <code class="docutils literal notranslate"><span class="pre">discover</span></code> sub-command has the following options:</p>501<dl class="std option">502<dt class="sig sig-object std" id="cmdoption-unittest-discover-v">503<span id="cmdoption-unittest-discover-verbose"></span><span class="sig-name descname"><span class="pre">-v</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--verbose</span></span><span class="sig-prename descclassname"></span><a class="headerlink" href="#cmdoption-unittest-discover-v" title="Link to this definition">¶</a></dt>504<dd><p>Verbose output</p>505</dd></dl>506 507<dl class="std option">508<dt class="sig sig-object std" id="cmdoption-unittest-discover-s">509<span id="cmdoption-unittest-discover-start-directory"></span><span class="sig-name descname"><span class="pre">-s</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--start-directory</span></span><span class="sig-prename descclassname"> <span class="pre">directory</span></span><a class="headerlink" href="#cmdoption-unittest-discover-s" title="Link to this definition">¶</a></dt>510<dd><p>Directory to start discovery (<code class="docutils literal notranslate"><span class="pre">.</span></code> default)</p>511</dd></dl>512 513<dl class="std option">514<dt class="sig sig-object std" id="cmdoption-unittest-discover-p">515<span id="cmdoption-unittest-discover-pattern"></span><span class="sig-name descname"><span class="pre">-p</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--pattern</span></span><span class="sig-prename descclassname"> <span class="pre">pattern</span></span><a class="headerlink" href="#cmdoption-unittest-discover-p" title="Link to this definition">¶</a></dt>516<dd><p>Pattern to match test files (<code class="docutils literal notranslate"><span class="pre">test*.py</span></code> default)</p>517</dd></dl>518 519<dl class="std option">520<dt class="sig sig-object std" id="cmdoption-unittest-discover-t">521<span id="cmdoption-unittest-discover-top-level-directory"></span><span class="sig-name descname"><span class="pre">-t</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--top-level-directory</span></span><span class="sig-prename descclassname"> <span class="pre">directory</span></span><a class="headerlink" href="#cmdoption-unittest-discover-t" title="Link to this definition">¶</a></dt>522<dd><p>Top level directory of project (defaults to start directory)</p>523</dd></dl>524 525<p>The <a class="reference internal" href="#cmdoption-unittest-discover-s"><code class="xref std std-option docutils literal notranslate"><span class="pre">-s</span></code></a>, <a class="reference internal" href="#cmdoption-unittest-discover-p"><code class="xref std std-option docutils literal notranslate"><span class="pre">-p</span></code></a>, and <a class="reference internal" href="#cmdoption-unittest-discover-t"><code class="xref std std-option docutils literal notranslate"><span class="pre">-t</span></code></a> options can be passed in526as positional arguments in that order. The following two command lines527are equivalent:</p>528<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">discover</span> <span class="o">-</span><span class="n">s</span> <span class="n">project_directory</span> <span class="o">-</span><span class="n">p</span> <span class="s2">&quot;*_test.py&quot;</span>529<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span> <span class="n">discover</span> <span class="n">project_directory</span> <span class="s2">&quot;*_test.py&quot;</span>530</pre></div>531</div>532<p>As well as being a path it is possible to pass a package name, for example533<code class="docutils literal notranslate"><span class="pre">myproject.subpackage.test</span></code>, as the start directory. The package name you534supply will then be imported and its location on the filesystem will be used535as the start directory.</p>536<div class="admonition caution">537<p class="admonition-title">Caution</p>538<p>Test discovery loads tests by importing them. Once test discovery has found539all the test files from the start directory you specify it turns the paths540into package names to import. For example <code class="file docutils literal notranslate"><span class="pre">foo/bar/baz.py</span></code> will be541imported as <code class="docutils literal notranslate"><span class="pre">foo.bar.baz</span></code>.</p>542<p>If you have a package installed globally and attempt test discovery on543a different copy of the package then the import <em>could</em> happen from the544wrong place. If this happens test discovery will warn you and exit.</p>545<p>If you supply the start directory as a package name rather than a546path to a directory then discover assumes that whichever location it547imports from is the location you intended, so you will not get the548warning.</p>549</div>550<p>Test modules and packages can customize test loading and discovery by through551the <a class="reference internal" href="#id1">load_tests protocol</a>.</p>552<div class="versionchanged">553<p><span class="versionmodified changed">Changed in version 3.4: </span>Test discovery supports <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace packages</span></a>.</p>554</div>555<div class="versionchanged">556<p><span class="versionmodified changed">Changed in version 3.11: </span>Test discovery dropped the <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace packages</span></a>557support. It has been broken since Python 3.7.558Start directory and its subdirectories containing tests must be regular559package that have <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code> file.</p>560<p>If the start directory is the dotted name of the package, the ancestor packages561can be namespace packages.</p>562</div>563<div class="versionchanged">564<p><span class="versionmodified changed">Changed in version 3.14: </span>Test discovery supports <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace package</span></a> as start directory again.565To avoid scanning directories unrelated to Python,566tests are not searched in subdirectories that do not contain <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>.</p>567</div>568</section>569<section id="organizing-test-code">570<span id="organizing-tests"></span><h2>Organizing test code<a class="headerlink" href="#organizing-test-code" title="Link to this heading">¶</a></h2>571<p>The basic building blocks of unit testing are <em class="dfn">test cases</em> — single572scenarios that must be set up and checked for correctness.  In <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code>,573test cases are represented by <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a> instances.574To make your own test cases you must write subclasses of575<a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a> or use <a class="reference internal" href="#unittest.FunctionTestCase" title="unittest.FunctionTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">FunctionTestCase</span></code></a>.</p>576<p>The testing code of a <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a> instance should be entirely self577contained, such that it can be run either in isolation or in arbitrary578combination with any number of other test cases.</p>579<p>The simplest <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a> subclass will simply implement a test method580(i.e. a method whose name starts with <code class="docutils literal notranslate"><span class="pre">test</span></code>) in order to perform specific581testing code:</p>582<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">unittest</span>583 584<span class="k">class</span><span class="w"> </span><span class="nc">DefaultWidgetSizeTestCase</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>585    <span class="k">def</span><span class="w"> </span><span class="nf">test_default_widget_size</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>586        <span class="n">widget</span> <span class="o">=</span> <span class="n">Widget</span><span class="p">(</span><span class="s1">&#39;The widget&#39;</span><span class="p">)</span>587        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">widget</span><span class="o">.</span><span class="n">size</span><span class="p">(),</span> <span class="p">(</span><span class="mi">50</span><span class="p">,</span> <span class="mi">50</span><span class="p">))</span>588</pre></div>589</div>590<p>Note that in order to test something, we use one of the <a class="reference internal" href="#assert-methods"><span class="std std-ref">assert* methods</span></a>591provided by the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a> base class.  If the test fails, an592exception will be raised with an explanatory message, and <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code>593will identify the test case as a <em class="dfn">failure</em>.  Any other exceptions will be594treated as <em class="dfn">errors</em>.</p>595<p>Tests can be numerous, and their set-up can be repetitive.  Luckily, we596can factor out set-up code by implementing a method called597<a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a>, which the testing framework will automatically598call for every single test we run:</p>599<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">unittest</span>600 601<span class="k">class</span><span class="w"> </span><span class="nc">WidgetTestCase</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>602    <span class="k">def</span><span class="w"> </span><span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>603        <span class="bp">self</span><span class="o">.</span><span class="n">widget</span> <span class="o">=</span> <span class="n">Widget</span><span class="p">(</span><span class="s1">&#39;The widget&#39;</span><span class="p">)</span>604 605    <span class="k">def</span><span class="w"> </span><span class="nf">test_default_widget_size</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>606        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">size</span><span class="p">(),</span> <span class="p">(</span><span class="mi">50</span><span class="p">,</span><span class="mi">50</span><span class="p">),</span>607                         <span class="s1">&#39;incorrect default size&#39;</span><span class="p">)</span>608 609    <span class="k">def</span><span class="w"> </span><span class="nf">test_widget_resize</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>610        <span class="bp">self</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">resize</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span><span class="mi">150</span><span class="p">)</span>611        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">size</span><span class="p">(),</span> <span class="p">(</span><span class="mi">100</span><span class="p">,</span><span class="mi">150</span><span class="p">),</span>612                         <span class="s1">&#39;wrong size after resize&#39;</span><span class="p">)</span>613</pre></div>614</div>615<div class="admonition note">616<p class="admonition-title">Note</p>617<p>The order in which the various tests will be run is determined618by sorting the test method names with respect to the built-in619ordering for strings.</p>620</div>621<p>If the <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a> method raises an exception while the test is622running, the framework will consider the test to have suffered an error, and623the test method will not be executed.</p>624<p>Similarly, we can provide a <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tearDown()</span></code></a> method that tidies up625after the test method has been run:</p>626<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">unittest</span>627 628<span class="k">class</span><span class="w"> </span><span class="nc">WidgetTestCase</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>629    <span class="k">def</span><span class="w"> </span><span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>630        <span class="bp">self</span><span class="o">.</span><span class="n">widget</span> <span class="o">=</span> <span class="n">Widget</span><span class="p">(</span><span class="s1">&#39;The widget&#39;</span><span class="p">)</span>631 632    <span class="k">def</span><span class="w"> </span><span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>633        <span class="bp">self</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">dispose</span><span class="p">()</span>634</pre></div>635</div>636<p>If <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a> succeeded, <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tearDown()</span></code></a> will be637run whether the test method succeeded or not.</p>638<p>Such a working environment for the testing code is called a639<em class="dfn">test fixture</em>.  A new TestCase instance is created as a unique640test fixture used to execute each individual test method.  Thus641<a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a>, <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tearDown()</span></code></a>, and <code class="xref py py-meth docutils literal notranslate"><span class="pre">TestCase.__init__()</span></code>642will be called once per test.</p>643<p>It is recommended that you use TestCase implementations to group tests together644according to the features they test.  <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> provides a mechanism for645this: the <em class="dfn">test suite</em>, represented by <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code>’s646<a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestSuite</span></code></a> class.  In most cases, calling <a class="reference internal" href="#unittest.main" title="unittest.main"><code class="xref py py-func docutils literal notranslate"><span class="pre">unittest.main()</span></code></a> will do647the right thing and collect all the module’s test cases for you and execute648them.</p>649<p>However, should you want to customize the building of your test suite,650you can do it yourself:</p>651<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">suite</span><span class="p">():</span>652    <span class="n">suite</span> <span class="o">=</span> <span class="n">unittest</span><span class="o">.</span><span class="n">TestSuite</span><span class="p">()</span>653    <span class="n">suite</span><span class="o">.</span><span class="n">addTest</span><span class="p">(</span><span class="n">WidgetTestCase</span><span class="p">(</span><span class="s1">&#39;test_default_widget_size&#39;</span><span class="p">))</span>654    <span class="n">suite</span><span class="o">.</span><span class="n">addTest</span><span class="p">(</span><span class="n">WidgetTestCase</span><span class="p">(</span><span class="s1">&#39;test_widget_resize&#39;</span><span class="p">))</span>655    <span class="k">return</span> <span class="n">suite</span>656 657<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>658    <span class="n">runner</span> <span class="o">=</span> <span class="n">unittest</span><span class="o">.</span><span class="n">TextTestRunner</span><span class="p">()</span>659    <span class="n">runner</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">suite</span><span class="p">())</span>660</pre></div>661</div>662<p>You can place the definitions of test cases and test suites in the same modules663as the code they are to test (such as <code class="file docutils literal notranslate"><span class="pre">widget.py</span></code>), but there are several664advantages to placing the test code in a separate module, such as665<code class="file docutils literal notranslate"><span class="pre">test_widget.py</span></code>:</p>666<ul class="simple">667<li><p>The test module can be run standalone from the command line.</p></li>668<li><p>The test code can more easily be separated from shipped code.</p></li>669<li><p>There is less temptation to change test code to fit the code it tests without670a good reason.</p></li>671<li><p>Test code should be modified much less frequently than the code it tests.</p></li>672<li><p>Tested code can be refactored more easily.</p></li>673<li><p>Tests for modules written in C must be in separate modules anyway, so why not674be consistent?</p></li>675<li><p>If the testing strategy changes, there is no need to change the source code.</p></li>676</ul>677</section>678<section id="re-using-old-test-code">679<span id="legacy-unit-tests"></span><h2>Re-using old test code<a class="headerlink" href="#re-using-old-test-code" title="Link to this heading">¶</a></h2>680<p>Some users will find that they have existing test code that they would like to681run from <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code>, without converting every old test function to a682<a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a> subclass.</p>683<p>For this reason, <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> provides a <a class="reference internal" href="#unittest.FunctionTestCase" title="unittest.FunctionTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">FunctionTestCase</span></code></a> class.684This subclass of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a> can be used to wrap an existing test685function.  Set-up and tear-down functions can also be provided.</p>686<p>Given the following test function:</p>687<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">testSomething</span><span class="p">():</span>688    <span class="n">something</span> <span class="o">=</span> <span class="n">makeSomething</span><span class="p">()</span>689    <span class="k">assert</span> <span class="n">something</span><span class="o">.</span><span class="n">name</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>690    <span class="c1"># ...</span>691</pre></div>692</div>693<p>one can create an equivalent test case instance as follows, with optional694set-up and tear-down methods:</p>695<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">testcase</span> <span class="o">=</span> <span class="n">unittest</span><span class="o">.</span><span class="n">FunctionTestCase</span><span class="p">(</span><span class="n">testSomething</span><span class="p">,</span>696                                     <span class="n">setUp</span><span class="o">=</span><span class="n">makeSomethingDB</span><span class="p">,</span>697                                     <span class="n">tearDown</span><span class="o">=</span><span class="n">deleteSomethingDB</span><span class="p">)</span>698</pre></div>699</div>700<div class="admonition note">701<p class="admonition-title">Note</p>702<p>Even though <a class="reference internal" href="#unittest.FunctionTestCase" title="unittest.FunctionTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">FunctionTestCase</span></code></a> can be used to quickly convert an703existing test base over to a <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code>-based system, this approach is704not recommended.  Taking the time to set up proper <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a>705subclasses will make future test refactorings infinitely easier.</p>706</div>707<p>In some cases, the existing tests may have been written using the <a class="reference internal" href="doctest.html#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a>708module.  If so, <code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> provides a <a class="reference internal" href="doctest.html#doctest.DocTestSuite" title="doctest.DocTestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestSuite</span></code></a> class that can709automatically build <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> instances from the existing710<code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code>-based tests.</p>711</section>712<section id="skipping-tests-and-expected-failures">713<span id="unittest-skipping"></span><h2>Skipping tests and expected failures<a class="headerlink" href="#skipping-tests-and-expected-failures" title="Link to this heading">¶</a></h2>714<div class="versionadded">715<p><span class="versionmodified added">Added in version 3.1.</span></p>716</div>717<p>Unittest supports skipping individual test methods and even whole classes of718tests.  In addition, it supports marking a test as an “expected failure,” a test719that is broken and will fail, but shouldn’t be counted as a failure on a720<a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestResult</span></code></a>.</p>721<p>Skipping a test is simply a matter of using the <a class="reference internal" href="#unittest.skip" title="unittest.skip"><code class="xref py py-func docutils literal notranslate"><span class="pre">skip()</span></code></a> <a class="reference internal" href="../glossary.html#term-decorator"><span class="xref std std-term">decorator</span></a>722or one of its conditional variants, calling <a class="reference internal" href="#unittest.TestCase.skipTest" title="unittest.TestCase.skipTest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TestCase.skipTest()</span></code></a> within a723<a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a> or test method, or raising <a class="reference internal" href="#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SkipTest</span></code></a> directly.</p>724<p>Basic skipping looks like this:</p>725<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">MyTestCase</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>726 727    <span class="nd">@unittest</span><span class="o">.</span><span class="n">skip</span><span class="p">(</span><span class="s2">&quot;demonstrating skipping&quot;</span><span class="p">)</span>728    <span class="k">def</span><span class="w"> </span><span class="nf">test_nothing</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>729        <span class="bp">self</span><span class="o">.</span><span class="n">fail</span><span class="p">(</span><span class="s2">&quot;shouldn&#39;t happen&quot;</span><span class="p">)</span>730 731    <span class="nd">@unittest</span><span class="o">.</span><span class="n">skipIf</span><span class="p">(</span><span class="n">mylib</span><span class="o">.</span><span class="n">__version__</span> <span class="o">&lt;</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">),</span>732                     <span class="s2">&quot;not supported in this library version&quot;</span><span class="p">)</span>733    <span class="k">def</span><span class="w"> </span><span class="nf">test_format</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>734        <span class="c1"># Tests that work for only a certain version of the library.</span>735        <span class="k">pass</span>736 737    <span class="nd">@unittest</span><span class="o">.</span><span class="n">skipUnless</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">platform</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&quot;win&quot;</span><span class="p">),</span> <span class="s2">&quot;requires Windows&quot;</span><span class="p">)</span>738    <span class="k">def</span><span class="w"> </span><span class="nf">test_windows_support</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>739        <span class="c1"># windows specific testing code</span>740        <span class="k">pass</span>741 742    <span class="k">def</span><span class="w"> </span><span class="nf">test_maybe_skipped</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>743        <span class="k">if</span> <span class="ow">not</span> <span class="n">external_resource_available</span><span class="p">():</span>744            <span class="bp">self</span><span class="o">.</span><span class="n">skipTest</span><span class="p">(</span><span class="s2">&quot;external resource not available&quot;</span><span class="p">)</span>745        <span class="c1"># test code that depends on the external resource</span>746        <span class="k">pass</span>747</pre></div>748</div>749<p>This is the output of running the example above in verbose mode:</p>750<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">test_format</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">MyTestCase</span><span class="o">.</span><span class="n">test_format</span><span class="p">)</span> <span class="o">...</span> <span class="n">skipped</span> <span class="s1">&#39;not supported in this library version&#39;</span>751<span class="n">test_nothing</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">MyTestCase</span><span class="o">.</span><span class="n">test_nothing</span><span class="p">)</span> <span class="o">...</span> <span class="n">skipped</span> <span class="s1">&#39;demonstrating skipping&#39;</span>752<span class="n">test_maybe_skipped</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">MyTestCase</span><span class="o">.</span><span class="n">test_maybe_skipped</span><span class="p">)</span> <span class="o">...</span> <span class="n">skipped</span> <span class="s1">&#39;external resource not available&#39;</span>753<span class="n">test_windows_support</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">MyTestCase</span><span class="o">.</span><span class="n">test_windows_support</span><span class="p">)</span> <span class="o">...</span> <span class="n">skipped</span> <span class="s1">&#39;requires Windows&#39;</span>754 755<span class="o">----------------------------------------------------------------------</span>756<span class="n">Ran</span> <span class="mi">4</span> <span class="n">tests</span> <span class="ow">in</span> <span class="mf">0.005</span><span class="n">s</span>757 758<span class="n">OK</span> <span class="p">(</span><span class="n">skipped</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>759</pre></div>760</div>761<p>Classes can be skipped just like methods:</p>762<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@unittest</span><span class="o">.</span><span class="n">skip</span><span class="p">(</span><span class="s2">&quot;showing class skipping&quot;</span><span class="p">)</span>763<span class="k">class</span><span class="w"> </span><span class="nc">MySkippedTestCase</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>764    <span class="k">def</span><span class="w"> </span><span class="nf">test_not_run</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>765        <span class="k">pass</span>766</pre></div>767</div>768<p><a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TestCase.setUp()</span></code></a> can also skip the test.  This is useful when a resource769that needs to be set up is not available.</p>770<p>Expected failures use the <a class="reference internal" href="#unittest.expectedFailure" title="unittest.expectedFailure"><code class="xref py py-func docutils literal notranslate"><span class="pre">expectedFailure()</span></code></a> decorator.</p>771<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">ExpectedFailureTestCase</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>772    <span class="nd">@unittest</span><span class="o">.</span><span class="n">expectedFailure</span>773    <span class="k">def</span><span class="w"> </span><span class="nf">test_fail</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>774        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="s2">&quot;broken&quot;</span><span class="p">)</span>775</pre></div>776</div>777<p>It’s easy to roll your own skipping decorators by making a decorator that calls778<a class="reference internal" href="#unittest.skip" title="unittest.skip"><code class="xref py py-func docutils literal notranslate"><span class="pre">skip()</span></code></a> on the test when it wants it to be skipped.  This decorator skips779the test unless the passed object has a certain attribute:</p>780<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">skipUnlessHasattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">attr</span><span class="p">):</span>781    <span class="k">if</span> <span class="nb">hasattr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">attr</span><span class="p">):</span>782        <span class="k">return</span> <span class="k">lambda</span> <span class="n">func</span><span class="p">:</span> <span class="n">func</span>783    <span class="k">return</span> <span class="n">unittest</span><span class="o">.</span><span class="n">skip</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">{!r}</span><span class="s2"> doesn&#39;t have </span><span class="si">{!r}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">attr</span><span class="p">))</span>784</pre></div>785</div>786<p>The following decorators and exception implement test skipping and expected failures:</p>787<dl class="py function">788<dt class="sig sig-object py" id="unittest.skip">789<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">skip</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">reason</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.skip" title="Link to this definition">¶</a></dt>790<dd><p>Unconditionally skip the decorated test.  <em>reason</em> should describe why the791test is being skipped.</p>792</dd></dl>793 794<dl class="py function">795<dt class="sig sig-object py" id="unittest.skipIf">796<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">skipIf</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">condition</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">reason</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.skipIf" title="Link to this definition">¶</a></dt>797<dd><p>Skip the decorated test if <em>condition</em> is true.</p>798</dd></dl>799 800<dl class="py function">801<dt class="sig sig-object py" id="unittest.skipUnless">802<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">skipUnless</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">condition</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">reason</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.skipUnless" title="Link to this definition">¶</a></dt>803<dd><p>Skip the decorated test unless <em>condition</em> is true.</p>804</dd></dl>805 806<dl class="py function">807<dt class="sig sig-object py" id="unittest.expectedFailure">808<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">expectedFailure</span></span><a class="headerlink" href="#unittest.expectedFailure" title="Link to this definition">¶</a></dt>809<dd><p>Mark the test as an expected failure or error.  If the test fails or errors810in the test function itself (rather than in one of the <em class="dfn">test fixture</em>811methods) then it will be considered a success.  If the test passes, it will812be considered a failure.</p>813</dd></dl>814 815<dl class="py exception">816<dt class="sig sig-object py" id="unittest.SkipTest">817<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">SkipTest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">reason</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.SkipTest" title="Link to this definition">¶</a></dt>818<dd><p>This exception is raised to skip a test.</p>819<p>Usually you can use <a class="reference internal" href="#unittest.TestCase.skipTest" title="unittest.TestCase.skipTest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TestCase.skipTest()</span></code></a> or one of the skipping820decorators instead of raising this directly.</p>821</dd></dl>822 823<p>Skipped tests will not have <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a> or <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tearDown()</span></code></a> run around them.824Skipped classes will not have <a class="reference internal" href="#unittest.TestCase.setUpClass" title="unittest.TestCase.setUpClass"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUpClass()</span></code></a> or <a class="reference internal" href="#unittest.TestCase.tearDownClass" title="unittest.TestCase.tearDownClass"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tearDownClass()</span></code></a> run.825Skipped modules will not have <a class="reference internal" href="#unittest.setUpModule" title="unittest.setUpModule"><code class="xref py py-func docutils literal notranslate"><span class="pre">setUpModule()</span></code></a> or <a class="reference internal" href="#unittest.tearDownModule" title="unittest.tearDownModule"><code class="xref py py-func docutils literal notranslate"><span class="pre">tearDownModule()</span></code></a> run.</p>826</section>827<section id="distinguishing-test-iterations-using-subtests">828<span id="subtests"></span><h2>Distinguishing test iterations using subtests<a class="headerlink" href="#distinguishing-test-iterations-using-subtests" title="Link to this heading">¶</a></h2>829<div class="versionadded">830<p><span class="versionmodified added">Added in version 3.4.</span></p>831</div>832<p>When there are very small differences among your tests, for833instance some parameters, unittest allows you to distinguish them inside834the body of a test method using the <a class="reference internal" href="#unittest.TestCase.subTest" title="unittest.TestCase.subTest"><code class="xref py py-meth docutils literal notranslate"><span class="pre">subTest()</span></code></a> context manager.</p>835<p>For example, the following test:</p>836<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">NumbersTest</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>837 838    <span class="k">def</span><span class="w"> </span><span class="nf">test_even</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>839<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>840<span class="sd">        Test that numbers between 0 and 5 are all even.</span>841<span class="sd">        &quot;&quot;&quot;</span>842        <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">6</span><span class="p">):</span>843            <span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">subTest</span><span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="n">i</span><span class="p">):</span>844                <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">i</span> <span class="o">%</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>845</pre></div>846</div>847<p>will produce the following output:</p>848<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">======================================================================</span>849<span class="n">FAIL</span><span class="p">:</span> <span class="n">test_even</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">NumbersTest</span><span class="o">.</span><span class="n">test_even</span><span class="p">)</span> <span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>850<span class="n">Test</span> <span class="n">that</span> <span class="n">numbers</span> <span class="n">between</span> <span class="mi">0</span> <span class="ow">and</span> <span class="mi">5</span> <span class="n">are</span> <span class="nb">all</span> <span class="n">even</span><span class="o">.</span>851<span class="o">----------------------------------------------------------------------</span>852<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>853  <span class="n">File</span> <span class="s2">&quot;subtests.py&quot;</span><span class="p">,</span> <span class="n">line</span> <span class="mi">11</span><span class="p">,</span> <span class="ow">in</span> <span class="n">test_even</span>854    <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">i</span> <span class="o">%</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>855    <span class="o">^^^^^^^^^^^^^^^^^^^^^^^^^^</span>856<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>857 858<span class="o">======================================================================</span>859<span class="n">FAIL</span><span class="p">:</span> <span class="n">test_even</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">NumbersTest</span><span class="o">.</span><span class="n">test_even</span><span class="p">)</span> <span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>860<span class="n">Test</span> <span class="n">that</span> <span class="n">numbers</span> <span class="n">between</span> <span class="mi">0</span> <span class="ow">and</span> <span class="mi">5</span> <span class="n">are</span> <span class="nb">all</span> <span class="n">even</span><span class="o">.</span>861<span class="o">----------------------------------------------------------------------</span>862<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>863  <span class="n">File</span> <span class="s2">&quot;subtests.py&quot;</span><span class="p">,</span> <span class="n">line</span> <span class="mi">11</span><span class="p">,</span> <span class="ow">in</span> <span class="n">test_even</span>864    <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">i</span> <span class="o">%</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>865    <span class="o">^^^^^^^^^^^^^^^^^^^^^^^^^^</span>866<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>867 868<span class="o">======================================================================</span>869<span class="n">FAIL</span><span class="p">:</span> <span class="n">test_even</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">NumbersTest</span><span class="o">.</span><span class="n">test_even</span><span class="p">)</span> <span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>870<span class="n">Test</span> <span class="n">that</span> <span class="n">numbers</span> <span class="n">between</span> <span class="mi">0</span> <span class="ow">and</span> <span class="mi">5</span> <span class="n">are</span> <span class="nb">all</span> <span class="n">even</span><span class="o">.</span>871<span class="o">----------------------------------------------------------------------</span>872<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>873  <span class="n">File</span> <span class="s2">&quot;subtests.py&quot;</span><span class="p">,</span> <span class="n">line</span> <span class="mi">11</span><span class="p">,</span> <span class="ow">in</span> <span class="n">test_even</span>874    <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">i</span> <span class="o">%</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>875    <span class="o">^^^^^^^^^^^^^^^^^^^^^^^^^^</span>876<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>877</pre></div>878</div>879<p>Without using a subtest, execution would stop after the first failure,880and the error would be less easy to diagnose because the value of <code class="docutils literal notranslate"><span class="pre">i</span></code>881wouldn’t be displayed:</p>882<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o">======================================================================</span>883<span class="n">FAIL</span><span class="p">:</span> <span class="n">test_even</span> <span class="p">(</span><span class="n">__main__</span><span class="o">.</span><span class="n">NumbersTest</span><span class="o">.</span><span class="n">test_even</span><span class="p">)</span>884<span class="o">----------------------------------------------------------------------</span>885<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>886  <span class="n">File</span> <span class="s2">&quot;subtests.py&quot;</span><span class="p">,</span> <span class="n">line</span> <span class="mi">32</span><span class="p">,</span> <span class="ow">in</span> <span class="n">test_even</span>887    <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">i</span> <span class="o">%</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>888<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>889</pre></div>890</div>891</section>892<section id="classes-and-functions">893<span id="unittest-contents"></span><h2>Classes and functions<a class="headerlink" href="#classes-and-functions" title="Link to this heading">¶</a></h2>894<p>This section describes in depth the API of <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code>.</p>895<section id="test-cases">896<span id="testcase-objects"></span><h3>Test cases<a class="headerlink" href="#test-cases" title="Link to this heading">¶</a></h3>897<dl class="py class">898<dt class="sig sig-object py" id="unittest.TestCase">899<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">TestCase</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">methodName</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'runTest'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase" title="Link to this definition">¶</a></dt>900<dd><p>Instances of the <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code> class represent the logical test units901in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> universe.  This class is intended to be used as a base902class, with specific tests being implemented by concrete subclasses.  This class903implements the interface needed by the test runner to allow it to drive the904tests, and methods that the test code can use to check for and report various905kinds of failure.</p>906<p>Each instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code> will run a single base method: the method907named <em>methodName</em>.908In most uses of <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code>, you will neither change909the <em>methodName</em> nor reimplement the default <code class="docutils literal notranslate"><span class="pre">runTest()</span></code> method.</p>910<div class="versionchanged">911<p><span class="versionmodified changed">Changed in version 3.2: </span><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code> can be instantiated successfully without providing a912<em>methodName</em>. This makes it easier to experiment with <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code>913from the interactive interpreter.</p>914</div>915<p><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code> instances provide three groups of methods: one group used916to run the test, another used by the test implementation to check conditions917and report failures, and some inquiry methods allowing information about the918test itself to be gathered.</p>919<p>Methods in the first group (running the test) are:</p>920<dl class="py method">921<dt class="sig sig-object py" id="unittest.TestCase.setUp">922<span class="sig-name descname"><span class="pre">setUp</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.setUp" title="Link to this definition">¶</a></dt>923<dd><p>Method called to prepare the test fixture.  This is called immediately924before calling the test method; other than <a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a> or <a class="reference internal" href="#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SkipTest</span></code></a>,925any exception raised by this method will be considered an error rather than926a test failure. The default implementation does nothing.</p>927</dd></dl>928 929<dl class="py method">930<dt class="sig sig-object py" id="unittest.TestCase.tearDown">931<span class="sig-name descname"><span class="pre">tearDown</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.tearDown" title="Link to this definition">¶</a></dt>932<dd><p>Method called immediately after the test method has been called and the933result recorded.  This is called even if the test method raised an934exception, so the implementation in subclasses may need to be particularly935careful about checking internal state.  Any exception, other than936<a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a> or <a class="reference internal" href="#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SkipTest</span></code></a>, raised by this method will be937considered an additional error rather than a test failure (thus increasing938the total number of reported errors). This method will only be called if939the <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a> succeeds, regardless of the outcome of the test method.940The default implementation does nothing.</p>941</dd></dl>942 943<dl class="py method">944<dt class="sig sig-object py" id="unittest.TestCase.setUpClass">945<span class="sig-name descname"><span class="pre">setUpClass</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.setUpClass" title="Link to this definition">¶</a></dt>946<dd><p>A class method called before tests in an individual class are run.947<code class="docutils literal notranslate"><span class="pre">setUpClass</span></code> is called with the class as the only argument948and must be decorated as a <a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal notranslate"><span class="pre">classmethod()</span></code></a>:</p>949<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@classmethod</span>950<span class="k">def</span><span class="w"> </span><span class="nf">setUpClass</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>951    <span class="o">...</span>952</pre></div>953</div>954<p>See <a class="reference internal" href="#class-and-module-fixtures">Class and Module Fixtures</a> for more details.</p>955<div class="versionadded">956<p><span class="versionmodified added">Added in version 3.2.</span></p>957</div>958</dd></dl>959 960<dl class="py method">961<dt class="sig sig-object py" id="unittest.TestCase.tearDownClass">962<span class="sig-name descname"><span class="pre">tearDownClass</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.tearDownClass" title="Link to this definition">¶</a></dt>963<dd><p>A class method called after tests in an individual class have run.964<code class="docutils literal notranslate"><span class="pre">tearDownClass</span></code> is called with the class as the only argument965and must be decorated as a <a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-meth docutils literal notranslate"><span class="pre">classmethod()</span></code></a>:</p>966<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="nd">@classmethod</span>967<span class="k">def</span><span class="w"> </span><span class="nf">tearDownClass</span><span class="p">(</span><span class="bp">cls</span><span class="p">):</span>968    <span class="o">...</span>969</pre></div>970</div>971<p>See <a class="reference internal" href="#class-and-module-fixtures">Class and Module Fixtures</a> for more details.</p>972<div class="versionadded">973<p><span class="versionmodified added">Added in version 3.2.</span></p>974</div>975</dd></dl>976 977<dl class="py method">978<dt class="sig sig-object py" id="unittest.TestCase.run">979<span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">result</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.run" title="Link to this definition">¶</a></dt>980<dd><p>Run the test, collecting the result into the <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestResult</span></code></a> object981passed as <em>result</em>.  If <em>result</em> is omitted or <code class="docutils literal notranslate"><span class="pre">None</span></code>, a temporary982result object is created (by calling the <a class="reference internal" href="#unittest.TestCase.defaultTestResult" title="unittest.TestCase.defaultTestResult"><code class="xref py py-meth docutils literal notranslate"><span class="pre">defaultTestResult()</span></code></a>983method) and used. The result object is returned to <code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code>’s984caller.</p>985<p>The same effect may be had by simply calling the <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code>986instance.</p>987<div class="versionchanged">988<p><span class="versionmodified changed">Changed in version 3.3: </span>Previous versions of <code class="docutils literal notranslate"><span class="pre">run</span></code> did not return the result. Neither did989calling an instance.</p>990</div>991</dd></dl>992 993<dl class="py method">994<dt class="sig sig-object py" id="unittest.TestCase.skipTest">995<span class="sig-name descname"><span class="pre">skipTest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">reason</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.skipTest" title="Link to this definition">¶</a></dt>996<dd><p>Calling this during a test method or <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setUp()</span></code></a> skips the current997test.  See <a class="reference internal" href="#unittest-skipping"><span class="std std-ref">Skipping tests and expected failures</span></a> for more information.</p>998<div class="versionadded">999<p><span class="versionmodified added">Added in version 3.1.</span></p>1000</div>1001</dd></dl>1002 1003<dl class="py method">1004<dt class="sig sig-object py" id="unittest.TestCase.subTest">1005<span class="sig-name descname"><span class="pre">subTest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">params</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.subTest" title="Link to this definition">¶</a></dt>1006<dd><p>Return a context manager which executes the enclosed code block as a1007subtest.  <em>msg</em> and <em>params</em> are optional, arbitrary values which are1008displayed whenever a subtest fails, allowing you to identify them1009clearly.</p>1010<p>A test case can contain any number of subtest declarations, and1011they can be arbitrarily nested.</p>1012<p>See <a class="reference internal" href="#subtests"><span class="std std-ref">Distinguishing test iterations using subtests</span></a> for more information.</p>1013<div class="versionadded">1014<p><span class="versionmodified added">Added in version 3.4.</span></p>1015</div>1016</dd></dl>1017 1018<dl class="py method">1019<dt class="sig sig-object py" id="unittest.TestCase.debug">1020<span class="sig-name descname"><span class="pre">debug</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.debug" title="Link to this definition">¶</a></dt>1021<dd><p>Run the test without collecting the result.  This allows exceptions raised1022by the test to be propagated to the caller, and can be used to support1023running tests under a debugger.</p>1024</dd></dl>1025 1026<p id="assert-methods">The <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code> class provides several assert methods to check for and1027report failures.  The following table lists the most commonly used methods1028(see the tables below for more assert methods):</p>1029<table class="docutils align-default">1030<thead>1031<tr class="row-odd"><th class="head"><p>Method</p></th>1032<th class="head"><p>Checks that</p></th>1033<th class="head"><p>New in</p></th>1034</tr>1035</thead>1036<tbody>1037<tr class="row-even"><td><p><a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertEqual(a,</span> <span class="pre">b)</span></code></a></p></td>1038<td><p><code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></code></p></td>1039<td></td>1040</tr>1041<tr class="row-odd"><td><p><a class="reference internal" href="#unittest.TestCase.assertNotEqual" title="unittest.TestCase.assertNotEqual"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertNotEqual(a,</span> <span class="pre">b)</span></code></a></p></td>1042<td><p><code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></code></p></td>1043<td></td>1044</tr>1045<tr class="row-even"><td><p><a class="reference internal" href="#unittest.TestCase.assertTrue" title="unittest.TestCase.assertTrue"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertTrue(x)</span></code></a></p></td>1046<td><p><code class="docutils literal notranslate"><span class="pre">bool(x)</span> <span class="pre">is</span> <span class="pre">True</span></code></p></td>1047<td></td>1048</tr>1049<tr class="row-odd"><td><p><a class="reference internal" href="#unittest.TestCase.assertFalse" title="unittest.TestCase.assertFalse"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertFalse(x)</span></code></a></p></td>1050<td><p><code class="docutils literal notranslate"><span class="pre">bool(x)</span> <span class="pre">is</span> <span class="pre">False</span></code></p></td>1051<td></td>1052</tr>1053<tr class="row-even"><td><p><a class="reference internal" href="#unittest.TestCase.assertIs" title="unittest.TestCase.assertIs"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertIs(a,</span> <span class="pre">b)</span></code></a></p></td>1054<td><p><code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">is</span> <span class="pre">b</span></code></p></td>1055<td><p>3.1</p></td>1056</tr>1057<tr class="row-odd"><td><p><a class="reference internal" href="#unittest.TestCase.assertIsNot" title="unittest.TestCase.assertIsNot"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertIsNot(a,</span> <span class="pre">b)</span></code></a></p></td>1058<td><p><code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">b</span></code></p></td>1059<td><p>3.1</p></td>1060</tr>1061<tr class="row-even"><td><p><a class="reference internal" href="#unittest.TestCase.assertIsNone" title="unittest.TestCase.assertIsNone"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertIsNone(x)</span></code></a></p></td>1062<td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">None</span></code></p></td>1063<td><p>3.1</p></td>1064</tr>1065<tr class="row-odd"><td><p><a class="reference internal" href="#unittest.TestCase.assertIsNotNone" title="unittest.TestCase.assertIsNotNone"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertIsNotNone(x)</span></code></a></p></td>1066<td><p><code class="docutils literal notranslate"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">None</span></code></p></td>1067<td><p>3.1</p></td>1068</tr>1069<tr class="row-even"><td><p><a class="reference internal" href="#unittest.TestCase.assertIn" title="unittest.TestCase.assertIn"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertIn(a,</span> <span class="pre">b)</span></code></a></p></td>1070<td><p><code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">in</span> <span class="pre">b</span></code></p></td>1071<td><p>3.1</p></td>1072</tr>1073<tr class="row-odd"><td><p><a class="reference internal" href="#unittest.TestCase.assertNotIn" title="unittest.TestCase.assertNotIn"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertNotIn(a,</span> <span class="pre">b)</span></code></a></p></td>1074<td><p><code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">b</span></code></p></td>1075<td><p>3.1</p></td>1076</tr>1077<tr class="row-even"><td><p><a class="reference internal" href="#unittest.TestCase.assertIsInstance" title="unittest.TestCase.assertIsInstance"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertIsInstance(a,</span> <span class="pre">b)</span></code></a></p></td>1078<td><p><code class="docutils literal notranslate"><span class="pre">isinstance(a,</span> <span class="pre">b)</span></code></p></td>1079<td><p>3.2</p></td>1080</tr>1081<tr class="row-odd"><td><p><a class="reference internal" href="#unittest.TestCase.assertNotIsInstance" title="unittest.TestCase.assertNotIsInstance"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertNotIsInstance(a,</span> <span class="pre">b)</span></code></a></p></td>1082<td><p><code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">isinstance(a,</span> <span class="pre">b)</span></code></p></td>1083<td><p>3.2</p></td>1084</tr>1085<tr class="row-even"><td><p><a class="reference internal" href="#unittest.TestCase.assertIsSubclass" title="unittest.TestCase.assertIsSubclass"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertIsSubclass(a,</span> <span class="pre">b)</span></code></a></p></td>1086<td><p><code class="docutils literal notranslate"><span class="pre">issubclass(a,</span> <span class="pre">b)</span></code></p></td>1087<td><p>3.14</p></td>1088</tr>1089<tr class="row-odd"><td><p><a class="reference internal" href="#unittest.TestCase.assertNotIsSubclass" title="unittest.TestCase.assertNotIsSubclass"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertNotIsSubclass(a,</span> <span class="pre">b)</span></code></a></p></td>1090<td><p><code class="docutils literal notranslate"><span class="pre">not</span> <span class="pre">issubclass(a,</span> <span class="pre">b)</span></code></p></td>1091<td><p>3.14</p></td>1092</tr>1093</tbody>1094</table>1095<p>All the assert methods accept a <em>msg</em> argument that, if specified, is used1096as the error message on failure (see also <a class="reference internal" href="#unittest.TestCase.longMessage" title="unittest.TestCase.longMessage"><code class="xref py py-data docutils literal notranslate"><span class="pre">longMessage</span></code></a>).1097Note that the <em>msg</em> keyword argument can be passed to <a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertRaises()</span></code></a>,1098<a class="reference internal" href="#unittest.TestCase.assertRaisesRegex" title="unittest.TestCase.assertRaisesRegex"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertRaisesRegex()</span></code></a>, <a class="reference internal" href="#unittest.TestCase.assertWarns" title="unittest.TestCase.assertWarns"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertWarns()</span></code></a>, <a class="reference internal" href="#unittest.TestCase.assertWarnsRegex" title="unittest.TestCase.assertWarnsRegex"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertWarnsRegex()</span></code></a>1099only when they are used as a context manager.</p>1100<dl class="py method">1101<dt class="sig sig-object py" id="unittest.TestCase.assertEqual">1102<span class="sig-name descname"><span class="pre">assertEqual</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">first</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertEqual" title="Link to this definition">¶</a></dt>1103<dd><p>Test that <em>first</em> and <em>second</em> are equal.  If the values do not1104compare equal, the test will fail.</p>1105<p>In addition, if <em>first</em> and <em>second</em> are the exact same type and one of1106list, tuple, dict, set, frozenset or str or any type that a subclass1107registers with <a class="reference internal" href="#unittest.TestCase.addTypeEqualityFunc" title="unittest.TestCase.addTypeEqualityFunc"><code class="xref py py-meth docutils literal notranslate"><span class="pre">addTypeEqualityFunc()</span></code></a> the type-specific equality1108function will be called in order to generate a more useful default1109error message (see also the <a class="reference internal" href="#type-specific-methods"><span class="std std-ref">list of type-specific methods</span></a>).</p>1110<div class="versionchanged">1111<p><span class="versionmodified changed">Changed in version 3.1: </span>Added the automatic calling of type-specific equality function.</p>1112</div>1113<div class="versionchanged">1114<p><span class="versionmodified changed">Changed in version 3.2: </span><a class="reference internal" href="#unittest.TestCase.assertMultiLineEqual" title="unittest.TestCase.assertMultiLineEqual"><code class="xref py py-meth docutils literal notranslate"><span class="pre">assertMultiLineEqual()</span></code></a> added as the default type equality1115function for comparing strings.</p>1116</div>1117</dd></dl>1118 1119<dl class="py method">1120<dt class="sig sig-object py" id="unittest.TestCase.assertNotEqual">1121<span class="sig-name descname"><span class="pre">assertNotEqual</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">first</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertNotEqual" title="Link to this definition">¶</a></dt>1122<dd><p>Test that <em>first</em> and <em>second</em> are not equal.  If the values do1123compare equal, the test will fail.</p>1124</dd></dl>1125 1126<dl class="py method">1127<dt class="sig sig-object py" id="unittest.TestCase.assertTrue">1128<span class="sig-name descname"><span class="pre">assertTrue</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">expr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertTrue" title="Link to this definition">¶</a></dt>1129<dt class="sig sig-object py" id="unittest.TestCase.assertFalse">1130<span class="sig-name descname"><span class="pre">assertFalse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">expr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertFalse" title="Link to this definition">¶</a></dt>1131<dd><p>Test that <em>expr</em> is true (or false).</p>1132<p>Note that this is equivalent to <code class="docutils literal notranslate"><span class="pre">bool(expr)</span> <span class="pre">is</span> <span class="pre">True</span></code> and not to <code class="docutils literal notranslate"><span class="pre">expr</span>1133<span class="pre">is</span> <span class="pre">True</span></code> (use <code class="docutils literal notranslate"><span class="pre">assertIs(expr,</span> <span class="pre">True)</span></code> for the latter).  This method1134should also be avoided when more specific methods are available (e.g.1135<code class="docutils literal notranslate"><span class="pre">assertEqual(a,</span> <span class="pre">b)</span></code> instead of <code class="docutils literal notranslate"><span class="pre">assertTrue(a</span> <span class="pre">==</span> <span class="pre">b)</span></code>), because they1136provide a better error message in case of failure.</p>1137</dd></dl>1138 1139<dl class="py method">1140<dt class="sig sig-object py" id="unittest.TestCase.assertIs">1141<span class="sig-name descname"><span class="pre">assertIs</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">first</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertIs" title="Link to this definition">¶</a></dt>1142<dt class="sig sig-object py" id="unittest.TestCase.assertIsNot">1143<span class="sig-name descname"><span class="pre">assertIsNot</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">first</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">second</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertIsNot" title="Link to this definition">¶</a></dt>1144<dd><p>Test that <em>first</em> and <em>second</em> are (or are not) the same object.</p>1145<div class="versionadded">1146<p><span class="versionmodified added">Added in version 3.1.</span></p>1147</div>1148</dd></dl>1149 1150<dl class="py method">1151<dt class="sig sig-object py" id="unittest.TestCase.assertIsNone">1152<span class="sig-name descname"><span class="pre">assertIsNone</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">expr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertIsNone" title="Link to this definition">¶</a></dt>1153<dt class="sig sig-object py" id="unittest.TestCase.assertIsNotNone">1154<span class="sig-name descname"><span class="pre">assertIsNotNone</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">expr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertIsNotNone" title="Link to this definition">¶</a></dt>1155<dd><p>Test that <em>expr</em> is (or is not) <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>1156<div class="versionadded">1157<p><span class="versionmodified added">Added in version 3.1.</span></p>1158</div>1159</dd></dl>1160 1161<dl class="py method">1162<dt class="sig sig-object py" id="unittest.TestCase.assertIn">1163<span class="sig-name descname"><span class="pre">assertIn</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">member</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">container</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertIn" title="Link to this definition">¶</a></dt>1164<dt class="sig sig-object py" id="unittest.TestCase.assertNotIn">1165<span class="sig-name descname"><span class="pre">assertNotIn</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">member</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">container</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertNotIn" title="Link to this definition">¶</a></dt>1166<dd><p>Test that <em>member</em> is (or is not) in <em>container</em>.</p>1167<div class="versionadded">1168<p><span class="versionmodified added">Added in version 3.1.</span></p>1169</div>1170</dd></dl>1171 1172<dl class="py method">1173<dt class="sig sig-object py" id="unittest.TestCase.assertIsInstance">1174<span class="sig-name descname"><span class="pre">assertIsInstance</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cls</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertIsInstance" title="Link to this definition">¶</a></dt>1175<dt class="sig sig-object py" id="unittest.TestCase.assertNotIsInstance">1176<span class="sig-name descname"><span class="pre">assertNotIsInstance</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cls</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertNotIsInstance" title="Link to this definition">¶</a></dt>1177<dd><p>Test that <em>obj</em> is (or is not) an instance of <em>cls</em> (which can be a1178class or a tuple of classes, as supported by <a class="reference internal" href="functions.html#isinstance" title="isinstance"><code class="xref py py-func docutils literal notranslate"><span class="pre">isinstance()</span></code></a>).1179To check for the exact type, use <a class="reference internal" href="#unittest.TestCase.assertIs" title="unittest.TestCase.assertIs"><code class="xref py py-func docutils literal notranslate"><span class="pre">assertIs(type(obj),</span> <span class="pre">cls)</span></code></a>.</p>1180<div class="versionadded">1181<p><span class="versionmodified added">Added in version 3.2.</span></p>1182</div>1183</dd></dl>1184 1185<dl class="py method">1186<dt class="sig sig-object py" id="unittest.TestCase.assertIsSubclass">1187<span class="sig-name descname"><span class="pre">assertIsSubclass</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cls</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superclass</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertIsSubclass" title="Link to this definition">¶</a></dt>1188<dt class="sig sig-object py" id="unittest.TestCase.assertNotIsSubclass">1189<span class="sig-name descname"><span class="pre">assertNotIsSubclass</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cls</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superclass</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#unittest.TestCase.assertNotIsSubclass" title="Link to this definition">¶</a></dt>1190<dd><p>Test that <em>cls</em> is (or is not) a subclass of <em>superclass</em> (which can be a1191class or a tuple of classes, as supported by <a class="reference internal" href="functions.html#issubclass" title="issubclass"><code class="xref py py-func docutils literal notranslate"><span class="pre">issubclass()</span></code></a>).1192To check for the exact type, use <a class="reference internal" href="#unittest.TestCase.assertIs" title="unittest.TestCase.assertIs"><code class="xref py py-func docutils literal notranslate"><span class="pre">assertIs(cls,</span> <span class="pre">superclass)</span></code></a>.</p>1193<div class="versionadded">1194<p><span class="versionmodified added">Added in version 3.14.</span></p>1195</div>1196</dd></dl>1197 1198<p>It is also possible to check the production of exceptions, warnings, and1199log messages using the following methods:</p>1200<table class="docutils align-default">

Showing the first 1,200 of 3170 lines. Download the file for the rest.