study/uTools-Manuals
1
0
Fork 0
mirror of https://github.com/fofolee/uTools-Manuals.git synced 2025-06-08 23:14:06 +08:00
Code Issues Packages Projects Releases Wiki Activity
uTools-Manuals/docs/python/unittest.html
fofolee 38dcd51d8a v0.0.2
2019-04-21 11:50:48 +08:00

237 lines
246 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<div class="body" role="main"><div class="section" id="module-unittest"><h1><span class="yiyi-st" id="yiyi-10">26.4. <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> — 单元测试框架</span></h1><p><span class="yiyi-st" id="yiyi-11"><strong>Source code:</strong> <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/unittest/__init__.py">Lib/unittest/__init__.py</a></span></p><p><span class="yiyi-st" id="yiyi-12">（如果您已经熟悉测试的基本概念，你可能想要跳到 <a class="reference internal" href="#assert-methods"><span> assert 方法列表</span></a>。）</span></p><p><span class="yiyi-st" id="yiyi-13"><a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> 单元测试框架最初灵感来自 JUnit，和其他语言的主要单元测试框架有相似的风格。</span><span class="yiyi-st" id="yiyi-14">它支持自动化测试，共享设置和闭合代码测试，聚合测试，以及从报告框架上进行独立测试。</span></p><p><span class="yiyi-st" id="yiyi-15">要实现这一目标，<a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> 在面向对象方法上支持一些重要的概念︰</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-16">测试夹具</span></dt><dd><span class="yiyi-st" id="yiyi-17">一个<em class="dfn">测试夹具</em>表示执行一个或多个测试，以及任何相关清理操作所需的准备工作。</span><span class="yiyi-st" id="yiyi-18">例如，这可能涉及创建临时或代理数据库，目录或启动服务器进程。</span></dd><dt><span class="yiyi-st" id="yiyi-19">测试用例</span></dt><dd><span class="yiyi-st" id="yiyi-20"><em class="dfn">测试用例</em>是一个单独的测试单元。</span><span class="yiyi-st" id="yiyi-21">它检查对特定输入集的特定响应。</span><span class="yiyi-st" id="yiyi-22"><a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>提供了一个基类<a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>，用于创建新的测试用例。</span></dd><dt><span class="yiyi-st" id="yiyi-23">测试套件</span></dt><dd><span class="yiyi-st" id="yiyi-24"><em class="dfn">测试套件</em>是测试用例，测试套件或两者混合的一个集合。</span><span class="yiyi-st" id="yiyi-25">它用于聚合可以一块执行的测试。</span></dd><dt><span class="yiyi-st" id="yiyi-26">测试执行器</span></dt><dd><span class="yiyi-st" id="yiyi-27">A <em class="dfn">test runner</em> is a component which orchestrates the execution of tests and provides the outcome to the user. </span><span class="yiyi-st" id="yiyi-28">执行器可以使用图形接口，文本接口或返回特殊值来指示测试执行的结果。</span></dd></dl><div class="admonition seealso"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-29">See also</span></p><dl class="docutils"><dt><span class="yiyi-st" id="yiyi-30">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"><span class="pre">doctest</span></code></a></span></dt><dd><span class="yiyi-st" id="yiyi-31">Another test-support module with a very different flavor.</span></dd><dt><span class="yiyi-st" id="yiyi-32"><a class="reference external" href="https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm">Simple Smalltalk Testing: With Patterns</a></span></dt><dd><span class="yiyi-st" id="yiyi-33">Kent Beck’s original paper on testing frameworks using the pattern shared by <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>.</span></dd><dt><span class="yiyi-st" id="yiyi-34"><a class="reference external" href="https://nose.readthedocs.org/en/latest/">Nose</a>和<a class="reference external" href="http://pytest.org">py.test</a></span></dt><dd><span class="yiyi-st" id="yiyi-35">Third-party unittest frameworks with a lighter-weight syntax for writing tests. </span><span class="yiyi-st" id="yiyi-36">For example, <code class="docutils literal"><span class="pre">assert</span> <span class="pre">func(10)</span> <span class="pre">==</span> <span class="pre">42</span></code>.</span></dd><dt><span class="yiyi-st" id="yiyi-37"><a class="reference external" href="https://wiki.python.org/moin/PythonTestingToolsTaxonomy">The Python Testing Tools Taxonomy</a></span></dt><dd><span class="yiyi-st" id="yiyi-38">An extensive list of Python testing tools including functional testing frameworks and mock object libraries.</span></dd><dt><span class="yiyi-st" id="yiyi-39"><a class="reference external" href="http://lists.idyll.org/listinfo/testing-in-python">Testing in Python Mailing List</a></span></dt><dd><span class="yiyi-st" id="yiyi-40">A special-interest-group for discussion of testing, and testing tools, in Python.</span></dd></dl><p class="last"><span class="yiyi-st" id="yiyi-41">The script <code class="file docutils literal"><span class="pre">Tools/unittestgui/unittestgui.py</span></code> in the Python source distribution is a GUI tool for test discovery and execution. </span><span class="yiyi-st" id="yiyi-42">This is intended largely for ease of use for those new to unit testing. </span><span class="yiyi-st" id="yiyi-43">For production environments it is recommended that tests be driven by a continuous integration system such as <a class="reference external" href="https://buildbot.net/">Buildbot</a>, <a class="reference external" href="https://jenkins.io/">Jenkins</a> or <a class="reference external" href="http://hudson-ci.org/">Hudson</a>.</span></p></div><div class="section" id="basic-example"><h2><span class="yiyi-st" id="yiyi-44">26.4.1. </span><span class="yiyi-st" id="yiyi-45">Basic example</span></h2><p><span class="yiyi-st" id="yiyi-46">The <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> module provides a rich set of tools for constructing and running tests. </span><span class="yiyi-st" id="yiyi-47">This section demonstrates that a small subset of the tools suffice to meet the needs of most users.</span></p><p><span class="yiyi-st" id="yiyi-48">Here is a short script to test three string methods:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">unittest</span>
<span class="k">class</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>
<span class="k">def</span> <span class="nf">test_upper</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="s1">'foo'</span><span class="o">.</span><span class="n">upper</span><span class="p">(),</span> <span class="s1">'FOO'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_isupper</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertTrue</span><span class="p">(</span><span class="s1">'FOO'</span><span class="o">.</span><span class="n">isupper</span><span class="p">())</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertFalse</span><span class="p">(</span><span class="s1">'Foo'</span><span class="o">.</span><span class="n">isupper</span><span class="p">())</span>
<span class="k">def</span> <span class="nf">test_split</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">s</span> <span class="o">=</span> <span class="s1">'hello world'</span>
<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">'hello'</span><span class="p">,</span> <span class="s1">'world'</span><span class="p">])</span>
<span class="c1"># check that s.split fails when the separator is not a string</span>
<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>
<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>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>
<span class="n">unittest</span><span class="o">.</span><span class="n">main</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-49">通过继承<a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">unittest.TestCase</span></code></a>创建一个测试用例。</span><span class="yiyi-st" id="yiyi-50">三个单独的测试方法以字母<code class="docutils literal"><span class="pre">test</span></code>开头的名称定义。</span><span class="yiyi-st" id="yiyi-51">这个命名约定告诉我们测试执行类中哪些方法代表的是测试用例。</span></p><p><span class="yiyi-st" id="yiyi-52">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"><span class="pre">assertEqual()</span></code></a> to check for an expected result; <a class="reference internal" href="#unittest.TestCase.assertTrue" title="unittest.TestCase.assertTrue"><code class="xref py py-meth docutils literal"><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"><span class="pre">assertFalse()</span></code></a> to verify a condition; or <a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal"><span class="pre">assertRaises()</span></code></a> to verify that a specific exception gets raised. </span><span class="yiyi-st" id="yiyi-53">These methods are used instead of the <a class="reference internal" href="../reference/simple_stmts.html#assert"><code class="xref std std-keyword docutils literal"><span class="pre">assert</span></code></a> statement so the test runner can accumulate all test results and produce a report.</span></p><p><span class="yiyi-st" id="yiyi-54">The <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><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"><span class="pre">tearDown()</span></code></a> methods allow you to define instructions that will be executed before and after each test method. </span><span class="yiyi-st" id="yiyi-55">They are covered in more detail in the section <a class="reference internal" href="#organizing-tests"><span>Organizing test code</span></a>.</span></p><p><span class="yiyi-st" id="yiyi-56">The final block shows a simple way to run the tests. </span><span class="yiyi-st" id="yiyi-57"><a class="reference internal" href="#unittest.main" title="unittest.main"><code class="xref py py-func docutils literal"><span class="pre">unittest.main()</span></code></a> provides a command-line interface to the test script. </span><span class="yiyi-st" id="yiyi-58">When run from the command line, the above script produces an output that looks like this:</span></p><pre><code class="language-python"><span></span><span class="o">...</span>
<span class="o">----------------------------------------------------------------------</span>
<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>
<span class="n">OK</span>
</code></pre><p><span class="yiyi-st" id="yiyi-59">将<code class="docutils literal"><span class="pre">-v</span></code>选项传递到测试脚本将指示<a class="reference internal" href="#unittest.main" title="unittest.main"><code class="xref py py-func docutils literal"><span class="pre">unittest.main()</span></code></a>启用更高级别的详细信息，并产生以下输出：</span></p><pre><code class="language-python"><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="p">)</span> <span class="o">...</span> <span class="n">ok</span>
<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="p">)</span> <span class="o">...</span> <span class="n">ok</span>
<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="p">)</span> <span class="o">...</span> <span class="n">ok</span>
<span class="o">----------------------------------------------------------------------</span>
<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>
<span class="n">OK</span>
</code></pre><p><span class="yiyi-st" id="yiyi-60">The above examples show the most commonly used <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> features which are sufficient to meet many everyday testing needs. </span><span class="yiyi-st" id="yiyi-61">The remainder of the documentation explores the full feature set from first principles.</span></p></div><div class="section" id="command-line-interface"><h2><span class="yiyi-st" id="yiyi-62">26.4.2. </span><span class="yiyi-st" id="yiyi-63">Command-Line Interface</span></h2><p><span class="yiyi-st" id="yiyi-64">The unittest module can be used from the command line to run tests from modules, classes or even individual test methods:</span></p><pre><code class="language-python"><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>
<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="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>
</code></pre><p><span class="yiyi-st" id="yiyi-65">You can pass in a list with any combination of module names, and fully qualified class or method names.</span></p><p><span class="yiyi-st" id="yiyi-66">Test modules can be specified by file path as well:</span></p><pre><code class="language-python"><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>
</code></pre><p><span class="yiyi-st" id="yiyi-67">This allows you to use the shell filename completion to specify the test module. </span><span class="yiyi-st" id="yiyi-68">The file specified must still be importable as a module. </span><span class="yiyi-st" id="yiyi-69">通过删除'.py'和将路径分隔符转换为'.'，路径被转换为模块名称。</span><span class="yiyi-st" id="yiyi-70">If you want to execute a test file that isn’t importable as a module you should execute the file directly instead.</span></p><p><span class="yiyi-st" id="yiyi-71">You can run tests with more detail (higher verbosity) by passing in the -v flag:</span></p><pre><code class="language-python"><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>
</code></pre><p><span class="yiyi-st" id="yiyi-72">When executed without arguments <a class="reference internal" href="#unittest-test-discovery"><span>Test Discovery</span></a> is started:</span></p><pre><code class="language-python"><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">unittest</span>
</code></pre><p><span class="yiyi-st" id="yiyi-73">For a list of all the command-line options:</span></p><pre><code class="language-python"><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>
</code></pre><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-74"><span class="versionmodified">Changed in version 3.2: </span>In earlier versions it was only possible to run individual test methods and not modules or classes.</span></p></div><div class="section" id="command-line-options"><h3><span class="yiyi-st" id="yiyi-75">26.4.2.1. </span><span class="yiyi-st" id="yiyi-76">Command-line options</span></h3><p><span class="yiyi-st" id="yiyi-77"><strong class="program">unittest</strong> supports these command-line options:</span></p><dl class="cmdoption"><dt id="cmdoption-unittest-b"><span class="yiyi-st" id="yiyi-78"> <span id="cmdoption-unittest--buffer"></span><code class="descname">-b</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--buffer</code><code class="descclassname"></code></span></dt><dd><p><span class="yiyi-st" id="yiyi-79">The standard output and standard error streams are buffered during the test run. </span><span class="yiyi-st" id="yiyi-80">Output during a passing test is discarded. </span><span class="yiyi-st" id="yiyi-81">Output is echoed normally on test fail or error and is added to the failure messages.</span></p></dd></dl><dl class="cmdoption"><dt id="cmdoption-unittest-c"><span class="yiyi-st" id="yiyi-82"> <span id="cmdoption-unittest--catch"></span><code class="descname">-c</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--catch</code><code class="descclassname"></code></span></dt><dd><p><span class="yiyi-st" id="yiyi-83"><code class="kbd docutils literal"><span class="pre">Control-C</span></code> during the test run waits for the current test to end and then reports all the results so far. </span><span class="yiyi-st" id="yiyi-84">A second <code class="kbd docutils literal"><span class="pre">Control-C</span></code> raises the normal <a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal"><span class="pre">KeyboardInterrupt</span></code></a> exception.</span></p><p><span class="yiyi-st" id="yiyi-85">See <a class="reference internal" href="#signal-handling">Signal Handling</a> for the functions that provide this functionality.</span></p></dd></dl><dl class="cmdoption"><dt id="cmdoption-unittest-f"><span class="yiyi-st" id="yiyi-86"> <span id="cmdoption-unittest--failfast"></span><code class="descname">-f</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--failfast</code><code class="descclassname"></code></span></dt><dd><p><span class="yiyi-st" id="yiyi-87">Stop the test run on the first error or failure.</span></p></dd></dl><dl class="cmdoption"><dt id="cmdoption-unittest--locals"><span class="yiyi-st" id="yiyi-88"> <code class="descname">--locals</code><code class="descclassname"></code></span></dt><dd><p><span class="yiyi-st" id="yiyi-89">Show local variables in tracebacks.</span></p></dd></dl><div class="versionadded"><p><span class="yiyi-st" id="yiyi-90"><span class="versionmodified">New in version 3.2: </span>The command-line options <code class="docutils literal"><span class="pre">-b</span></code>, <code class="docutils literal"><span class="pre">-c</span></code> and <code class="docutils literal"><span class="pre">-f</span></code> were added.</span></p></div><div class="versionadded"><p><span class="yiyi-st" id="yiyi-91"><span class="versionmodified">New in version 3.5: </span>The command-line option <code class="docutils literal"><span class="pre">--locals</span></code>.</span></p></div><p><span class="yiyi-st" id="yiyi-92">The command line can also be used for test discovery, for running all of the tests in a project or just a subset.</span></p></div></div><div class="section" id="test-discovery"><h2><span class="yiyi-st" id="yiyi-93">26.4.3. </span><span class="yiyi-st" id="yiyi-94">Test Discovery</span></h2><div class="versionadded"><p><span class="yiyi-st" id="yiyi-95"><span class="versionmodified">New in version 3.2.</span></span></p></div><p><span class="yiyi-st" id="yiyi-96">Unittest supports simple test discovery. </span><span class="yiyi-st" id="yiyi-97">In order to be compatible with test discovery, all of the test files must be <a class="reference internal" href="../tutorial/modules.html#tut-modules"><span>modules</span></a> or <a class="reference internal" href="../tutorial/modules.html#tut-packages"><span>packages</span></a> (including <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace packages</span></a>) importable from the top-level directory of the project (this means that their filenames must be valid <a class="reference internal" href="../reference/lexical_analysis.html#identifiers"><span>identifiers</span></a>).</span></p><p><span class="yiyi-st" id="yiyi-98">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"><span class="pre">TestLoader.discover()</span></code></a>, but can also be used from the command line. </span><span class="yiyi-st" id="yiyi-99">The basic command-line usage is:</span></p><pre><code class="language-python"><span></span><span class="n">cd</span> <span class="n">project_directory</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>
</code></pre><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-100">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-101">As a shortcut, <code class="docutils literal"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">unittest</span></code> is the equivalent of <code class="docutils literal"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">unittest</span> <span class="pre">discover</span></code>. </span><span class="yiyi-st" id="yiyi-102">If you want to pass arguments to test discovery the <code class="docutils literal"><span class="pre">discover</span></code> sub-command must be used explicitly.</span></p></div><p><span class="yiyi-st" id="yiyi-103">The <code class="docutils literal"><span class="pre">discover</span></code> sub-command has the following options:</span></p><dl class="cmdoption"><dt id="cmdoption-unittest-discover-v"><span class="yiyi-st" id="yiyi-104"> <span id="cmdoption-unittest-discover--verbose"></span><code class="descname">-v</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--verbose</code><code class="descclassname"></code></span></dt><dd><p><span class="yiyi-st" id="yiyi-105">Verbose output</span></p></dd></dl><dl class="cmdoption"><dt id="cmdoption-unittest-discover-s"><span class="yiyi-st" id="yiyi-106"> <span id="cmdoption-unittest-discover--start-directory"></span><code class="descname">-s</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--start-directory</code><code class="descclassname"> directory</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-107">Directory to start discovery (<code class="docutils literal"><span class="pre">.</span></code></span><span class="yiyi-st" id="yiyi-108"> default)</span></p></dd></dl><dl class="cmdoption"><dt id="cmdoption-unittest-discover-p"><span class="yiyi-st" id="yiyi-109"> <span id="cmdoption-unittest-discover--pattern"></span><code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--pattern</code><code class="descclassname"> pattern</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-110">Pattern to match test files (<code class="docutils literal"><span class="pre">test*.py</span></code> default)</span></p></dd></dl><dl class="cmdoption"><dt id="cmdoption-unittest-discover-t"><span class="yiyi-st" id="yiyi-111"> <span id="cmdoption-unittest-discover--top-level-directory"></span><code class="descname">-t</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--top-level-directory</code><code class="descclassname"> directory</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-112">Top level directory of project (defaults to start directory)</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-113">The <a class="reference internal" href="#cmdoption-unittest-discover-s"><code class="xref std std-option docutils literal"><span class="pre">-s</span></code></a>, <a class="reference internal" href="#cmdoption-unittest-discover-p"><code class="xref std std-option docutils literal"><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"><span class="pre">-t</span></code></a> options can be passed in as positional arguments in that order. </span><span class="yiyi-st" id="yiyi-114">The following two command lines are equivalent:</span></p><pre><code class="language-python"><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">"*_test.py"</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="n">project_directory</span> <span class="s2">"*_test.py"</span>
</code></pre><p><span class="yiyi-st" id="yiyi-115">As well as being a path it is possible to pass a package name, for example <code class="docutils literal"><span class="pre">myproject.subpackage.test</span></code>, as the start directory. </span><span class="yiyi-st" id="yiyi-116">The package name you supply will then be imported and its location on the filesystem will be used as the start directory.</span></p><div class="admonition caution"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-117">Caution</span></p><p><span class="yiyi-st" id="yiyi-118">Test discovery loads tests by importing them. </span><span class="yiyi-st" id="yiyi-119">Once test discovery has found all the test files from the start directory you specify it turns the paths into package names to import. </span><span class="yiyi-st" id="yiyi-120">For example <code class="file docutils literal"><span class="pre">foo/bar/baz.py</span></code> will be imported as <code class="docutils literal"><span class="pre">foo.bar.baz</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-121">If you have a package installed globally and attempt test discovery on a different copy of the package then the import <em>could</em> happen from the wrong place. </span><span class="yiyi-st" id="yiyi-122">If this happens test discovery will warn you and exit.</span></p><p class="last"><span class="yiyi-st" id="yiyi-123">If you supply the start directory as a package name rather than a path to a directory then discover assumes that whichever location it imports from is the location you intended, so you will not get the warning.</span></p></div><p><span class="yiyi-st" id="yiyi-124">Test modules and packages can customize test loading and discovery by through the <a class="reference internal" href="#load-tests-protocol">load_tests protocol</a>.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-125"><span class="versionmodified">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>.</span></p></div></div><div class="section" id="organizing-test-code"><h2><span class="yiyi-st" id="yiyi-126">26.4.4. </span><span class="yiyi-st" id="yiyi-127">Organizing test code</span></h2><p><span class="yiyi-st" id="yiyi-128">The basic building blocks of unit testing are <em class="dfn">test cases</em> — single scenarios that must be set up and checked for correctness. </span><span class="yiyi-st" id="yiyi-129">In <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>, test cases are represented by <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">unittest.TestCase</span></code></a> instances. </span><span class="yiyi-st" id="yiyi-130">To make your own test cases you must write subclasses of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><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"><span class="pre">FunctionTestCase</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-131">The testing code of a <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instance should be entirely self contained, such that it can be run either in isolation or in arbitrary combination with any number of other test cases.</span></p><p><span class="yiyi-st" id="yiyi-132">The simplest <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> subclass will simply implement a test method (i.e. </span><span class="yiyi-st" id="yiyi-133">a method whose name starts with <code class="docutils literal"><span class="pre">test</span></code>) in order to perform specific testing code:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">unittest</span>
<span class="k">class</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>
<span class="k">def</span> <span class="nf">test_default_widget_size</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">widget</span> <span class="o">=</span> <span class="n">Widget</span><span class="p">(</span><span class="s1">'The widget'</span><span class="p">)</span>
<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>
</code></pre><p><span class="yiyi-st" id="yiyi-134">Note that in order to test something, we use one of the <code class="xref py py-meth docutils literal"><span class="pre">assert*()</span></code> methods provided by the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> base class. </span><span class="yiyi-st" id="yiyi-135">If the test fails, an exception will be raised, and <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> will identify the test case as a <em class="dfn">failure</em>. </span><span class="yiyi-st" id="yiyi-136">Any other exceptions will be treated as <em class="dfn">errors</em>.</span></p><p><span class="yiyi-st" id="yiyi-137">Tests can be numerous, and their set-up can be repetitive. </span><span class="yiyi-st" id="yiyi-138">Luckily, we can factor out set-up code by implementing a method called <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><span class="pre">setUp()</span></code></a>, which the testing framework will automatically call for every single test we run:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">unittest</span>
<span class="k">class</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>
<span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</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">Widget</span><span class="p">(</span><span class="s1">'The widget'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_default_widget_size</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<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>
<span class="s1">'incorrect default size'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_widget_resize</span><span class="p">(</span><span class="bp">self</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">resize</span><span class="p">(</span><span class="mi">100</span><span class="p">,</span><span class="mi">150</span><span class="p">)</span>
<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>
<span class="s1">'wrong size after resize'</span><span class="p">)</span>
</code></pre><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-139">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-140">The order in which the various tests will be run is determined by sorting the test method names with respect to the built-in ordering for strings.</span></p></div><p><span class="yiyi-st" id="yiyi-141">If the <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><span class="pre">setUp()</span></code></a> method raises an exception while the test is running, the framework will consider the test to have suffered an error, and the test method will not be executed.</span></p><p><span class="yiyi-st" id="yiyi-142">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"><span class="pre">tearDown()</span></code></a> method that tidies up after the test method has been run:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">unittest</span>
<span class="k">class</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>
<span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</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">Widget</span><span class="p">(</span><span class="s1">'The widget'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</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">dispose</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-143">If <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><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"><span class="pre">tearDown()</span></code></a> will be run whether the test method succeeded or not.</span></p><p><span class="yiyi-st" id="yiyi-144">Such a working environment for the testing code is called a <em class="dfn">fixture</em>.</span></p><p><span class="yiyi-st" id="yiyi-145">Test case instances are grouped together according to the features they test. </span><span class="yiyi-st" id="yiyi-146"><a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> provides a mechanism for this: the <em class="dfn">test suite</em>, represented by <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>‘s <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> class. </span><span class="yiyi-st" id="yiyi-147">In most cases, calling <a class="reference internal" href="#unittest.main" title="unittest.main"><code class="xref py py-func docutils literal"><span class="pre">unittest.main()</span></code></a> will do the right thing and collect all the module’s test cases for you, and then execute them.</span></p><p><span class="yiyi-st" id="yiyi-148">However, should you want to customize the building of your test suite, you can do it yourself:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">suite</span><span class="p">():</span>
<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>
<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">'test_default_size'</span><span class="p">))</span>
<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">'test_resize'</span><span class="p">))</span>
<span class="k">return</span> <span class="n">suite</span>
</code></pre><p><span class="yiyi-st" id="yiyi-149">You can place the definitions of test cases and test suites in the same modules as the code they are to test (such as <code class="file docutils literal"><span class="pre">widget.py</span></code>), but there are several advantages to placing the test code in a separate module, such as <code class="file docutils literal"><span class="pre">test_widget.py</span></code>:</span></p><ul class="simple"><li><span class="yiyi-st" id="yiyi-150">The test module can be run standalone from the command line.</span></li><li><span class="yiyi-st" id="yiyi-151">The test code can more easily be separated from shipped code.</span></li><li><span class="yiyi-st" id="yiyi-152">There is less temptation to change test code to fit the code it tests without a good reason.</span></li><li><span class="yiyi-st" id="yiyi-153">Test code should be modified much less frequently than the code it tests.</span></li><li><span class="yiyi-st" id="yiyi-154">Tested code can be refactored more easily.</span></li><li><span class="yiyi-st" id="yiyi-155">Tests for modules written in C must be in separate modules anyway, so why not be consistent?</span></li><li><span class="yiyi-st" id="yiyi-156">If the testing strategy changes, there is no need to change the source code.</span></li></ul></div><div class="section" id="re-using-old-test-code"><h2><span class="yiyi-st" id="yiyi-157">26.4.5. </span><span class="yiyi-st" id="yiyi-158">Re-using old test code</span></h2><p><span class="yiyi-st" id="yiyi-159">Some users will find that they have existing test code that they would like to run from <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>, without converting every old test function to a <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> subclass.</span></p><p><span class="yiyi-st" id="yiyi-160">For this reason, <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> provides a <a class="reference internal" href="#unittest.FunctionTestCase" title="unittest.FunctionTestCase"><code class="xref py py-class docutils literal"><span class="pre">FunctionTestCase</span></code></a> class. </span><span class="yiyi-st" id="yiyi-161">This subclass of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> can be used to wrap an existing test function. </span><span class="yiyi-st" id="yiyi-162">Set-up and tear-down functions can also be provided.</span></p><p><span class="yiyi-st" id="yiyi-163">Given the following test function:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">testSomething</span><span class="p">():</span>
<span class="n">something</span> <span class="o">=</span> <span class="n">makeSomething</span><span class="p">()</span>
<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>
<span class="c1"># ...</span>
</code></pre><p><span class="yiyi-st" id="yiyi-164">one can create an equivalent test case instance as follows, with optional set-up and tear-down methods:</span></p><pre><code class="language-python"><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>
<span class="n">setUp</span><span class="o">=</span><span class="n">makeSomethingDB</span><span class="p">,</span>
<span class="n">tearDown</span><span class="o">=</span><span class="n">deleteSomethingDB</span><span class="p">)</span>
</code></pre><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-165">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-166">Even though <a class="reference internal" href="#unittest.FunctionTestCase" title="unittest.FunctionTestCase"><code class="xref py py-class docutils literal"><span class="pre">FunctionTestCase</span></code></a> can be used to quickly convert an existing test base over to a <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>-based system, this approach is not recommended. </span><span class="yiyi-st" id="yiyi-167">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"><span class="pre">TestCase</span></code></a> subclasses will make future test refactorings infinitely easier.</span></p></div><p><span class="yiyi-st" id="yiyi-168">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"><span class="pre">doctest</span></code></a> module. </span><span class="yiyi-st" id="yiyi-169">If so, <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"><span class="pre">doctest</span></code></a> provides a <code class="xref py py-class docutils literal"><span class="pre">DocTestSuite</span></code> class that can automatically build <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">unittest.TestSuite</span></code></a> instances from the existing <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"><span class="pre">doctest</span></code></a>-based tests.</span></p></div><div class="section" id="skipping-tests-and-expected-failures"><h2><span class="yiyi-st" id="yiyi-170">26.4.6. </span><span class="yiyi-st" id="yiyi-171">Skipping tests and expected failures</span></h2><div class="versionadded"><p><span class="yiyi-st" id="yiyi-172"><span class="versionmodified">New in version 3.1.</span></span></p></div><p><span class="yiyi-st" id="yiyi-173">Unittest supports skipping individual test methods and even whole classes of tests. </span><span class="yiyi-st" id="yiyi-174">In addition, it supports marking a test as an “expected failure,” a test that is broken and will fail, but shouldn’t be counted as a failure on a <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-175">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"><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> or one of its conditional variants.</span></p><p><span class="yiyi-st" id="yiyi-176">Basic skipping looks like this:</span></p><pre><code class="language-python"><span></span><span class="k">class</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>
<span class="nd">@unittest</span><span class="o">.</span><span class="n">skip</span><span class="p">(</span><span class="s2">"demonstrating skipping"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_nothing</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">fail</span><span class="p">(</span><span class="s2">"shouldn't happen"</span><span class="p">)</span>
<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>
<span class="s2">"not supported in this library version"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_format</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># Tests that work for only a certain version of the library.</span>
<span class="k">pass</span>
<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">"win"</span><span class="p">),</span> <span class="s2">"requires Windows"</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">test_windows_support</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="c1"># windows specific testing code</span>
<span class="k">pass</span>
</code></pre><p><span class="yiyi-st" id="yiyi-177">This is the output of running the example above in verbose mode:</span></p><pre><code class="language-python"><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="p">)</span> <span class="o">...</span> <span class="n">skipped</span> <span class="s1">'not supported in this library version'</span>
<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="p">)</span> <span class="o">...</span> <span class="n">skipped</span> <span class="s1">'demonstrating skipping'</span>
<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="p">)</span> <span class="o">...</span> <span class="n">skipped</span> <span class="s1">'requires Windows'</span>
<span class="o">----------------------------------------------------------------------</span>
<span class="n">Ran</span> <span class="mi">3</span> <span class="n">tests</span> <span class="ow">in</span> <span class="mf">0.005</span><span class="n">s</span>
<span class="n">OK</span> <span class="p">(</span><span class="n">skipped</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-178">Classes can be skipped just like methods:</span></p><pre><code class="language-python"><span></span><span class="nd">@unittest</span><span class="o">.</span><span class="n">skip</span><span class="p">(</span><span class="s2">"showing class skipping"</span><span class="p">)</span>
<span class="k">class</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>
<span class="k">def</span> <span class="nf">test_not_run</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="k">pass</span>
</code></pre><p><span class="yiyi-st" id="yiyi-179"><a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><span class="pre">TestCase.setUp()</span></code></a> can also skip the test. </span><span class="yiyi-st" id="yiyi-180">This is useful when a resource that needs to be set up is not available.</span></p><p><span class="yiyi-st" id="yiyi-181">Expected failures use the <a class="reference internal" href="#unittest.expectedFailure" title="unittest.expectedFailure"><code class="xref py py-func docutils literal"><span class="pre">expectedFailure()</span></code></a> decorator.</span></p><pre><code class="language-python"><span></span><span class="k">class</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>
<span class="nd">@unittest</span><span class="o">.</span><span class="n">expectedFailure</span>
<span class="k">def</span> <span class="nf">test_fail</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<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">"broken"</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-182">It’s easy to roll your own skipping decorators by making a decorator that calls <a class="reference internal" href="#unittest.skip" title="unittest.skip"><code class="xref py py-func docutils literal"><span class="pre">skip()</span></code></a> on the test when it wants it to be skipped. </span><span class="yiyi-st" id="yiyi-183">This decorator skips the test unless the passed object has a certain attribute:</span></p><pre><code class="language-python"><span></span><span class="k">def</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>
<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>
<span class="k">return</span> <span class="k">lambda</span> <span class="n">func</span><span class="p">:</span> <span class="n">func</span>
<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">"</span><span class="si">{!r}</span><span class="s2"> doesn't have </span><span class="si">{!r}</span><span class="s2">"</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>
</code></pre><p><span class="yiyi-st" id="yiyi-184">The following decorators implement test skipping and expected failures:</span></p><dl class="function"><dt id="unittest.skip"><span class="yiyi-st" id="yiyi-185"> <code class="descclassname">@</code><code class="descclassname">unittest.</code><code class="descname">skip</code><span class="sig-paren">(</span><em>reason</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-186">Unconditionally skip the decorated test. </span><span class="yiyi-st" id="yiyi-187"><em>reason</em> should describe why the test is being skipped.</span></p></dd></dl><dl class="function"><dt id="unittest.skipIf"><span class="yiyi-st" id="yiyi-188"> <code class="descclassname">@</code><code class="descclassname">unittest.</code><code class="descname">skipIf</code><span class="sig-paren">(</span><em>condition</em>, <em>reason</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-189">Skip the decorated test if <em>condition</em> is true.</span></p></dd></dl><dl class="function"><dt id="unittest.skipUnless"><span class="yiyi-st" id="yiyi-190"> <code class="descclassname">@</code><code class="descclassname">unittest.</code><code class="descname">skipUnless</code><span class="sig-paren">(</span><em>condition</em>, <em>reason</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-191">Skip the decorated test unless <em>condition</em> is true.</span></p></dd></dl><dl class="function"><dt id="unittest.expectedFailure"><span class="yiyi-st" id="yiyi-192"> <code class="descclassname">@</code><code class="descclassname">unittest.</code><code class="descname">expectedFailure</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-193">Mark the test as an expected failure. </span><span class="yiyi-st" id="yiyi-194">If the test fails when run, the test is not counted as a failure.</span></p></dd></dl><dl class="exception"><dt id="unittest.SkipTest"><span class="yiyi-st" id="yiyi-195"> <em class="property">exception </em><code class="descclassname">unittest.</code><code class="descname">SkipTest</code><span class="sig-paren">(</span><em>reason</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-196">This exception is raised to skip a test.</span></p><p><span class="yiyi-st" id="yiyi-197">Usually you can use <a class="reference internal" href="#unittest.TestCase.skipTest" title="unittest.TestCase.skipTest"><code class="xref py py-meth docutils literal"><span class="pre">TestCase.skipTest()</span></code></a> or one of the skipping decorators instead of raising this directly.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-198">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"><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"><span class="pre">tearDown()</span></code></a> run around them. </span><span class="yiyi-st" id="yiyi-199">Skipped classes will not have <a class="reference internal" href="#unittest.TestCase.setUpClass" title="unittest.TestCase.setUpClass"><code class="xref py py-meth docutils literal"><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"><span class="pre">tearDownClass()</span></code></a> run. </span><span class="yiyi-st" id="yiyi-200">Skipped modules will not have <code class="xref py py-func docutils literal"><span class="pre">setUpModule()</span></code> or <code class="xref py py-func docutils literal"><span class="pre">tearDownModule()</span></code> run.</span></p></div><div class="section" id="distinguishing-test-iterations-using-subtests"><h2><span class="yiyi-st" id="yiyi-201">26.4.7. </span><span class="yiyi-st" id="yiyi-202">Distinguishing test iterations using subtests</span></h2><div class="versionadded"><p><span class="yiyi-st" id="yiyi-203"><span class="versionmodified">New in version 3.4.</span></span></p></div><p><span class="yiyi-st" id="yiyi-204">When some of your tests differ only by a some very small differences, for instance some parameters, unittest allows you to distinguish them inside the 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"><span class="pre">subTest()</span></code></a> context manager.</span></p><p><span class="yiyi-st" id="yiyi-205">For example, the following test:</span></p><pre><code class="language-python"><span></span><span class="k">class</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>
<span class="k">def</span> <span class="nf">test_even</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Test that numbers between 0 and 5 are all even.</span>
<span class="sd"> """</span>
<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>
<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>
<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>
</code></pre><p><span class="yiyi-st" id="yiyi-206">will produce the following output:</span></p><pre><code class="language-python"><span></span><span class="o">======================================================================</span>
<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="p">)</span> <span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="o">----------------------------------------------------------------------</span>
<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>
<span class="n">File</span> <span class="s2">"subtests.py"</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>
<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>
<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>
<span class="o">======================================================================</span>
<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="p">)</span> <span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
<span class="o">----------------------------------------------------------------------</span>
<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>
<span class="n">File</span> <span class="s2">"subtests.py"</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>
<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>
<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>
<span class="o">======================================================================</span>
<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="p">)</span> <span class="p">(</span><span class="n">i</span><span class="o">=</span><span class="mi">5</span><span class="p">)</span>
<span class="o">----------------------------------------------------------------------</span>
<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>
<span class="n">File</span> <span class="s2">"subtests.py"</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>
<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>
<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>
</code></pre><p><span class="yiyi-st" id="yiyi-207">Without using a subtest, execution would stop after the first failure, and the error would be less easy to diagnose because the value of <code class="docutils literal"><span class="pre">i</span></code> wouldn’t be displayed:</span></p><pre><code class="language-python"><span></span><span class="o">======================================================================</span>
<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="p">)</span>
<span class="o">----------------------------------------------------------------------</span>
<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>
<span class="n">File</span> <span class="s2">"subtests.py"</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>
<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>
<span class="ne">AssertionError</span><span class="p">:</span> <span class="mi">1</span> <span class="o">!=</span> <span class="mi">0</span>
</code></pre></div><div class="section" id="classes-and-functions"><h2><span class="yiyi-st" id="yiyi-208">26.4.8. </span><span class="yiyi-st" id="yiyi-209">Classes and functions</span></h2><p><span class="yiyi-st" id="yiyi-210">This section describes in depth the API of <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>.</span></p><div class="section" id="test-cases"><h3><span class="yiyi-st" id="yiyi-211">26.4.8.1. </span><span class="yiyi-st" id="yiyi-212">Test cases</span></h3><dl class="class"><dt id="unittest.TestCase"><span class="yiyi-st" id="yiyi-213"> <em class="property">class </em><code class="descclassname">unittest.</code><code class="descname">TestCase</code><span class="sig-paren">(</span><em>methodName='runTest'</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-214">Instances of the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> class represent the logical test units in the <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> universe. </span><span class="yiyi-st" id="yiyi-215">This class is intended to be used as a base class, with specific tests being implemented by concrete subclasses. </span><span class="yiyi-st" id="yiyi-216">This class implements the interface needed by the test runner to allow it to drive the tests, and methods that the test code can use to check for and report various kinds of failure.</span></p><p><span class="yiyi-st" id="yiyi-217">Each instance of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> will run a single base method: the method named <em>methodName</em>. </span><span class="yiyi-st" id="yiyi-218">In most uses of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>, you will neither change the <em>methodName</em> nor reimplement the default <code class="docutils literal"><span class="pre">runTest()</span></code> method.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-219"><span class="versionmodified">Changed in version 3.2: </span><a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> can be instantiated successfully without providing a <em>methodName</em>. </span><span class="yiyi-st" id="yiyi-220">This makes it easier to experiment with <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> from the interactive interpreter.</span></p></div><p><span class="yiyi-st" id="yiyi-221"><a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances provide three groups of methods: one group used to run the test, another used by the test implementation to check conditions and report failures, and some inquiry methods allowing information about the test itself to be gathered.</span></p><p><span class="yiyi-st" id="yiyi-222">Methods in the first group (running the test) are:</span></p><dl class="method"><dt id="unittest.TestCase.setUp"><span class="yiyi-st" id="yiyi-223"> <code class="descname">setUp</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-224">Method called to prepare the test fixture. </span><span class="yiyi-st" id="yiyi-225">This is called immediately before calling the test method; other than <a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal"><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"><span class="pre">SkipTest</span></code></a>, any exception raised by this method will be considered an error rather than a test failure. </span><span class="yiyi-st" id="yiyi-226">The default implementation does nothing.</span></p></dd></dl><dl class="method"><dt id="unittest.TestCase.tearDown"><span class="yiyi-st" id="yiyi-227"> <code class="descname">tearDown</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-228">Method called immediately after the test method has been called and the result recorded. </span><span class="yiyi-st" id="yiyi-229">This is called even if the test method raised an exception, so the implementation in subclasses may need to be particularly careful about checking internal state. </span><span class="yiyi-st" id="yiyi-230">Any exception, other than <a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal"><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"><span class="pre">SkipTest</span></code></a>, raised by this method will be considered an additional error rather than a test failure (thus increasing the total number of reported errors). </span><span class="yiyi-st" id="yiyi-231">This method will only be called if the <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><span class="pre">setUp()</span></code></a> succeeds, regardless of the outcome of the test method. </span><span class="yiyi-st" id="yiyi-232">The default implementation does nothing.</span></p></dd></dl><dl class="method"><dt id="unittest.TestCase.setUpClass"><span class="yiyi-st" id="yiyi-233"> <code class="descname">setUpClass</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-234">A class method called before tests in an individual class run. </span><span class="yiyi-st" id="yiyi-235"><code class="docutils literal"><span class="pre">setUpClass</span></code> is called with the class as the only argument and must be decorated as a <a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-func docutils literal"><span class="pre">classmethod()</span></code></a>:</span></p><pre><code class="language-python"><span></span><span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">setUpClass</span><span class="p">(</span><span class="n">cls</span><span class="p">):</span>
<span class="o">...</span>
</code></pre><p><span class="yiyi-st" id="yiyi-236">See <a class="reference internal" href="#class-and-module-fixtures">Class and Module Fixtures</a> for more details.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-237"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.tearDownClass"><span class="yiyi-st" id="yiyi-238"> <code class="descname">tearDownClass</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-239">A class method called after tests in an individual class have run. </span><span class="yiyi-st" id="yiyi-240"><code class="docutils literal"><span class="pre">tearDownClass</span></code> is called with the class as the only argument and must be decorated as a <a class="reference internal" href="functions.html#classmethod" title="classmethod"><code class="xref py py-meth docutils literal"><span class="pre">classmethod()</span></code></a>:</span></p><pre><code class="language-python"><span></span><span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">tearDownClass</span><span class="p">(</span><span class="n">cls</span><span class="p">):</span>
<span class="o">...</span>
</code></pre><p><span class="yiyi-st" id="yiyi-241">See <a class="reference internal" href="#class-and-module-fixtures">Class and Module Fixtures</a> for more details.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-242"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.run"><span class="yiyi-st" id="yiyi-243"> <code class="descname">run</code><span class="sig-paren">(</span><em>result=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-244">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"><span class="pre">TestResult</span></code></a> object passed as <em>result</em>. </span><span class="yiyi-st" id="yiyi-245">If <em>result</em> is omitted or <code class="docutils literal"><span class="pre">None</span></code>, a temporary result 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"><span class="pre">defaultTestResult()</span></code></a> method) and used. </span><span class="yiyi-st" id="yiyi-246">The result object is returned to <a class="reference internal" href="#unittest.TestCase.run" title="unittest.TestCase.run"><code class="xref py py-meth docutils literal"><span class="pre">run()</span></code></a>‘s caller.</span></p><p><span class="yiyi-st" id="yiyi-247">The same effect may be had by simply calling the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instance.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-248"><span class="versionmodified">Changed in version 3.3: </span>Previous versions of <code class="docutils literal"><span class="pre">run</span></code> did not return the result. </span><span class="yiyi-st" id="yiyi-249">Neither did calling an instance.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.skipTest"><span class="yiyi-st" id="yiyi-250"> <code class="descname">skipTest</code><span class="sig-paren">(</span><em>reason</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-251">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"><span class="pre">setUp()</span></code></a> skips the current test. </span><span class="yiyi-st" id="yiyi-252">See <a class="reference internal" href="#unittest-skipping"><span>Skipping tests and expected failures</span></a> for more information.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-253"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.subTest"><span class="yiyi-st" id="yiyi-254"> <code class="descname">subTest</code><span class="sig-paren">(</span><em>msg=None</em>, <em>**params</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-255">Return a context manager which executes the enclosed code block as a subtest. </span><span class="yiyi-st" id="yiyi-256"><em>msg</em> and <em>params</em> are optional, arbitrary values which are displayed whenever a subtest fails, allowing you to identify them clearly.</span></p><p><span class="yiyi-st" id="yiyi-257">A test case can contain any number of subtest declarations, and they can be arbitrarily nested.</span></p><p><span class="yiyi-st" id="yiyi-258">See <a class="reference internal" href="#subtests"><span>Distinguishing test iterations using subtests</span></a> for more information.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-259"><span class="versionmodified">New in version 3.4.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.debug"><span class="yiyi-st" id="yiyi-260"> <code class="descname">debug</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-261">Run the test without collecting the result. </span><span class="yiyi-st" id="yiyi-262">This allows exceptions raised by the test to be propagated to the caller, and can be used to support running tests under a debugger.</span></p></dd></dl><p id="assert-methods"><span class="yiyi-st" id="yiyi-263">The <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> class provides several assert methods to check for and report failures. </span><span class="yiyi-st" id="yiyi-264">The following table lists the most commonly used methods (see the tables below for more assert methods):</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-265">Method</span></th><th class="head"><span class="yiyi-st" id="yiyi-266">Checks that</span></th><th class="head"><span class="yiyi-st" id="yiyi-267">New in</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-268"><a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-269"><code class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></code></span></td><td></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-270"><a class="reference internal" href="#unittest.TestCase.assertNotEqual" title="unittest.TestCase.assertNotEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertNotEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-271"><code class="docutils literal"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></code></span></td><td></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-272"><a class="reference internal" href="#unittest.TestCase.assertTrue" title="unittest.TestCase.assertTrue"><code class="xref py py-meth docutils literal"><span class="pre">assertTrue(x)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-273"><code class="docutils literal"><span class="pre">bool(x)</span> <span class="pre">is</span> <span class="pre">True</span></code></span></td><td></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-274"><a class="reference internal" href="#unittest.TestCase.assertFalse" title="unittest.TestCase.assertFalse"><code class="xref py py-meth docutils literal"><span class="pre">assertFalse(x)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-275"><code class="docutils literal"><span class="pre">bool(x)</span> <span class="pre">is</span> <span class="pre">False</span></code></span></td><td></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-276"><a class="reference internal" href="#unittest.TestCase.assertIs" title="unittest.TestCase.assertIs"><code class="xref py py-meth docutils literal"><span class="pre">assertIs(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-277"><code class="docutils literal"><span class="pre">a</span> <span class="pre">is</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-278">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-279"><a class="reference internal" href="#unittest.TestCase.assertIsNot" title="unittest.TestCase.assertIsNot"><code class="xref py py-meth docutils literal"><span class="pre">assertIsNot(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-280"><code class="docutils literal"><span class="pre">a</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-281">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-282"><a class="reference internal" href="#unittest.TestCase.assertIsNone" title="unittest.TestCase.assertIsNone"><code class="xref py py-meth docutils literal"><span class="pre">assertIsNone(x)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-283"><code class="docutils literal"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">None</span></code></span></td><td><span class="yiyi-st" id="yiyi-284">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-285"><a class="reference internal" href="#unittest.TestCase.assertIsNotNone" title="unittest.TestCase.assertIsNotNone"><code class="xref py py-meth docutils literal"><span class="pre">assertIsNotNone(x)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-286"><code class="docutils literal"><span class="pre">x</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">None</span></code></span></td><td><span class="yiyi-st" id="yiyi-287">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-288"><a class="reference internal" href="#unittest.TestCase.assertIn" title="unittest.TestCase.assertIn"><code class="xref py py-meth docutils literal"><span class="pre">assertIn(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-289"><code class="docutils literal"><span class="pre">a</span> <span class="pre">in</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-290">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-291"><a class="reference internal" href="#unittest.TestCase.assertNotIn" title="unittest.TestCase.assertNotIn"><code class="xref py py-meth docutils literal"><span class="pre">assertNotIn(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-292"><code class="docutils literal"><span class="pre">a</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-293">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-294"><a class="reference internal" href="#unittest.TestCase.assertIsInstance" title="unittest.TestCase.assertIsInstance"><code class="xref py py-meth docutils literal"><span class="pre">assertIsInstance(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-295"><code class="docutils literal"><span class="pre">isinstance(a,</span> <span class="pre">b)</span></code></span></td><td><span class="yiyi-st" id="yiyi-296">3.2</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-297"><a class="reference internal" href="#unittest.TestCase.assertNotIsInstance" title="unittest.TestCase.assertNotIsInstance"><code class="xref py py-meth docutils literal"><span class="pre">assertNotIsInstance(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-298"><code class="docutils literal"><span class="pre">not</span> <span class="pre">isinstance(a,</span> <span class="pre">b)</span></code></span></td><td><span class="yiyi-st" id="yiyi-299">3.2</span></td></tr></tbody></table><p><span class="yiyi-st" id="yiyi-300">All the assert methods accept a <em>msg</em> argument that, if specified, is used as 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"><span class="pre">longMessage</span></code></a>). </span><span class="yiyi-st" id="yiyi-301">Note 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"><span class="pre">assertRaises()</span></code></a>, <a class="reference internal" href="#unittest.TestCase.assertRaisesRegex" title="unittest.TestCase.assertRaisesRegex"><code class="xref py py-meth docutils literal"><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"><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"><span class="pre">assertWarnsRegex()</span></code></a> only when they are used as a context manager.</span></p><dl class="method"><dt id="unittest.TestCase.assertEqual"><span class="yiyi-st" id="yiyi-302"> <code class="descname">assertEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-303">测试<em>第一</em>和<em>第二</em>是否相等。</span><span class="yiyi-st" id="yiyi-304">If the values do not compare equal, the test will fail.</span></p><p><span class="yiyi-st" id="yiyi-305">In addition, if <em>first</em> and <em>second</em> are the exact same type and one of list, tuple, dict, set, frozenset or str or any type that a subclass registers with <a class="reference internal" href="#unittest.TestCase.addTypeEqualityFunc" title="unittest.TestCase.addTypeEqualityFunc"><code class="xref py py-meth docutils literal"><span class="pre">addTypeEqualityFunc()</span></code></a> the type-specific equality function will be called in order to generate a more useful default error message (see also the <a class="reference internal" href="#type-specific-methods"><span>list of type-specific methods</span></a>).</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-306"><span class="versionmodified">Changed in version 3.1: </span>Added the automatic calling of type-specific equality function.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-307"><span class="versionmodified">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"><span class="pre">assertMultiLineEqual()</span></code></a> added as the default type equality function for comparing strings.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertNotEqual"><span class="yiyi-st" id="yiyi-308"> <code class="descname">assertNotEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-309">测试<em>第一值</em>和<em>第二个值</em>不相等。</span><span class="yiyi-st" id="yiyi-310">If the values do compare equal, the test will fail.</span></p></dd></dl><dl class="method"><dt id="unittest.TestCase.assertTrue"><span class="yiyi-st" id="yiyi-311"> <code class="descname">assertTrue</code><span class="sig-paren">(</span><em>expr</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertFalse"><span class="yiyi-st" id="yiyi-312"> <code class="descname">assertFalse</code><span class="sig-paren">(</span><em>expr</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-313">Test that <em>expr</em> is true (or false).</span></p><p><span class="yiyi-st" id="yiyi-314">Note that this is equivalent to <code class="docutils literal"><span class="pre">bool(expr)</span> <span class="pre">is</span> <span class="pre">True</span></code> and not to <code class="docutils literal"><span class="pre">expr</span> <span class="pre">is</span> <span class="pre">True</span></code> (use <code class="docutils literal"><span class="pre">assertIs(expr,</span> <span class="pre">True)</span></code> for the latter). </span><span class="yiyi-st" id="yiyi-315">This method should also be avoided when more specific methods are available (e.g. </span><span class="yiyi-st" id="yiyi-316"><code class="docutils literal"><span class="pre">assertEqual(a,</span> <span class="pre">b)</span></code> instead of <code class="docutils literal"><span class="pre">assertTrue(a</span> <span class="pre">==</span> <span class="pre">b)</span></code>), because they provide a better error message in case of failure.</span></p></dd></dl><dl class="method"><dt id="unittest.TestCase.assertIs"><span class="yiyi-st" id="yiyi-317"> <code class="descname">assertIs</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertIsNot"><span class="yiyi-st" id="yiyi-318"> <code class="descname">assertIsNot</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-319">Test that <em>first</em> and <em>second</em> evaluate (or don’t evaluate) to the same object.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-320"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertIsNone"><span class="yiyi-st" id="yiyi-321"> <code class="descname">assertIsNone</code><span class="sig-paren">(</span><em>expr</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertIsNotNone"><span class="yiyi-st" id="yiyi-322"> <code class="descname">assertIsNotNone</code><span class="sig-paren">(</span><em>expr</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-323">Test that <em>expr</em> is (or is not) None.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-324"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertIn"><span class="yiyi-st" id="yiyi-325"> <code class="descname">assertIn</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertNotIn"><span class="yiyi-st" id="yiyi-326"> <code class="descname">assertNotIn</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-327">Test that <em>first</em> is (or is not) in <em>second</em>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-328"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertIsInstance"><span class="yiyi-st" id="yiyi-329"> <code class="descname">assertIsInstance</code><span class="sig-paren">(</span><em>obj</em>, <em>cls</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertNotIsInstance"><span class="yiyi-st" id="yiyi-330"> <code class="descname">assertNotIsInstance</code><span class="sig-paren">(</span><em>obj</em>, <em>cls</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-331">Test that <em>obj</em> is (or is not) an instance of <em>cls</em> (which can be a class 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"><span class="pre">isinstance()</span></code></a>). </span><span class="yiyi-st" id="yiyi-332">To 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"><span class="pre">assertIs(type(obj),</span> <span class="pre">cls)</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-333"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-334">It is also possible to check the production of exceptions, warnings, and log messages using the following methods:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-335">Method</span></th><th class="head"><span class="yiyi-st" id="yiyi-336">Checks that</span></th><th class="head"><span class="yiyi-st" id="yiyi-337">New in</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-338"><a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal"><span class="pre">assertRaises(exc,</span> <span class="pre">fun,</span> <span class="pre">*args,</span> <span class="pre">**kwds)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-339"><code class="docutils literal"><span class="pre">fun(*args,</span> <span class="pre">**kwds)</span></code> raises <em>exc</em></span></td><td></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-340"><a class="reference internal" href="#unittest.TestCase.assertRaisesRegex" title="unittest.TestCase.assertRaisesRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRaisesRegex(exc,</span> <span class="pre">r,</span> <span class="pre">fun,</span> <span class="pre">*args,</span> <span class="pre">**kwds)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-341"><code class="docutils literal"><span class="pre">fun(*args,</span> <span class="pre">**kwds)</span></code> raises <em>exc</em> and the message matches regex <em>r</em></span></td><td><span class="yiyi-st" id="yiyi-342">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-343"><a class="reference internal" href="#unittest.TestCase.assertWarns" title="unittest.TestCase.assertWarns"><code class="xref py py-meth docutils literal"><span class="pre">assertWarns(warn,</span> <span class="pre">fun,</span> <span class="pre">*args,</span> <span class="pre">**kwds)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-344"><code class="docutils literal"><span class="pre">fun(*args,</span> <span class="pre">**kwds)</span></code> raises <em>warn</em></span></td><td><span class="yiyi-st" id="yiyi-345">3.2</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-346"><a class="reference internal" href="#unittest.TestCase.assertWarnsRegex" title="unittest.TestCase.assertWarnsRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertWarnsRegex(warn,</span> <span class="pre">r,</span> <span class="pre">fun,</span> <span class="pre">*args,</span> <span class="pre">**kwds)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-347"><code class="docutils literal"><span class="pre">fun(*args,</span> <span class="pre">**kwds)</span></code> raises <em>warn</em> and the message matches regex <em>r</em></span></td><td><span class="yiyi-st" id="yiyi-348">3.2</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-349"><a class="reference internal" href="#unittest.TestCase.assertLogs" title="unittest.TestCase.assertLogs"><code class="xref py py-meth docutils literal"><span class="pre">assertLogs(logger,</span> <span class="pre">level)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-350">The <code class="docutils literal"><span class="pre">with</span></code> block logs on <em>logger</em> with minimum <em>level</em></span></td><td><span class="yiyi-st" id="yiyi-351">3.4</span></td></tr></tbody></table><dl class="method"><dt id="unittest.TestCase.assertRaises"><span class="yiyi-st" id="yiyi-352"> <code class="descname">assertRaises</code><span class="sig-paren">(</span><em>exception</em>, <em>callable</em>, <em>*args</em>, <em>**kwds</em><span class="sig-paren">)</span></span></dt><dt><span class="yiyi-st" id="yiyi-353"> <code class="descname">assertRaises</code><span class="sig-paren">(</span><em>exception</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-354">Test that an exception is raised when <em>callable</em> is called with any positional or keyword arguments that are also passed to <a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal"><span class="pre">assertRaises()</span></code></a>. </span><span class="yiyi-st" id="yiyi-355">The test passes if <em>exception</em> is raised, is an error if another exception is raised, or fails if no exception is raised. </span><span class="yiyi-st" id="yiyi-356">To catch any of a group of exceptions, a tuple containing the exception classes may be passed as <em>exception</em>.</span></p><p><span class="yiyi-st" id="yiyi-357">If only the <em>exception</em> and possibly the <em>msg</em> arguments are given, return a context manager so that the code under test can be written inline rather than as a function:</span></p><pre><code class="language-python"><span></span><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="n">SomeException</span><span class="p">):</span>
<span class="n">do_something</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-358">When used as a context manager, <a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal"><span class="pre">assertRaises()</span></code></a> accepts the additional keyword argument <em>msg</em>.</span></p><p><span class="yiyi-st" id="yiyi-359">The context manager will store the caught exception object in its <code class="xref py py-attr docutils literal"><span class="pre">exception</span></code> attribute. </span><span class="yiyi-st" id="yiyi-360">This can be useful if the intention is to perform additional checks on the exception raised:</span></p><pre><code class="language-python"><span></span><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="n">SomeException</span><span class="p">)</span> <span class="k">as</span> <span class="n">cm</span><span class="p">:</span>
<span class="n">do_something</span><span class="p">()</span>
<span class="n">the_exception</span> <span class="o">=</span> <span class="n">cm</span><span class="o">.</span><span class="n">exception</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">the_exception</span><span class="o">.</span><span class="n">error_code</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
</code></pre><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-361"><span class="versionmodified">Changed in version 3.1: </span>Added the ability to use <a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal"><span class="pre">assertRaises()</span></code></a> as a context manager.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-362"><span class="versionmodified">Changed in version 3.2: </span>Added the <code class="xref py py-attr docutils literal"><span class="pre">exception</span></code> attribute.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-363"><span class="versionmodified">Changed in version 3.3: </span>Added the <em>msg</em> keyword argument when used as a context manager.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertRaisesRegex"><span class="yiyi-st" id="yiyi-364"> <code class="descname">assertRaisesRegex</code><span class="sig-paren">(</span><em>exception</em>, <em>regex</em>, <em>callable</em>, <em>*args</em>, <em>**kwds</em><span class="sig-paren">)</span></span></dt><dt><span class="yiyi-st" id="yiyi-365"> <code class="descname">assertRaisesRegex</code><span class="sig-paren">(</span><em>exception</em>, <em>regex</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-366">Like <a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal"><span class="pre">assertRaises()</span></code></a> but also tests that <em>regex</em> matches on the string representation of the raised exception. </span><span class="yiyi-st" id="yiyi-367"><em>regex</em> may be a regular expression object or a string containing a regular expression suitable for use by <a class="reference internal" href="re.html#re.search" title="re.search"><code class="xref py py-func docutils literal"><span class="pre">re.search()</span></code></a>. </span><span class="yiyi-st" id="yiyi-368">Examples:</span></p><pre><code class="language-python"><span></span><span class="bp">self</span><span class="o">.</span><span class="n">assertRaisesRegex</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="s2">"invalid literal for.*XYZ'$"</span><span class="p">,</span>
<span class="nb">int</span><span class="p">,</span> <span class="s1">'XYZ'</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-369">or:</span></p><pre><code class="language-python"><span></span><span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">assertRaisesRegex</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="s1">'literal'</span><span class="p">):</span>
<span class="nb">int</span><span class="p">(</span><span class="s1">'XYZ'</span><span class="p">)</span>
</code></pre><div class="versionadded"><p><span class="yiyi-st" id="yiyi-370"><span class="versionmodified">New in version 3.1: </span>under the name <code class="docutils literal"><span class="pre">assertRaisesRegexp</span></code>.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-371"><span class="versionmodified">Changed in version 3.2: </span>Renamed to <a class="reference internal" href="#unittest.TestCase.assertRaisesRegex" title="unittest.TestCase.assertRaisesRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRaisesRegex()</span></code></a>.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-372"><span class="versionmodified">Changed in version 3.3: </span>Added the <em>msg</em> keyword argument when used as a context manager.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertWarns"><span class="yiyi-st" id="yiyi-373"> <code class="descname">assertWarns</code><span class="sig-paren">(</span><em>warning</em>, <em>callable</em>, <em>*args</em>, <em>**kwds</em><span class="sig-paren">)</span></span></dt><dt><span class="yiyi-st" id="yiyi-374"> <code class="descname">assertWarns</code><span class="sig-paren">(</span><em>warning</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-375">Test that a warning is triggered when <em>callable</em> is called with any positional or keyword arguments that are also passed to <a class="reference internal" href="#unittest.TestCase.assertWarns" title="unittest.TestCase.assertWarns"><code class="xref py py-meth docutils literal"><span class="pre">assertWarns()</span></code></a>. </span><span class="yiyi-st" id="yiyi-376">The test passes if <em>warning</em> is triggered and fails if it isn’t. </span><span class="yiyi-st" id="yiyi-377">Any exception is an error. </span><span class="yiyi-st" id="yiyi-378">To catch any of a group of warnings, a tuple containing the warning classes may be passed as <em>warnings</em>.</span></p><p><span class="yiyi-st" id="yiyi-379">If only the <em>warning</em> and possibly the <em>msg</em> arguments are given, return a context manager so that the code under test can be written inline rather than as a function:</span></p><pre><code class="language-python"><span></span><span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">assertWarns</span><span class="p">(</span><span class="n">SomeWarning</span><span class="p">):</span>
<span class="n">do_something</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-380">When used as a context manager, <a class="reference internal" href="#unittest.TestCase.assertWarns" title="unittest.TestCase.assertWarns"><code class="xref py py-meth docutils literal"><span class="pre">assertWarns()</span></code></a> accepts the additional keyword argument <em>msg</em>.</span></p><p><span class="yiyi-st" id="yiyi-381">The context manager will store the caught warning object in its <code class="xref py py-attr docutils literal"><span class="pre">warning</span></code> attribute, and the source line which triggered the warnings in the <code class="xref py py-attr docutils literal"><span class="pre">filename</span></code> and <code class="xref py py-attr docutils literal"><span class="pre">lineno</span></code> attributes. </span><span class="yiyi-st" id="yiyi-382">This can be useful if the intention is to perform additional checks on the warning caught:</span></p><pre><code class="language-python"><span></span><span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">assertWarns</span><span class="p">(</span><span class="n">SomeWarning</span><span class="p">)</span> <span class="k">as</span> <span class="n">cm</span><span class="p">:</span>
<span class="n">do_something</span><span class="p">()</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertIn</span><span class="p">(</span><span class="s1">'myfile.py'</span><span class="p">,</span> <span class="n">cm</span><span class="o">.</span><span class="n">filename</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="mi">320</span><span class="p">,</span> <span class="n">cm</span><span class="o">.</span><span class="n">lineno</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-383">This method works regardless of the warning filters in place when it is called.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-384"><span class="versionmodified">New in version 3.2.</span></span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-385"><span class="versionmodified">Changed in version 3.3: </span>Added the <em>msg</em> keyword argument when used as a context manager.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertWarnsRegex"><span class="yiyi-st" id="yiyi-386"> <code class="descname">assertWarnsRegex</code><span class="sig-paren">(</span><em>warning</em>, <em>regex</em>, <em>callable</em>, <em>*args</em>, <em>**kwds</em><span class="sig-paren">)</span></span></dt><dt><span class="yiyi-st" id="yiyi-387"> <code class="descname">assertWarnsRegex</code><span class="sig-paren">(</span><em>warning</em>, <em>regex</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-388">Like <a class="reference internal" href="#unittest.TestCase.assertWarns" title="unittest.TestCase.assertWarns"><code class="xref py py-meth docutils literal"><span class="pre">assertWarns()</span></code></a> but also tests that <em>regex</em> matches on the message of the triggered warning. </span><span class="yiyi-st" id="yiyi-389"><em>regex</em> may be a regular expression object or a string containing a regular expression suitable for use by <a class="reference internal" href="re.html#re.search" title="re.search"><code class="xref py py-func docutils literal"><span class="pre">re.search()</span></code></a>. </span><span class="yiyi-st" id="yiyi-390">Example:</span></p><pre><code class="language-python"><span></span><span class="bp">self</span><span class="o">.</span><span class="n">assertWarnsRegex</span><span class="p">(</span><span class="ne">DeprecationWarning</span><span class="p">,</span>
<span class="s1">r'legacy_function\(\) is deprecated'</span><span class="p">,</span>
<span class="n">legacy_function</span><span class="p">,</span> <span class="s1">'XYZ'</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-391">or:</span></p><pre><code class="language-python"><span></span><span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">assertWarnsRegex</span><span class="p">(</span><span class="ne">RuntimeWarning</span><span class="p">,</span> <span class="s1">'unsafe frobnicating'</span><span class="p">):</span>
<span class="n">frobnicate</span><span class="p">(</span><span class="s1">'/etc/passwd'</span><span class="p">)</span>
</code></pre><div class="versionadded"><p><span class="yiyi-st" id="yiyi-392"><span class="versionmodified">New in version 3.2.</span></span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-393"><span class="versionmodified">Changed in version 3.3: </span>Added the <em>msg</em> keyword argument when used as a context manager.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertLogs"><span class="yiyi-st" id="yiyi-394"> <code class="descname">assertLogs</code><span class="sig-paren">(</span><em>logger=None</em>, <em>level=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-395">A context manager to test that at least one message is logged on the <em>logger</em> or one of its children, with at least the given <em>level</em>.</span></p><p><span class="yiyi-st" id="yiyi-396">If given, <em>logger</em> should be a <a class="reference internal" href="logging.html#logging.Logger" title="logging.Logger"><code class="xref py py-class docutils literal"><span class="pre">logging.Logger</span></code></a> object or a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a> giving the name of a logger. </span><span class="yiyi-st" id="yiyi-397">The default is the root logger, which will catch all messages.</span></p><p><span class="yiyi-st" id="yiyi-398">If given, <em>level</em> should be either a numeric logging level or its string equivalent (for example either <code class="docutils literal"><span class="pre">"ERROR"</span></code> or <code class="xref py py-attr docutils literal"><span class="pre">logging.ERROR</span></code>). </span><span class="yiyi-st" id="yiyi-399">The default is <code class="xref py py-attr docutils literal"><span class="pre">logging.INFO</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-400">The test passes if at least one message emitted inside the <code class="docutils literal"><span class="pre">with</span></code> block matches the <em>logger</em> and <em>level</em> conditions, otherwise it fails.</span></p><p><span class="yiyi-st" id="yiyi-401">The object returned by the context manager is a recording helper which keeps tracks of the matching log messages. </span><span class="yiyi-st" id="yiyi-402">It has two attributes:</span></p><dl class="attribute"><dt id="unittest.TestCase.records"><span class="yiyi-st" id="yiyi-403"> <code class="descname">records</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-404">A list of <a class="reference internal" href="logging.html#logging.LogRecord" title="logging.LogRecord"><code class="xref py py-class docutils literal"><span class="pre">logging.LogRecord</span></code></a> objects of the matching log messages.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestCase.output"><span class="yiyi-st" id="yiyi-405"> <code class="descname">output</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-406">A list of <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal"><span class="pre">str</span></code></a> objects with the formatted output of matching messages.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-407">Example:</span></p><pre><code class="language-python"><span></span><span class="k">with</span> <span class="bp">self</span><span class="o">.</span><span class="n">assertLogs</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">,</span> <span class="n">level</span><span class="o">=</span><span class="s1">'INFO'</span><span class="p">)</span> <span class="k">as</span> <span class="n">cm</span><span class="p">:</span>
<span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s1">'first message'</span><span class="p">)</span>
<span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="s1">'foo.bar'</span><span class="p">)</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s1">'second message'</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">cm</span><span class="o">.</span><span class="n">output</span><span class="p">,</span> <span class="p">[</span><span class="s1">'INFO:foo:first message'</span><span class="p">,</span>
<span class="s1">'ERROR:foo.bar:second message'</span><span class="p">])</span>
</code></pre><div class="versionadded"><p><span class="yiyi-st" id="yiyi-408"><span class="versionmodified">New in version 3.4.</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-409">There are also other methods used to perform more specific checks, such as:</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-410">Method</span></th><th class="head"><span class="yiyi-st" id="yiyi-411">Checks that</span></th><th class="head"><span class="yiyi-st" id="yiyi-412">New in</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-413"><a class="reference internal" href="#unittest.TestCase.assertAlmostEqual" title="unittest.TestCase.assertAlmostEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertAlmostEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-414"><code class="docutils literal"><span class="pre">round(a-b,</span> <span class="pre">7)</span> <span class="pre">==</span> <span class="pre">0</span></code></span></td><td></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-415"><a class="reference internal" href="#unittest.TestCase.assertNotAlmostEqual" title="unittest.TestCase.assertNotAlmostEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertNotAlmostEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-416"><code class="docutils literal"><span class="pre">round(a-b,</span> <span class="pre">7)</span> <span class="pre">!=</span> <span class="pre">0</span></code></span></td><td></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-417"><a class="reference internal" href="#unittest.TestCase.assertGreater" title="unittest.TestCase.assertGreater"><code class="xref py py-meth docutils literal"><span class="pre">assertGreater(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-418"><code class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-419">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-420"><a class="reference internal" href="#unittest.TestCase.assertGreaterEqual" title="unittest.TestCase.assertGreaterEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertGreaterEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-421"><code class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;=</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-422">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-423"><a class="reference internal" href="#unittest.TestCase.assertLess" title="unittest.TestCase.assertLess"><code class="xref py py-meth docutils literal"><span class="pre">assertLess(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-424"><code class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-425">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-426"><a class="reference internal" href="#unittest.TestCase.assertLessEqual" title="unittest.TestCase.assertLessEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertLessEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-427"><code class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;=</span> <span class="pre">b</span></code></span></td><td><span class="yiyi-st" id="yiyi-428">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-429"><a class="reference internal" href="#unittest.TestCase.assertRegex" title="unittest.TestCase.assertRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRegex(s,</span> <span class="pre">r)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-430"><code class="docutils literal"><span class="pre">r.search(s)</span></code></span></td><td><span class="yiyi-st" id="yiyi-431">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-432"><a class="reference internal" href="#unittest.TestCase.assertNotRegex" title="unittest.TestCase.assertNotRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertNotRegex(s,</span> <span class="pre">r)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-433"><code class="docutils literal"><span class="pre">not</span> <span class="pre">r.search(s)</span></code></span></td><td><span class="yiyi-st" id="yiyi-434">3.2</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-435"><a class="reference internal" href="#unittest.TestCase.assertCountEqual" title="unittest.TestCase.assertCountEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertCountEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-436"><em>a</em> and <em>b</em> have the same elements in the same number, regardless of their order</span></td><td><span class="yiyi-st" id="yiyi-437">3.2</span></td></tr></tbody></table><dl class="method"><dt id="unittest.TestCase.assertAlmostEqual"><span class="yiyi-st" id="yiyi-438"> <code class="descname">assertAlmostEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>places=7</em>, <em>msg=None</em>, <em>delta=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertNotAlmostEqual"><span class="yiyi-st" id="yiyi-439"> <code class="descname">assertNotAlmostEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>places=7</em>, <em>msg=None</em>, <em>delta=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-440">Test that <em>first</em> and <em>second</em> are approximately (or not approximately) equal by computing the difference, rounding to the given number of decimal <em>places</em> (default 7), and comparing to zero. </span><span class="yiyi-st" id="yiyi-441">Note that these methods round the values to the given number of <em>decimal places</em> (i.e. </span><span class="yiyi-st" id="yiyi-442">like the <a class="reference internal" href="functions.html#round" title="round"><code class="xref py py-func docutils literal"><span class="pre">round()</span></code></a> function) and not <em>significant digits</em>.</span></p><p><span class="yiyi-st" id="yiyi-443">If <em>delta</em> is supplied instead of <em>places</em> then the difference between <em>first</em> and <em>second</em> must be less or equal to (or greater than) <em>delta</em>.</span></p><p><span class="yiyi-st" id="yiyi-444">Supplying both <em>delta</em> and <em>places</em> raises a <code class="docutils literal"><span class="pre">TypeError</span></code>.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-445"><span class="versionmodified">Changed in version 3.2: </span><a class="reference internal" href="#unittest.TestCase.assertAlmostEqual" title="unittest.TestCase.assertAlmostEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertAlmostEqual()</span></code></a> automatically considers almost equal objects that compare equal. </span><span class="yiyi-st" id="yiyi-446"><a class="reference internal" href="#unittest.TestCase.assertNotAlmostEqual" title="unittest.TestCase.assertNotAlmostEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertNotAlmostEqual()</span></code></a> automatically fails if the objects compare equal. </span><span class="yiyi-st" id="yiyi-447">Added the <em>delta</em> keyword argument.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertGreater"><span class="yiyi-st" id="yiyi-448"> <code class="descname">assertGreater</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertGreaterEqual"><span class="yiyi-st" id="yiyi-449"> <code class="descname">assertGreaterEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertLess"><span class="yiyi-st" id="yiyi-450"> <code class="descname">assertLess</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertLessEqual"><span class="yiyi-st" id="yiyi-451"> <code class="descname">assertLessEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-452">Test that <em>first</em> is respectively &gt;, &gt;=, &lt; or &lt;= than <em>second</em> depending on the method name. </span><span class="yiyi-st" id="yiyi-453">If not, the test will fail:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </span><span class="bp">self</span><span class="o">.</span><span class="n">assertGreaterEqual</span><span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">)</span>
<span class="go">AssertionError: "3" unexpectedly not greater than or equal to "4"</span>
</code></pre><div class="versionadded"><p><span class="yiyi-st" id="yiyi-454"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertRegex"><span class="yiyi-st" id="yiyi-455"> <code class="descname">assertRegex</code><span class="sig-paren">(</span><em>text</em>, <em>regex</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertNotRegex"><span class="yiyi-st" id="yiyi-456"> <code class="descname">assertNotRegex</code><span class="sig-paren">(</span><em>text</em>, <em>regex</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-457">Test that a <em>regex</em> search matches (or does not match) <em>text</em>. </span><span class="yiyi-st" id="yiyi-458">In case of failure, the error message will include the pattern and the <em>text</em> (or the pattern and the part of <em>text</em> that unexpectedly matched). </span><span class="yiyi-st" id="yiyi-459"><em>regex</em> may be a regular expression object or a string containing a regular expression suitable for use by <a class="reference internal" href="re.html#re.search" title="re.search"><code class="xref py py-func docutils literal"><span class="pre">re.search()</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-460"><span class="versionmodified">New in version 3.1: </span>under the name <code class="docutils literal"><span class="pre">assertRegexpMatches</span></code>.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-461"><span class="versionmodified">Changed in version 3.2: </span>The method <code class="docutils literal"><span class="pre">assertRegexpMatches()</span></code> has been renamed to <a class="reference internal" href="#unittest.TestCase.assertRegex" title="unittest.TestCase.assertRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRegex()</span></code></a>.</span></p></div><div class="versionadded"><p><span class="yiyi-st" id="yiyi-462"><span class="versionmodified">New in version 3.2: </span><a class="reference internal" href="#unittest.TestCase.assertNotRegex" title="unittest.TestCase.assertNotRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertNotRegex()</span></code></a>.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertCountEqual"><span class="yiyi-st" id="yiyi-463"> <code class="descname">assertCountEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-464">测试序列<em>第一</em>包含与<em>第二</em>相同的元素，而不考虑它们的顺序。</span><span class="yiyi-st" id="yiyi-465">When they don’t, an error message listing the differences between the sequences will be generated.</span></p><p><span class="yiyi-st" id="yiyi-466">当比较<em>第一</em>和<em>第二</em>时，重复的元素<em>不会</em>被忽略。</span><span class="yiyi-st" id="yiyi-467">It verifies whether each element has the same count in both sequences. </span><span class="yiyi-st" id="yiyi-468">Equivalent to: <code class="docutils literal"><span class="pre">assertEqual(Counter(list(first)),</span> <span class="pre">Counter(list(second)))</span></code> but works with sequences of unhashable objects as well.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-469"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><p id="type-specific-methods"><span class="yiyi-st" id="yiyi-470">The <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a> method dispatches the equality check for objects of the same type to different type-specific methods. </span><span class="yiyi-st" id="yiyi-471">These methods are already implemented for most of the built-in types, but it’s also possible to register new methods using <a class="reference internal" href="#unittest.TestCase.addTypeEqualityFunc" title="unittest.TestCase.addTypeEqualityFunc"><code class="xref py py-meth docutils literal"><span class="pre">addTypeEqualityFunc()</span></code></a>:</span></p><dl class="method"><dt id="unittest.TestCase.addTypeEqualityFunc"><span class="yiyi-st" id="yiyi-472"> <code class="descname">addTypeEqualityFunc</code><span class="sig-paren">(</span><em>typeobj</em>, <em>function</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-473">Registers a type-specific method called by <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a> to check if two objects of exactly the same <em>typeobj</em> (not subclasses) compare equal. </span><span class="yiyi-st" id="yiyi-474"><em>function</em> must take two positional arguments and a third msg=None keyword argument just as <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a> does. </span><span class="yiyi-st" id="yiyi-475">It must raise <a class="reference internal" href="#unittest.TestCase.failureException" title="unittest.TestCase.failureException"><code class="xref py py-data docutils literal"><span class="pre">self.failureException(msg)</span></code></a> when inequality between the first two parameters is detected – possibly providing useful information and explaining the inequalities in details in the error message.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-476"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-477">The list of type-specific methods automatically used by <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a> are summarized in the following table. </span><span class="yiyi-st" id="yiyi-478">Note that it’s usually not necessary to invoke these methods directly.</span></p><table border="1" class="docutils"><thead valign="bottom"><tr class="row-odd"><th class="head"><span class="yiyi-st" id="yiyi-479">Method</span></th><th class="head"><span class="yiyi-st" id="yiyi-480">Used to compare</span></th><th class="head"><span class="yiyi-st" id="yiyi-481">New in</span></th></tr></thead><tbody valign="top"><tr class="row-even"><td><span class="yiyi-st" id="yiyi-482"><a class="reference internal" href="#unittest.TestCase.assertMultiLineEqual" title="unittest.TestCase.assertMultiLineEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertMultiLineEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-483">strings</span></td><td><span class="yiyi-st" id="yiyi-484">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-485"><a class="reference internal" href="#unittest.TestCase.assertSequenceEqual" title="unittest.TestCase.assertSequenceEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertSequenceEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-486">sequences</span></td><td><span class="yiyi-st" id="yiyi-487">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-488"><a class="reference internal" href="#unittest.TestCase.assertListEqual" title="unittest.TestCase.assertListEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertListEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-489">lists</span></td><td><span class="yiyi-st" id="yiyi-490">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-491"><a class="reference internal" href="#unittest.TestCase.assertTupleEqual" title="unittest.TestCase.assertTupleEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertTupleEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-492">tuples</span></td><td><span class="yiyi-st" id="yiyi-493">3.1</span></td></tr><tr class="row-even"><td><span class="yiyi-st" id="yiyi-494"><a class="reference internal" href="#unittest.TestCase.assertSetEqual" title="unittest.TestCase.assertSetEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertSetEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-495">sets or frozensets</span></td><td><span class="yiyi-st" id="yiyi-496">3.1</span></td></tr><tr class="row-odd"><td><span class="yiyi-st" id="yiyi-497"><a class="reference internal" href="#unittest.TestCase.assertDictEqual" title="unittest.TestCase.assertDictEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertDictEqual(a,</span> <span class="pre">b)</span></code></a></span></td><td><span class="yiyi-st" id="yiyi-498">dicts</span></td><td><span class="yiyi-st" id="yiyi-499">3.1</span></td></tr></tbody></table><dl class="method"><dt id="unittest.TestCase.assertMultiLineEqual"><span class="yiyi-st" id="yiyi-500"> <code class="descname">assertMultiLineEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-501">测试多行字符串<em>第一</em>等于字符串<em>第二</em>。</span><span class="yiyi-st" id="yiyi-502">When not equal a diff of the two strings highlighting the differences will be included in the error message. </span><span class="yiyi-st" id="yiyi-503">This method is used by default when comparing strings with <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-504"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertSequenceEqual"><span class="yiyi-st" id="yiyi-505"> <code class="descname">assertSequenceEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em>, <em>seq_type=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-506">Tests that two sequences are equal. </span><span class="yiyi-st" id="yiyi-507">If a <em>seq_type</em> is supplied, both <em>first</em> and <em>second</em> must be instances of <em>seq_type</em> or a failure will be raised. </span><span class="yiyi-st" id="yiyi-508">If the sequences are different an error message is constructed that shows the difference between the two.</span></p><p><span class="yiyi-st" id="yiyi-509">This method is not called directly by <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a>, but it’s used to implement <a class="reference internal" href="#unittest.TestCase.assertListEqual" title="unittest.TestCase.assertListEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertListEqual()</span></code></a> and <a class="reference internal" href="#unittest.TestCase.assertTupleEqual" title="unittest.TestCase.assertTupleEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertTupleEqual()</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-510"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertListEqual"><span class="yiyi-st" id="yiyi-511"> <code class="descname">assertListEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dt id="unittest.TestCase.assertTupleEqual"><span class="yiyi-st" id="yiyi-512"> <code class="descname">assertTupleEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-513">Tests that two lists or tuples are equal. </span><span class="yiyi-st" id="yiyi-514">If not, an error message is constructed that shows only the differences between the two. </span><span class="yiyi-st" id="yiyi-515">An error is also raised if either of the parameters are of the wrong type. </span><span class="yiyi-st" id="yiyi-516">These methods are used by default when comparing lists or tuples with <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-517"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertSetEqual"><span class="yiyi-st" id="yiyi-518"> <code class="descname">assertSetEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-519">Tests that two sets are equal. </span><span class="yiyi-st" id="yiyi-520">If not, an error message is constructed that lists the differences between the sets. </span><span class="yiyi-st" id="yiyi-521">This method is used by default when comparing sets or frozensets with <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-522">Fails if either of <em>first</em> or <em>second</em> does not have a <a class="reference internal" href="stdtypes.html#set.difference" title="set.difference"><code class="xref py py-meth docutils literal"><span class="pre">set.difference()</span></code></a> method.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-523"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.assertDictEqual"><span class="yiyi-st" id="yiyi-524"> <code class="descname">assertDictEqual</code><span class="sig-paren">(</span><em>first</em>, <em>second</em>, <em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-525">Test that two dictionaries are equal. </span><span class="yiyi-st" id="yiyi-526">If not, an error message is constructed that shows the differences in the dictionaries. </span><span class="yiyi-st" id="yiyi-527">This method will be used by default to compare dictionaries in calls to <a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-528"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><p id="other-methods-and-attrs"><span class="yiyi-st" id="yiyi-529">Finally the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> provides the following methods and attributes:</span></p><dl class="method"><dt id="unittest.TestCase.fail"><span class="yiyi-st" id="yiyi-530"> <code class="descname">fail</code><span class="sig-paren">(</span><em>msg=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-531">Signals a test failure unconditionally, with <em>msg</em> or <code class="docutils literal"><span class="pre">None</span></code> for the error message.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestCase.failureException"><span class="yiyi-st" id="yiyi-532"> <code class="descname">failureException</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-533">This class attribute gives the exception raised by the test method. </span><span class="yiyi-st" id="yiyi-534">If a test framework needs to use a specialized exception, possibly to carry additional information, it must subclass this exception in order to “play fair” with the framework. </span><span class="yiyi-st" id="yiyi-535">The initial value of this attribute is <a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal"><span class="pre">AssertionError</span></code></a>.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestCase.longMessage"><span class="yiyi-st" id="yiyi-536"> <code class="descname">longMessage</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-537">If set to <code class="docutils literal"><span class="pre">True</span></code> then any explicit failure message you pass in to the <a class="reference internal" href="#assert-methods"><span>assert methods</span></a> will be appended to the end of the normal failure message. </span><span class="yiyi-st" id="yiyi-538">The normal messages contain useful information about the objects involved, for example the message from assertEqual shows you the repr of the two unequal objects. </span><span class="yiyi-st" id="yiyi-539">Setting this attribute to <code class="docutils literal"><span class="pre">True</span></code> allows you to have a custom error message in addition to the normal one.</span></p><p><span class="yiyi-st" id="yiyi-540">This attribute defaults to <code class="docutils literal"><span class="pre">True</span></code>. </span><span class="yiyi-st" id="yiyi-541">If set to False then a custom message passed to an assert method will silence the normal message.</span></p><p><span class="yiyi-st" id="yiyi-542">The class setting can be overridden in individual tests by assigning an instance attribute to <code class="docutils literal"><span class="pre">True</span></code> or <code class="docutils literal"><span class="pre">False</span></code> before calling the assert methods.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-543"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="attribute"><dt id="unittest.TestCase.maxDiff"><span class="yiyi-st" id="yiyi-544"> <code class="descname">maxDiff</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-545">This attribute controls the maximum length of diffs output by assert methods that report diffs on failure. </span><span class="yiyi-st" id="yiyi-546">It defaults to 80*8 characters. </span><span class="yiyi-st" id="yiyi-547">Assert methods affected by this attribute are <a class="reference internal" href="#unittest.TestCase.assertSequenceEqual" title="unittest.TestCase.assertSequenceEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertSequenceEqual()</span></code></a> (including all the sequence comparison methods that delegate to it), <a class="reference internal" href="#unittest.TestCase.assertDictEqual" title="unittest.TestCase.assertDictEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertDictEqual()</span></code></a> and <a class="reference internal" href="#unittest.TestCase.assertMultiLineEqual" title="unittest.TestCase.assertMultiLineEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertMultiLineEqual()</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-548">Setting <code class="docutils literal"><span class="pre">maxDiff</span></code> to None means that there is no maximum length of diffs.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-549"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-550">Testing frameworks can use the following methods to collect information on the test:</span></p><dl class="method"><dt id="unittest.TestCase.countTestCases"><span class="yiyi-st" id="yiyi-551"> <code class="descname">countTestCases</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-552">Return the number of tests represented by this test object. </span><span class="yiyi-st" id="yiyi-553">For <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances, this will always be <code class="docutils literal"><span class="pre">1</span></code>.</span></p></dd></dl><dl class="method"><dt id="unittest.TestCase.defaultTestResult"><span class="yiyi-st" id="yiyi-554"> <code class="descname">defaultTestResult</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-555">Return an instance of the test result class that should be used for this test case class (if no other result instance is provided to the <a class="reference internal" href="#unittest.TestCase.run" title="unittest.TestCase.run"><code class="xref py py-meth docutils literal"><span class="pre">run()</span></code></a> method).</span></p><p><span class="yiyi-st" id="yiyi-556">For <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances, this will always be an instance of <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a>; subclasses of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> should override this as necessary.</span></p></dd></dl><dl class="method"><dt id="unittest.TestCase.id"><span class="yiyi-st" id="yiyi-557"> <code class="descname">id</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-558">Return a string identifying the specific test case. </span><span class="yiyi-st" id="yiyi-559">This is usually the full name of the test method, including the module and class name.</span></p></dd></dl><dl class="method"><dt id="unittest.TestCase.shortDescription"><span class="yiyi-st" id="yiyi-560"> <code class="descname">shortDescription</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-561">Returns a description of the test, or <code class="docutils literal"><span class="pre">None</span></code> if no description has been provided. </span><span class="yiyi-st" id="yiyi-562">The default implementation of this method returns the first line of the test method’s docstring, if available, or <code class="docutils literal"><span class="pre">None</span></code>.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-563"><span class="versionmodified">Changed in version 3.1: </span>In 3.1 this was changed to add the test name to the short description even in the presence of a docstring. </span><span class="yiyi-st" id="yiyi-564">This caused compatibility issues with unittest extensions and adding the test name was moved to the <a class="reference internal" href="#unittest.TextTestResult" title="unittest.TextTestResult"><code class="xref py py-class docutils literal"><span class="pre">TextTestResult</span></code></a> in Python 3.2.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.addCleanup"><span class="yiyi-st" id="yiyi-565"> <code class="descname">addCleanup</code><span class="sig-paren">(</span><em>function</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-566">Add a function to be called after <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal"><span class="pre">tearDown()</span></code></a> to cleanup resources used during the test. </span><span class="yiyi-st" id="yiyi-567">Functions will be called in reverse order to the order they are added (LIFO). </span><span class="yiyi-st" id="yiyi-568">They are called with any arguments and keyword arguments passed into <a class="reference internal" href="#unittest.TestCase.addCleanup" title="unittest.TestCase.addCleanup"><code class="xref py py-meth docutils literal"><span class="pre">addCleanup()</span></code></a> when they are added.</span></p><p><span class="yiyi-st" id="yiyi-569">If <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><span class="pre">setUp()</span></code></a> fails, meaning that <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal"><span class="pre">tearDown()</span></code></a> is not called, then any cleanup functions added will still be called.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-570"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestCase.doCleanups"><span class="yiyi-st" id="yiyi-571"> <code class="descname">doCleanups</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-572">This method is called unconditionally after <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal"><span class="pre">tearDown()</span></code></a>, or after <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><span class="pre">setUp()</span></code></a> if <a class="reference internal" href="#unittest.TestCase.setUp" title="unittest.TestCase.setUp"><code class="xref py py-meth docutils literal"><span class="pre">setUp()</span></code></a> raises an exception.</span></p><p><span class="yiyi-st" id="yiyi-573">It is responsible for calling all the cleanup functions added by <a class="reference internal" href="#unittest.TestCase.addCleanup" title="unittest.TestCase.addCleanup"><code class="xref py py-meth docutils literal"><span class="pre">addCleanup()</span></code></a>. </span><span class="yiyi-st" id="yiyi-574">If you need cleanup functions to be called <em>prior</em> to <a class="reference internal" href="#unittest.TestCase.tearDown" title="unittest.TestCase.tearDown"><code class="xref py py-meth docutils literal"><span class="pre">tearDown()</span></code></a> then you can call <a class="reference internal" href="#unittest.TestCase.doCleanups" title="unittest.TestCase.doCleanups"><code class="xref py py-meth docutils literal"><span class="pre">doCleanups()</span></code></a> yourself.</span></p><p><span class="yiyi-st" id="yiyi-575"><a class="reference internal" href="#unittest.TestCase.doCleanups" title="unittest.TestCase.doCleanups"><code class="xref py py-meth docutils literal"><span class="pre">doCleanups()</span></code></a> pops methods off the stack of cleanup functions one at a time, so it can be called at any time.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-576"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl></dd></dl><dl class="class"><dt id="unittest.FunctionTestCase"><span class="yiyi-st" id="yiyi-577"> <em class="property">class </em><code class="descclassname">unittest.</code><code class="descname">FunctionTestCase</code><span class="sig-paren">(</span><em>testFunc</em>, <em>setUp=None</em>, <em>tearDown=None</em>, <em>description=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-578">This class implements the portion of the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> interface which allows the test runner to drive the test, but does not provide the methods which test code can use to check and report errors. </span><span class="yiyi-st" id="yiyi-579">This is used to create test cases using legacy test code, allowing it to be integrated into a <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a>-based test framework.</span></p></dd></dl><div class="section" id="deprecated-aliases"><h4><span class="yiyi-st" id="yiyi-580">26.4.8.1.1. </span><span class="yiyi-st" id="yiyi-581">Deprecated aliases</span></h4><p><span class="yiyi-st" id="yiyi-582">For historical reasons, some of the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> methods had one or more aliases that are now deprecated. </span><span class="yiyi-st" id="yiyi-583">The following table lists the correct names along with their deprecated aliases:</span></p><span class="yiyi-st" id="yiyi-584"> <blockquote> <div><table border="1" class="docutils"> <colgroup> <col width="41%"/> <col width="30%"/> <col width="30%"/> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Method Name</th> <th class="head">Deprecated alias</th> <th class="head">Deprecated alias</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><a class="reference internal" href="#unittest.TestCase.assertEqual" title="unittest.TestCase.assertEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertEqual()</span></code></a></td> <td>failUnlessEqual</td> <td>assertEquals</td> </tr> <tr class="row-odd"><td><a class="reference internal" href="#unittest.TestCase.assertNotEqual" title="unittest.TestCase.assertNotEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertNotEqual()</span></code></a></td> <td>failIfEqual</td> <td>assertNotEquals</td> </tr> <tr class="row-even"><td><a class="reference internal" href="#unittest.TestCase.assertTrue" title="unittest.TestCase.assertTrue"><code class="xref py py-meth docutils literal"><span class="pre">assertTrue()</span></code></a></td> <td>failUnless</td> <td>assert_</td> </tr> <tr class="row-odd"><td><a class="reference internal" href="#unittest.TestCase.assertFalse" title="unittest.TestCase.assertFalse"><code class="xref py py-meth docutils literal"><span class="pre">assertFalse()</span></code></a></td> <td>failIf</td> <td> </td> </tr> <tr class="row-even"><td><a class="reference internal" href="#unittest.TestCase.assertRaises" title="unittest.TestCase.assertRaises"><code class="xref py py-meth docutils literal"><span class="pre">assertRaises()</span></code></a></td> <td>failUnlessRaises</td> <td> </td> </tr> <tr class="row-odd"><td><a class="reference internal" href="#unittest.TestCase.assertAlmostEqual" title="unittest.TestCase.assertAlmostEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertAlmostEqual()</span></code></a></td> <td>failUnlessAlmostEqual</td> <td>assertAlmostEquals</td> </tr> <tr class="row-even"><td><a class="reference internal" href="#unittest.TestCase.assertNotAlmostEqual" title="unittest.TestCase.assertNotAlmostEqual"><code class="xref py py-meth docutils literal"><span class="pre">assertNotAlmostEqual()</span></code></a></td> <td>failIfAlmostEqual</td> <td>assertNotAlmostEquals</td> </tr> <tr class="row-odd"><td><a class="reference internal" href="#unittest.TestCase.assertRegex" title="unittest.TestCase.assertRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRegex()</span></code></a></td> <td> </td> <td>assertRegexpMatches</td> </tr> <tr class="row-even"><td><a class="reference internal" href="#unittest.TestCase.assertRaisesRegex" title="unittest.TestCase.assertRaisesRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRaisesRegex()</span></code></a></td> <td> </td> <td>assertRaisesRegexp</td> </tr> </tbody> </table> <div class="deprecated"> <p><span class="versionmodified">Deprecated since version 3.1: </span>the fail* aliases listed in the second column.</p> </div> <div class="deprecated"> <p><span class="versionmodified">Deprecated since version 3.2: </span>the assert* aliases listed in the third column.</p> </div> <div class="deprecated"> <p><span class="versionmodified">Deprecated since version 3.2: </span><code class="docutils literal"><span class="pre">assertRegexpMatches</span></code> and <code class="docutils literal"><span class="pre">assertRaisesRegexp</span></code> have been renamed to <a class="reference internal" href="#unittest.TestCase.assertRegex" title="unittest.TestCase.assertRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRegex()</span></code></a> and <a class="reference internal" href="#unittest.TestCase.assertRaisesRegex" title="unittest.TestCase.assertRaisesRegex"><code class="xref py py-meth docutils literal"><span class="pre">assertRaisesRegex()</span></code></a></p> </div> </div></blockquote></span></div></div><div class="section" id="grouping-tests"><h3><span class="yiyi-st" id="yiyi-585">26.4.8.2. </span><span class="yiyi-st" id="yiyi-586">Grouping tests</span></h3><dl class="class"><dt id="unittest.TestSuite"><span class="yiyi-st" id="yiyi-587"> <em class="property">class </em><code class="descclassname">unittest.</code><code class="descname">TestSuite</code><span class="sig-paren">(</span><em>tests=()</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-588">This class represents an aggregation of individual tests cases and test suites. </span><span class="yiyi-st" id="yiyi-589">The class presents the interface needed by the test runner to allow it to be run as any other test case. </span><span class="yiyi-st" id="yiyi-590">Running a <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> instance is the same as iterating over the suite, running each test individually.</span></p><p><span class="yiyi-st" id="yiyi-591">If <em>tests</em> is given, it must be an iterable of individual test cases or other test suites that will be used to build the suite initially. </span><span class="yiyi-st" id="yiyi-592">Additional methods are provided to add test cases and suites to the collection later on.</span></p><p><span class="yiyi-st" id="yiyi-593"><a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> objects behave much like <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> objects, except they do not actually implement a test. </span><span class="yiyi-st" id="yiyi-594">Instead, they are used to aggregate tests into groups of tests that should be run together. </span><span class="yiyi-st" id="yiyi-595">Some additional methods are available to add tests to <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> instances:</span></p><dl class="method"><dt id="unittest.TestSuite.addTest"><span class="yiyi-st" id="yiyi-596"> <code class="descname">addTest</code><span class="sig-paren">(</span><em>test</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-597">Add a <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> or <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> to the suite.</span></p></dd></dl><dl class="method"><dt id="unittest.TestSuite.addTests"><span class="yiyi-st" id="yiyi-598"> <code class="descname">addTests</code><span class="sig-paren">(</span><em>tests</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-599">Add all the tests from an iterable of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> and <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> instances to this test suite.</span></p><p><span class="yiyi-st" id="yiyi-600">This is equivalent to iterating over <em>tests</em>, calling <a class="reference internal" href="#unittest.TestSuite.addTest" title="unittest.TestSuite.addTest"><code class="xref py py-meth docutils literal"><span class="pre">addTest()</span></code></a> for each element.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-601"><a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> shares the following methods with <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>:</span></p><dl class="method"><dt id="unittest.TestSuite.run"><span class="yiyi-st" id="yiyi-602"> <code class="descname">run</code><span class="sig-paren">(</span><em>result</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-603">Run the tests associated with this suite, collecting the result into the test result object passed as <em>result</em>. </span><span class="yiyi-st" id="yiyi-604">Note that unlike <a class="reference internal" href="#unittest.TestCase.run" title="unittest.TestCase.run"><code class="xref py py-meth docutils literal"><span class="pre">TestCase.run()</span></code></a>, <a class="reference internal" href="#unittest.TestSuite.run" title="unittest.TestSuite.run"><code class="xref py py-meth docutils literal"><span class="pre">TestSuite.run()</span></code></a> requires the result object to be passed in.</span></p></dd></dl><dl class="method"><dt id="unittest.TestSuite.debug"><span class="yiyi-st" id="yiyi-605"> <code class="descname">debug</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-606">Run the tests associated with this suite without collecting the result. </span><span class="yiyi-st" id="yiyi-607">This allows exceptions raised by the test to be propagated to the caller and can be used to support running tests under a debugger.</span></p></dd></dl><dl class="method"><dt id="unittest.TestSuite.countTestCases"><span class="yiyi-st" id="yiyi-608"> <code class="descname">countTestCases</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-609">Return the number of tests represented by this test object, including all individual tests and sub-suites.</span></p></dd></dl><dl class="method"><dt id="unittest.TestSuite.__iter__"><span class="yiyi-st" id="yiyi-610"> <code class="descname">__iter__</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-611">Tests grouped by a <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> are always accessed by iteration. </span><span class="yiyi-st" id="yiyi-612">Subclasses can lazily provide tests by overriding <a class="reference internal" href="#unittest.TestSuite.__iter__" title="unittest.TestSuite.__iter__"><code class="xref py py-meth docutils literal"><span class="pre">__iter__()</span></code></a>. </span><span class="yiyi-st" id="yiyi-613">Note that this method may be called several times on a single suite (for example when counting tests or comparing for equality) so the tests returned by repeated iterations before <a class="reference internal" href="#unittest.TestSuite.run" title="unittest.TestSuite.run"><code class="xref py py-meth docutils literal"><span class="pre">TestSuite.run()</span></code></a> must be the same for each call iteration. </span><span class="yiyi-st" id="yiyi-614">After <a class="reference internal" href="#unittest.TestSuite.run" title="unittest.TestSuite.run"><code class="xref py py-meth docutils literal"><span class="pre">TestSuite.run()</span></code></a>, callers should not rely on the tests returned by this method unless the caller uses a subclass that overrides <code class="xref py py-meth docutils literal"><span class="pre">TestSuite._removeTestAtIndex()</span></code> to preserve test references.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-615"><span class="versionmodified">Changed in version 3.2: </span>In earlier versions the <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> accessed tests directly rather than through iteration, so overriding <a class="reference internal" href="#unittest.TestSuite.__iter__" title="unittest.TestSuite.__iter__"><code class="xref py py-meth docutils literal"><span class="pre">__iter__()</span></code></a> wasn’t sufficient for providing tests.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-616"><span class="versionmodified">Changed in version 3.4: </span>In earlier versions the <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> held references to each <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> after <a class="reference internal" href="#unittest.TestSuite.run" title="unittest.TestSuite.run"><code class="xref py py-meth docutils literal"><span class="pre">TestSuite.run()</span></code></a>. </span><span class="yiyi-st" id="yiyi-617">Subclasses can restore that behavior by overriding <code class="xref py py-meth docutils literal"><span class="pre">TestSuite._removeTestAtIndex()</span></code>.</span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-618">In the typical usage of a <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> object, the <a class="reference internal" href="#unittest.TestSuite.run" title="unittest.TestSuite.run"><code class="xref py py-meth docutils literal"><span class="pre">run()</span></code></a> method is invoked by a <code class="xref py py-class docutils literal"><span class="pre">TestRunner</span></code> rather than by the end-user test harness.</span></p></dd></dl></div><div class="section" id="loading-and-running-tests"><h3><span class="yiyi-st" id="yiyi-619">26.4.8.3. </span><span class="yiyi-st" id="yiyi-620">Loading and running tests</span></h3><dl class="class"><dt id="unittest.TestLoader"><span class="yiyi-st" id="yiyi-621"> <em class="property">class </em><code class="descclassname">unittest.</code><code class="descname">TestLoader</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-622">The <a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> class is used to create test suites from classes and modules. </span><span class="yiyi-st" id="yiyi-623">Normally, there is no need to create an instance of this class; the <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> module provides an instance that can be shared as <a class="reference internal" href="#unittest.defaultTestLoader" title="unittest.defaultTestLoader"><code class="xref py py-data docutils literal"><span class="pre">unittest.defaultTestLoader</span></code></a>. </span><span class="yiyi-st" id="yiyi-624">Using a subclass or instance, however, allows customization of some configurable properties.</span></p><p><span class="yiyi-st" id="yiyi-625"><a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> objects have the following attributes:</span></p><dl class="attribute"><dt id="unittest.TestLoader.errors"><span class="yiyi-st" id="yiyi-626"> <code class="descname">errors</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-627">A list of the non-fatal errors encountered while loading tests. </span><span class="yiyi-st" id="yiyi-628">Not reset by the loader at any point. </span><span class="yiyi-st" id="yiyi-629">Fatal errors are signalled by the relevant a method raising an exception to the caller. </span><span class="yiyi-st" id="yiyi-630">Non-fatal errors are also indicated by a synthetic test that will raise the original error when run.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-631"><span class="versionmodified">New in version 3.5.</span></span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-632"><a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> objects have the following methods:</span></p><dl class="method"><dt id="unittest.TestLoader.loadTestsFromTestCase"><span class="yiyi-st" id="yiyi-633"> <code class="descname">loadTestsFromTestCase</code><span class="sig-paren">(</span><em>testCaseClass</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-634">Return a suite of all tests cases contained in the <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>-derived <code class="xref py py-class docutils literal"><span class="pre">testCaseClass</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-635">A test case instance is created for each method named by <a class="reference internal" href="#unittest.TestLoader.getTestCaseNames" title="unittest.TestLoader.getTestCaseNames"><code class="xref py py-meth docutils literal"><span class="pre">getTestCaseNames()</span></code></a>. </span><span class="yiyi-st" id="yiyi-636">By default these are the method names beginning with <code class="docutils literal"><span class="pre">test</span></code>. </span><span class="yiyi-st" id="yiyi-637">If <a class="reference internal" href="#unittest.TestLoader.getTestCaseNames" title="unittest.TestLoader.getTestCaseNames"><code class="xref py py-meth docutils literal"><span class="pre">getTestCaseNames()</span></code></a> returns no methods, but the <code class="xref py py-meth docutils literal"><span class="pre">runTest()</span></code> method is implemented, a single test case is created for that method instead.</span></p></dd></dl><dl class="method"><dt id="unittest.TestLoader.loadTestsFromModule"><span class="yiyi-st" id="yiyi-638"> <code class="descname">loadTestsFromModule</code><span class="sig-paren">(</span><em>module</em>, <em>pattern=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-639">Return a suite of all tests cases contained in the given module. </span><span class="yiyi-st" id="yiyi-640">This method searches <em>module</em> for classes derived from <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> and creates an instance of the class for each test method defined for the class.</span></p><div class="admonition note"><p class="first admonition-title"><span class="yiyi-st" id="yiyi-641">Note</span></p><p class="last"><span class="yiyi-st" id="yiyi-642">While using a hierarchy of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>-derived classes can be convenient in sharing fixtures and helper functions, defining test methods on base classes that are not intended to be instantiated directly does not play well with this method. </span><span class="yiyi-st" id="yiyi-643">Doing so, however, can be useful when the fixtures are different and defined in subclasses.</span></p></div><p><span class="yiyi-st" id="yiyi-644">If a module provides a <code class="docutils literal"><span class="pre">load_tests</span></code> function it will be called to load the tests. </span><span class="yiyi-st" id="yiyi-645">This allows modules to customize test loading. </span><span class="yiyi-st" id="yiyi-646">This is the <a class="reference internal" href="#load-tests-protocol">load_tests protocol</a>. </span><span class="yiyi-st" id="yiyi-647">The <em>pattern</em> argument is passed as the third argument to <code class="docutils literal"><span class="pre">load_tests</span></code>.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-648"><span class="versionmodified">Changed in version 3.2: </span>Support for <code class="docutils literal"><span class="pre">load_tests</span></code> added.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-649"><span class="versionmodified">Changed in version 3.5: </span>The undocumented and unofficial <em>use_load_tests</em> default argument is deprecated and ignored, although it is still accepted for backward compatibility. </span><span class="yiyi-st" id="yiyi-650">The method also now accepts a keyword-only argument <em>pattern</em> which is passed to <code class="docutils literal"><span class="pre">load_tests</span></code> as the third argument.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestLoader.loadTestsFromName"><span class="yiyi-st" id="yiyi-651"> <code class="descname">loadTestsFromName</code><span class="sig-paren">(</span><em>name</em>, <em>module=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-652">Return a suite of all tests cases given a string specifier.</span></p><p><span class="yiyi-st" id="yiyi-653">The specifier <em>name</em> is a “dotted name” that may resolve either to a module, a test case class, a test method within a test case class, a <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> instance, or a callable object which returns a <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> or <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> instance. </span><span class="yiyi-st" id="yiyi-654">These checks are applied in the order listed here; that is, a method on a possible test case class will be picked up as “a test method within a test case class”, rather than “a callable object”.</span></p><p><span class="yiyi-st" id="yiyi-655">For example, if you have a module <code class="xref py py-mod docutils literal"><span class="pre">SampleTests</span></code> containing a <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>-derived class <code class="xref py py-class docutils literal"><span class="pre">SampleTestCase</span></code> with three test methods (<code class="xref py py-meth docutils literal"><span class="pre">test_one()</span></code>, <code class="xref py py-meth docutils literal"><span class="pre">test_two()</span></code>, and <code class="xref py py-meth docutils literal"><span class="pre">test_three()</span></code>), the specifier <code class="docutils literal"><span class="pre">'SampleTests.SampleTestCase'</span></code> would cause this method to return a suite which will run all three test methods. </span><span class="yiyi-st" id="yiyi-656">Using the specifier <code class="docutils literal"><span class="pre">'SampleTests.SampleTestCase.test_two'</span></code> would cause it to return a test suite which will run only the <code class="xref py py-meth docutils literal"><span class="pre">test_two()</span></code> test method. </span><span class="yiyi-st" id="yiyi-657">The specifier can refer to modules and packages which have not been imported; they will be imported as a side-effect.</span></p><p><span class="yiyi-st" id="yiyi-658">The method optionally resolves <em>name</em> relative to the given <em>module</em>.</span></p></dd></dl><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-659"><span class="versionmodified">Changed in version 3.5: </span>If an <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal"><span class="pre">ImportError</span></code></a> or <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal"><span class="pre">AttributeError</span></code></a> occurs while traversing <em>name</em> then a synthetic test that raises that error when run will be returned. </span><span class="yiyi-st" id="yiyi-660">These errors are included in the errors accumulated by self.errors.</span></p></div><dl class="method"><dt id="unittest.TestLoader.loadTestsFromNames"><span class="yiyi-st" id="yiyi-661"> <code class="descname">loadTestsFromNames</code><span class="sig-paren">(</span><em>names</em>, <em>module=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-662">Similar to <a class="reference internal" href="#unittest.TestLoader.loadTestsFromName" title="unittest.TestLoader.loadTestsFromName"><code class="xref py py-meth docutils literal"><span class="pre">loadTestsFromName()</span></code></a>, but takes a sequence of names rather than a single name. </span><span class="yiyi-st" id="yiyi-663">The return value is a test suite which supports all the tests defined for each name.</span></p></dd></dl><dl class="method"><dt id="unittest.TestLoader.getTestCaseNames"><span class="yiyi-st" id="yiyi-664"> <code class="descname">getTestCaseNames</code><span class="sig-paren">(</span><em>testCaseClass</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-665">Return a sorted sequence of method names found within <em>testCaseClass</em>; this should be a subclass of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>.</span></p></dd></dl><dl class="method"><dt id="unittest.TestLoader.discover"><span class="yiyi-st" id="yiyi-666"> <code class="descname">discover</code><span class="sig-paren">(</span><em>start_dir</em>, <em>pattern='test*.py'</em>, <em>top_level_dir=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-667">Find all the test modules by recursing into subdirectories from the specified start directory, and return a TestSuite object containing them. </span><span class="yiyi-st" id="yiyi-668">Only test files that match <em>pattern</em> will be loaded. </span><span class="yiyi-st" id="yiyi-669">(Using shell style pattern matching.) </span><span class="yiyi-st" id="yiyi-670">Only module names that are importable (i.e. </span><span class="yiyi-st" id="yiyi-671">are valid Python identifiers) will be loaded.</span></p><p><span class="yiyi-st" id="yiyi-672">All test modules must be importable from the top level of the project. </span><span class="yiyi-st" id="yiyi-673">If the start directory is not the top level directory then the top level directory must be specified separately.</span></p><p><span class="yiyi-st" id="yiyi-674">If importing a module fails, for example due to a syntax error, then this will be recorded as a single error and discovery will continue. </span><span class="yiyi-st" id="yiyi-675">If the import failure is due to <a class="reference internal" href="#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal"><span class="pre">SkipTest</span></code></a> being raised, it will be recorded as a skip instead of an error.</span></p><p><span class="yiyi-st" id="yiyi-676">If a package (a directory containing a file named <code class="file docutils literal"><span class="pre">__init__.py</span></code>) is found, the package will be checked for a <code class="docutils literal"><span class="pre">load_tests</span></code> function. </span><span class="yiyi-st" id="yiyi-677">If this exists then it will be called <code class="docutils literal"><span class="pre">package.load_tests(loader,</span> <span class="pre">tests,</span> <span class="pre">pattern)</span></code>. </span><span class="yiyi-st" id="yiyi-678">Test discovery takes care to ensure that a package is only checked for tests once during an invocation, even if the load_tests function itself calls <code class="docutils literal"><span class="pre">loader.discover</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-679">If <code class="docutils literal"><span class="pre">load_tests</span></code> exists then discovery does <em>not</em> recurse into the package, <code class="docutils literal"><span class="pre">load_tests</span></code> is responsible for loading all tests in the package.</span></p><p><span class="yiyi-st" id="yiyi-680">The pattern is deliberately not stored as a loader attribute so that packages can continue discovery themselves. </span><span class="yiyi-st" id="yiyi-681"><em>top_level_dir</em> is stored so <code class="docutils literal"><span class="pre">load_tests</span></code> does not need to pass this argument in to <code class="docutils literal"><span class="pre">loader.discover()</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-682"><em>start_dir</em> can be a dotted module name as well as a directory.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-683"><span class="versionmodified">New in version 3.2.</span></span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-684"><span class="versionmodified">Changed in version 3.4: </span>Modules that raise <a class="reference internal" href="#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal"><span class="pre">SkipTest</span></code></a> on import are recorded as skips, not errors. </span><span class="yiyi-st" id="yiyi-685">Discovery works for <a class="reference internal" href="../glossary.html#term-namespace-package"><span class="xref std std-term">namespace packages</span></a>. </span><span class="yiyi-st" id="yiyi-686">Paths are sorted before being imported so that execution order is the same even if the underlying file system’s ordering is not dependent on file name.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-687"><span class="versionmodified">Changed in version 3.5: </span>Found packages are now checked for <code class="docutils literal"><span class="pre">load_tests</span></code> regardless of whether their path matches <em>pattern</em>, because it is impossible for a package name to match the default pattern.</span></p></div></dd></dl><p><span class="yiyi-st" id="yiyi-688">The following attributes of a <a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> can be configured either by subclassing or assignment on an instance:</span></p><dl class="attribute"><dt id="unittest.TestLoader.testMethodPrefix"><span class="yiyi-st" id="yiyi-689"> <code class="descname">testMethodPrefix</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-690">String giving the prefix of method names which will be interpreted as test methods. </span><span class="yiyi-st" id="yiyi-691">The default value is <code class="docutils literal"><span class="pre">'test'</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-692">This affects <a class="reference internal" href="#unittest.TestLoader.getTestCaseNames" title="unittest.TestLoader.getTestCaseNames"><code class="xref py py-meth docutils literal"><span class="pre">getTestCaseNames()</span></code></a> and all the <code class="xref py py-meth docutils literal"><span class="pre">loadTestsFrom*()</span></code> methods.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestLoader.sortTestMethodsUsing"><span class="yiyi-st" id="yiyi-693"> <code class="descname">sortTestMethodsUsing</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-694">Function to be used to compare method names when sorting them in <a class="reference internal" href="#unittest.TestLoader.getTestCaseNames" title="unittest.TestLoader.getTestCaseNames"><code class="xref py py-meth docutils literal"><span class="pre">getTestCaseNames()</span></code></a> and all the <code class="xref py py-meth docutils literal"><span class="pre">loadTestsFrom*()</span></code> methods.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestLoader.suiteClass"><span class="yiyi-st" id="yiyi-695"> <code class="descname">suiteClass</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-696">Callable object that constructs a test suite from a list of tests. </span><span class="yiyi-st" id="yiyi-697">No methods on the resulting object are needed. </span><span class="yiyi-st" id="yiyi-698">The default value is the <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> class.</span></p><p><span class="yiyi-st" id="yiyi-699">This affects all the <code class="xref py py-meth docutils literal"><span class="pre">loadTestsFrom*()</span></code> methods.</span></p></dd></dl></dd></dl><dl class="class"><dt id="unittest.TestResult"><span class="yiyi-st" id="yiyi-700"> <em class="property">class </em><code class="descclassname">unittest.</code><code class="descname">TestResult</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-701">This class is used to compile information about which tests have succeeded and which have failed.</span></p><p><span class="yiyi-st" id="yiyi-702">A <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> object stores the results of a set of tests. </span><span class="yiyi-st" id="yiyi-703">The <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> and <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> classes ensure that results are properly recorded; test authors do not need to worry about recording the outcome of tests.</span></p><p><span class="yiyi-st" id="yiyi-704">Testing frameworks built on top of <a class="reference internal" href="#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal"><span class="pre">unittest</span></code></a> may want access to the <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> object generated by running a set of tests for reporting purposes; a <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> instance is returned by the <code class="xref py py-meth docutils literal"><span class="pre">TestRunner.run()</span></code> method for this purpose.</span></p><p><span class="yiyi-st" id="yiyi-705"><a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> instances have the following attributes that will be of interest when inspecting the results of running a set of tests:</span></p><dl class="attribute"><dt id="unittest.TestResult.errors"><span class="yiyi-st" id="yiyi-706"> <code class="descname">errors</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-707">A list containing 2-tuples of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances and strings holding formatted tracebacks. </span><span class="yiyi-st" id="yiyi-708">Each tuple represents a test which raised an unexpected exception.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestResult.failures"><span class="yiyi-st" id="yiyi-709"> <code class="descname">failures</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-710">A list containing 2-tuples of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances and strings holding formatted tracebacks. </span><span class="yiyi-st" id="yiyi-711">Each tuple represents a test where a failure was explicitly signalled using the <code class="xref py py-meth docutils literal"><span class="pre">TestCase.assert*()</span></code> methods.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestResult.skipped"><span class="yiyi-st" id="yiyi-712"> <code class="descname">skipped</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-713">A list containing 2-tuples of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances and strings holding the reason for skipping the test.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-714"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="attribute"><dt id="unittest.TestResult.expectedFailures"><span class="yiyi-st" id="yiyi-715"> <code class="descname">expectedFailures</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-716">A list containing 2-tuples of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances and strings holding formatted tracebacks. </span><span class="yiyi-st" id="yiyi-717">Each tuple represents an expected failure of the test case.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestResult.unexpectedSuccesses"><span class="yiyi-st" id="yiyi-718"> <code class="descname">unexpectedSuccesses</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-719">A list containing <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instances that were marked as expected failures, but succeeded.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestResult.shouldStop"><span class="yiyi-st" id="yiyi-720"> <code class="descname">shouldStop</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-721">Set to <code class="docutils literal"><span class="pre">True</span></code> when the execution of tests should stop by <a class="reference internal" href="#unittest.TestResult.stop" title="unittest.TestResult.stop"><code class="xref py py-meth docutils literal"><span class="pre">stop()</span></code></a>.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestResult.testsRun"><span class="yiyi-st" id="yiyi-722"> <code class="descname">testsRun</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-723">The total number of tests run so far.</span></p></dd></dl><dl class="attribute"><dt id="unittest.TestResult.buffer"><span class="yiyi-st" id="yiyi-724"> <code class="descname">buffer</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-725">If set to true, <code class="docutils literal"><span class="pre">sys.stdout</span></code> and <code class="docutils literal"><span class="pre">sys.stderr</span></code> will be buffered in between <a class="reference internal" href="#unittest.TestResult.startTest" title="unittest.TestResult.startTest"><code class="xref py py-meth docutils literal"><span class="pre">startTest()</span></code></a> and <a class="reference internal" href="#unittest.TestResult.stopTest" title="unittest.TestResult.stopTest"><code class="xref py py-meth docutils literal"><span class="pre">stopTest()</span></code></a> being called. </span><span class="yiyi-st" id="yiyi-726">Collected output will only be echoed onto the real <code class="docutils literal"><span class="pre">sys.stdout</span></code> and <code class="docutils literal"><span class="pre">sys.stderr</span></code> if the test fails or errors. </span><span class="yiyi-st" id="yiyi-727">Any output is also attached to the failure / error message.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-728"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="attribute"><dt id="unittest.TestResult.failfast"><span class="yiyi-st" id="yiyi-729"> <code class="descname">failfast</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-730">If set to true <a class="reference internal" href="#unittest.TestResult.stop" title="unittest.TestResult.stop"><code class="xref py py-meth docutils literal"><span class="pre">stop()</span></code></a> will be called on the first failure or error, halting the test run.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-731"><span class="versionmodified">New in version 3.2.</span></span></p></div></dd></dl><dl class="attribute"><dt id="unittest.TestResult.tb_locals"><span class="yiyi-st" id="yiyi-732"> <code class="descname">tb_locals</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-733">If set to true then local variables will be shown in tracebacks.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-734"><span class="versionmodified">New in version 3.5.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestResult.wasSuccessful"><span class="yiyi-st" id="yiyi-735"> <code class="descname">wasSuccessful</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-736">Return <code class="docutils literal"><span class="pre">True</span></code> if all tests run so far have passed, otherwise returns <code class="docutils literal"><span class="pre">False</span></code>.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-737"><span class="versionmodified">Changed in version 3.4: </span>Returns <code class="docutils literal"><span class="pre">False</span></code> if there were any <a class="reference internal" href="#unittest.TestResult.unexpectedSuccesses" title="unittest.TestResult.unexpectedSuccesses"><code class="xref py py-attr docutils literal"><span class="pre">unexpectedSuccesses</span></code></a> from tests marked with the <a class="reference internal" href="#unittest.expectedFailure" title="unittest.expectedFailure"><code class="xref py py-func docutils literal"><span class="pre">expectedFailure()</span></code></a> decorator.</span></p></div></dd></dl><dl class="method"><dt id="unittest.TestResult.stop"><span class="yiyi-st" id="yiyi-738"> <code class="descname">stop</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-739">This method can be called to signal that the set of tests being run should be aborted by setting the <a class="reference internal" href="#unittest.TestResult.shouldStop" title="unittest.TestResult.shouldStop"><code class="xref py py-attr docutils literal"><span class="pre">shouldStop</span></code></a> attribute to <code class="docutils literal"><span class="pre">True</span></code>. </span><span class="yiyi-st" id="yiyi-740"><code class="xref py py-class docutils literal"><span class="pre">TestRunner</span></code> objects should respect this flag and return without running any additional tests.</span></p><p><span class="yiyi-st" id="yiyi-741">For example, this feature is used by the <a class="reference internal" href="#unittest.TextTestRunner" title="unittest.TextTestRunner"><code class="xref py py-class docutils literal"><span class="pre">TextTestRunner</span></code></a> class to stop the test framework when the user signals an interrupt from the keyboard. </span><span class="yiyi-st" id="yiyi-742">Interactive tools which provide <code class="xref py py-class docutils literal"><span class="pre">TestRunner</span></code> implementations can use this in a similar manner.</span></p></dd></dl><p><span class="yiyi-st" id="yiyi-743">The following methods of the <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> class are used to maintain the internal data structures, and may be extended in subclasses to support additional reporting requirements. </span><span class="yiyi-st" id="yiyi-744">This is particularly useful in building tools which support interactive reporting while tests are being run.</span></p><dl class="method"><dt id="unittest.TestResult.startTest"><span class="yiyi-st" id="yiyi-745"> <code class="descname">startTest</code><span class="sig-paren">(</span><em>test</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-746">Called when the test case <em>test</em> is about to be run.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.stopTest"><span class="yiyi-st" id="yiyi-747"> <code class="descname">stopTest</code><span class="sig-paren">(</span><em>test</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-748">Called after the test case <em>test</em> has been executed, regardless of the outcome.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.startTestRun"><span class="yiyi-st" id="yiyi-749"> <code class="descname">startTestRun</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-750">Called once before any tests are executed.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-751"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestResult.stopTestRun"><span class="yiyi-st" id="yiyi-752"> <code class="descname">stopTestRun</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-753">Called once after all tests are executed.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-754"><span class="versionmodified">New in version 3.1.</span></span></p></div></dd></dl><dl class="method"><dt id="unittest.TestResult.addError"><span class="yiyi-st" id="yiyi-755"> <code class="descname">addError</code><span class="sig-paren">(</span><em>test</em>, <em>err</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-756">Called when the test case <em>test</em> raises an unexpected exception. </span><span class="yiyi-st" id="yiyi-757"><em>err</em> is a tuple of the form returned by <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></code></a>: <code class="docutils literal"><span class="pre">(type,</span> <span class="pre">value,</span> <span class="pre">traceback)</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-758">The default implementation appends a tuple <code class="docutils literal"><span class="pre">(test,</span> <span class="pre">formatted_err)</span></code> to the instance’s <a class="reference internal" href="#unittest.TestResult.errors" title="unittest.TestResult.errors"><code class="xref py py-attr docutils literal"><span class="pre">errors</span></code></a> attribute, where <em>formatted_err</em> is a formatted traceback derived from <em>err</em>.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.addFailure"><span class="yiyi-st" id="yiyi-759"> <code class="descname">addFailure</code><span class="sig-paren">(</span><em>test</em>, <em>err</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-760">Called when the test case <em>test</em> signals a failure. </span><span class="yiyi-st" id="yiyi-761"><em>err</em> is a tuple of the form returned by <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></code></a>: <code class="docutils literal"><span class="pre">(type,</span> <span class="pre">value,</span> <span class="pre">traceback)</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-762">The default implementation appends a tuple <code class="docutils literal"><span class="pre">(test,</span> <span class="pre">formatted_err)</span></code> to the instance’s <a class="reference internal" href="#unittest.TestResult.failures" title="unittest.TestResult.failures"><code class="xref py py-attr docutils literal"><span class="pre">failures</span></code></a> attribute, where <em>formatted_err</em> is a formatted traceback derived from <em>err</em>.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.addSuccess"><span class="yiyi-st" id="yiyi-763"> <code class="descname">addSuccess</code><span class="sig-paren">(</span><em>test</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-764">Called when the test case <em>test</em> succeeds.</span></p><p><span class="yiyi-st" id="yiyi-765">The default implementation does nothing.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.addSkip"><span class="yiyi-st" id="yiyi-766"> <code class="descname">addSkip</code><span class="sig-paren">(</span><em>test</em>, <em>reason</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-767">Called when the test case <em>test</em> is skipped. </span><span class="yiyi-st" id="yiyi-768"><em>reason</em> is the reason the test gave for skipping.</span></p><p><span class="yiyi-st" id="yiyi-769">The default implementation appends a tuple <code class="docutils literal"><span class="pre">(test,</span> <span class="pre">reason)</span></code> to the instance’s <a class="reference internal" href="#unittest.TestResult.skipped" title="unittest.TestResult.skipped"><code class="xref py py-attr docutils literal"><span class="pre">skipped</span></code></a> attribute.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.addExpectedFailure"><span class="yiyi-st" id="yiyi-770"> <code class="descname">addExpectedFailure</code><span class="sig-paren">(</span><em>test</em>, <em>err</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-771">Called when the test case <em>test</em> fails, but was marked with the <a class="reference internal" href="#unittest.expectedFailure" title="unittest.expectedFailure"><code class="xref py py-func docutils literal"><span class="pre">expectedFailure()</span></code></a> decorator.</span></p><p><span class="yiyi-st" id="yiyi-772">The default implementation appends a tuple <code class="docutils literal"><span class="pre">(test,</span> <span class="pre">formatted_err)</span></code> to the instance’s <a class="reference internal" href="#unittest.TestResult.expectedFailures" title="unittest.TestResult.expectedFailures"><code class="xref py py-attr docutils literal"><span class="pre">expectedFailures</span></code></a> attribute, where <em>formatted_err</em> is a formatted traceback derived from <em>err</em>.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.addUnexpectedSuccess"><span class="yiyi-st" id="yiyi-773"> <code class="descname">addUnexpectedSuccess</code><span class="sig-paren">(</span><em>test</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-774">Called when the test case <em>test</em> was marked with the <a class="reference internal" href="#unittest.expectedFailure" title="unittest.expectedFailure"><code class="xref py py-func docutils literal"><span class="pre">expectedFailure()</span></code></a> decorator, but succeeded.</span></p><p><span class="yiyi-st" id="yiyi-775">The default implementation appends the test to the instance’s <a class="reference internal" href="#unittest.TestResult.unexpectedSuccesses" title="unittest.TestResult.unexpectedSuccesses"><code class="xref py py-attr docutils literal"><span class="pre">unexpectedSuccesses</span></code></a> attribute.</span></p></dd></dl><dl class="method"><dt id="unittest.TestResult.addSubTest"><span class="yiyi-st" id="yiyi-776"> <code class="descname">addSubTest</code><span class="sig-paren">(</span><em>test</em>, <em>subtest</em>, <em>outcome</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-777">Called when a subtest finishes. </span><span class="yiyi-st" id="yiyi-778"><em>test</em> is the test case corresponding to the test method. </span><span class="yiyi-st" id="yiyi-779"><em>subtest</em> is a custom <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instance describing the subtest.</span></p><p><span class="yiyi-st" id="yiyi-780">If <em>outcome</em> is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal"><span class="pre">None</span></code></a>, the subtest succeeded. </span><span class="yiyi-st" id="yiyi-781">Otherwise, it failed with an exception where <em>outcome</em> is a tuple of the form returned by <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal"><span class="pre">sys.exc_info()</span></code></a>: <code class="docutils literal"><span class="pre">(type,</span> <span class="pre">value,</span> <span class="pre">traceback)</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-782">The default implementation does nothing when the outcome is a success, and records subtest failures as normal failures.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-783"><span class="versionmodified">New in version 3.4.</span></span></p></div></dd></dl></dd></dl><dl class="class"><dt id="unittest.TextTestResult"><span class="yiyi-st" id="yiyi-784"> <em class="property">class </em><code class="descclassname">unittest.</code><code class="descname">TextTestResult</code><span class="sig-paren">(</span><em>stream</em>, <em>descriptions</em>, <em>verbosity</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-785">A concrete implementation of <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> used by the <a class="reference internal" href="#unittest.TextTestRunner" title="unittest.TextTestRunner"><code class="xref py py-class docutils literal"><span class="pre">TextTestRunner</span></code></a>.</span></p><div class="versionadded"><p><span class="yiyi-st" id="yiyi-786"><span class="versionmodified">New in version 3.2: </span>This class was previously named <code class="docutils literal"><span class="pre">_TextTestResult</span></code>. </span><span class="yiyi-st" id="yiyi-787">The old name still exists as an alias but is deprecated.</span></p></div></dd></dl><dl class="data"><dt id="unittest.defaultTestLoader"><span class="yiyi-st" id="yiyi-788"> <code class="descclassname">unittest.</code><code class="descname">defaultTestLoader</code></span></dt><dd><p><span class="yiyi-st" id="yiyi-789">Instance of the <a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> class intended to be shared. </span><span class="yiyi-st" id="yiyi-790">If no customization of the <a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> is needed, this instance can be used instead of repeatedly creating new instances.</span></p></dd></dl><dl class="class"><dt id="unittest.TextTestRunner"><span class="yiyi-st" id="yiyi-791"> <em class="property">class </em><code class="descclassname">unittest.</code><code class="descname">TextTestRunner</code><span class="sig-paren">(</span><em>stream=None</em>, <em>descriptions=True</em>, <em>verbosity=1</em>, <em>failfast=False</em>, <em>buffer=False</em>, <em>resultclass=None</em>, <em>warnings=None</em>, <em>*</em>, <em>tb_locals=False</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-792">A basic test runner implementation that outputs results to a stream. </span><span class="yiyi-st" id="yiyi-793">If <em>stream</em> is <code class="docutils literal"><span class="pre">None</span></code>, the default, <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal"><span class="pre">sys.stderr</span></code></a> is used as the output stream. </span><span class="yiyi-st" id="yiyi-794">This class has a few configurable parameters, but is essentially very simple. </span><span class="yiyi-st" id="yiyi-795">Graphical applications which run test suites should provide alternate implementations. </span><span class="yiyi-st" id="yiyi-796">Such implementations should accept <code class="docutils literal"><span class="pre">**kwargs</span></code> as the interface to construct runners changes when features are added to unittest.</span></p><p><span class="yiyi-st" id="yiyi-797">By default this runner shows <a class="reference internal" href="exceptions.html#DeprecationWarning" title="DeprecationWarning"><code class="xref py py-exc docutils literal"><span class="pre">DeprecationWarning</span></code></a>, <a class="reference internal" href="exceptions.html#PendingDeprecationWarning" title="PendingDeprecationWarning"><code class="xref py py-exc docutils literal"><span class="pre">PendingDeprecationWarning</span></code></a>, <a class="reference internal" href="exceptions.html#ResourceWarning" title="ResourceWarning"><code class="xref py py-exc docutils literal"><span class="pre">ResourceWarning</span></code></a> and <a class="reference internal" href="exceptions.html#ImportWarning" title="ImportWarning"><code class="xref py py-exc docutils literal"><span class="pre">ImportWarning</span></code></a> even if they are <a class="reference internal" href="warnings.html#warning-ignored"><span>ignored by default</span></a>. </span><span class="yiyi-st" id="yiyi-798">Deprecation warnings caused by <a class="reference internal" href="#deprecated-aliases"><span>deprecated unittest methods</span></a> are also special-cased and, when the warning filters are <code class="docutils literal"><span class="pre">'default'</span></code> or <code class="docutils literal"><span class="pre">'always'</span></code>, they will appear only once per-module, in order to avoid too many warning messages. </span><span class="yiyi-st" id="yiyi-799">This behavior can be overridden using the <code class="xref std std-option docutils literal"><span class="pre">-Wd</span></code> or <code class="xref std std-option docutils literal"><span class="pre">-Wa</span></code> options and leaving <em>warnings</em> to <code class="docutils literal"><span class="pre">None</span></code>.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-800"><span class="versionmodified">Changed in version 3.2: </span>Added the <code class="docutils literal"><span class="pre">warnings</span></code> argument.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-801"><span class="versionmodified">Changed in version 3.2: </span>The default stream is set to <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal"><span class="pre">sys.stderr</span></code></a> at instantiation time rather than import time.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-802"><span class="versionmodified">Changed in version 3.5: </span>Added the tb_locals parameter.</span></p></div><dl class="method"><dt id="unittest.TextTestRunner._makeResult"><span class="yiyi-st" id="yiyi-803"> <code class="descname">_makeResult</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-804">This method returns the instance of <code class="docutils literal"><span class="pre">TestResult</span></code> used by <a class="reference internal" href="#unittest.TextTestRunner.run" title="unittest.TextTestRunner.run"><code class="xref py py-meth docutils literal"><span class="pre">run()</span></code></a>. </span><span class="yiyi-st" id="yiyi-805">It is not intended to be called directly, but can be overridden in subclasses to provide a custom <code class="docutils literal"><span class="pre">TestResult</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-806"><code class="docutils literal"><span class="pre">_makeResult()</span></code> instantiates the class or callable passed in the <code class="docutils literal"><span class="pre">TextTestRunner</span></code> constructor as the <code class="docutils literal"><span class="pre">resultclass</span></code> argument. </span><span class="yiyi-st" id="yiyi-807">It defaults to <a class="reference internal" href="#unittest.TextTestResult" title="unittest.TextTestResult"><code class="xref py py-class docutils literal"><span class="pre">TextTestResult</span></code></a> if no <code class="docutils literal"><span class="pre">resultclass</span></code> is provided. </span><span class="yiyi-st" id="yiyi-808">The result class is instantiated with the following arguments:</span></p><pre><code class="language-python"><span></span><span class="n">stream</span><span class="p">,</span> <span class="n">descriptions</span><span class="p">,</span> <span class="n">verbosity</span>
</code></pre></dd></dl><dl class="method"><dt id="unittest.TextTestRunner.run"><span class="yiyi-st" id="yiyi-809"> <code class="descname">run</code><span class="sig-paren">(</span><em>test</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-810">This method is the main public interface to the <cite>TextTestRunner</cite>. </span><span class="yiyi-st" id="yiyi-811">This method takes a <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> or <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> instance. </span><span class="yiyi-st" id="yiyi-812">A <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> is created by calling <a class="reference internal" href="#unittest.TextTestRunner._makeResult" title="unittest.TextTestRunner._makeResult"><code class="xref py py-func docutils literal"><span class="pre">_makeResult()</span></code></a> and the test(s) are run and the results printed to stdout.</span></p></dd></dl></dd></dl><dl class="function"><dt id="unittest.main"><span class="yiyi-st" id="yiyi-813"> <code class="descclassname">unittest.</code><code class="descname">main</code><span class="sig-paren">(</span><em>module='__main__'</em>, <em>defaultTest=None</em>, <em>argv=None</em>, <em>testRunner=None</em>, <em>testLoader=unittest.defaultTestLoader</em>, <em>exit=True</em>, <em>verbosity=1</em>, <em>failfast=None</em>, <em>catchbreak=None</em>, <em>buffer=None</em>, <em>warnings=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-814">A command-line program that loads a set of tests from <em>module</em> and runs them; this is primarily for making test modules conveniently executable. </span><span class="yiyi-st" id="yiyi-815">The simplest use for this function is to include the following line at the end of a test script:</span></p><pre><code class="language-python"><span></span><span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>
<span class="n">unittest</span><span class="o">.</span><span class="n">main</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-816">You can run tests with more detailed information by passing in the verbosity argument:</span></p><pre><code class="language-python"><span></span><span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s1">'__main__'</span><span class="p">:</span>
<span class="n">unittest</span><span class="o">.</span><span class="n">main</span><span class="p">(</span><span class="n">verbosity</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-817">The <em>defaultTest</em> argument is either the name of a single test or an iterable of test names to run if no test names are specified via <em>argv</em>. </span><span class="yiyi-st" id="yiyi-818">If not specified or <code class="docutils literal"><span class="pre">None</span></code> and no test names are provided via <em>argv</em>, all tests found in <em>module</em> are run.</span></p><p><span class="yiyi-st" id="yiyi-819">The <em>argv</em> argument can be a list of options passed to the program, with the first element being the program name. </span><span class="yiyi-st" id="yiyi-820">If not specified or <code class="docutils literal"><span class="pre">None</span></code>, the values of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal"><span class="pre">sys.argv</span></code></a> are used.</span></p><p><span class="yiyi-st" id="yiyi-821">The <em>testRunner</em> argument can either be a test runner class or an already created instance of it. </span><span class="yiyi-st" id="yiyi-822">By default <code class="docutils literal"><span class="pre">main</span></code> calls <a class="reference internal" href="sys.html#sys.exit" title="sys.exit"><code class="xref py py-func docutils literal"><span class="pre">sys.exit()</span></code></a> with an exit code indicating success or failure of the tests run.</span></p><p><span class="yiyi-st" id="yiyi-823">The <em>testLoader</em> argument has to be a <a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> instance, and defaults to <a class="reference internal" href="#unittest.defaultTestLoader" title="unittest.defaultTestLoader"><code class="xref py py-data docutils literal"><span class="pre">defaultTestLoader</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-824"><code class="docutils literal"><span class="pre">main</span></code> supports being used from the interactive interpreter by passing in the argument <code class="docutils literal"><span class="pre">exit=False</span></code>. </span><span class="yiyi-st" id="yiyi-825">This displays the result on standard output without calling <a class="reference internal" href="sys.html#sys.exit" title="sys.exit"><code class="xref py py-func docutils literal"><span class="pre">sys.exit()</span></code></a>:</span></p><pre><code class="language-python"><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">unittest</span> <span class="k">import</span> <span class="n">main</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">main</span><span class="p">(</span><span class="n">module</span><span class="o">=</span><span class="s1">'test_module'</span><span class="p">,</span> <span class="n">exit</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-826">The <em>failfast</em>, <em>catchbreak</em> and <em>buffer</em> parameters have the same effect as the same-name <a class="reference internal" href="#command-line-options">command-line options</a>.</span></p><p><span class="yiyi-st" id="yiyi-827">The <em>warning</em> argument specifies the <a class="reference internal" href="warnings.html#warning-filter"><span>warning filter</span></a> that should be used while running the tests. </span><span class="yiyi-st" id="yiyi-828">If it’s not specified, it will remain <code class="docutils literal"><span class="pre">None</span></code> if a <code class="xref std std-option docutils literal"><span class="pre">-W</span></code> option is passed to <strong class="program">python</strong>, otherwise it will be set to <code class="docutils literal"><span class="pre">'default'</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-829">Calling <code class="docutils literal"><span class="pre">main</span></code> actually returns an instance of the <code class="docutils literal"><span class="pre">TestProgram</span></code> class. </span><span class="yiyi-st" id="yiyi-830">This stores the result of the tests run as the <code class="docutils literal"><span class="pre">result</span></code> attribute.</span></p><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-831"><span class="versionmodified">Changed in version 3.1: </span>The <em>exit</em> parameter was added.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-832"><span class="versionmodified">Changed in version 3.2: </span>The <em>verbosity</em>, <em>failfast</em>, <em>catchbreak</em>, <em>buffer</em> and <em>warnings</em> parameters were added.</span></p></div><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-833"><span class="versionmodified">Changed in version 3.4: </span>The <em>defaultTest</em> parameter was changed to also accept an iterable of test names.</span></p></div></dd></dl><div class="section" id="load-tests-protocol"><h4><span class="yiyi-st" id="yiyi-834">26.4.8.3.1. load_tests Protocol</span></h4><div class="versionadded"><p><span class="yiyi-st" id="yiyi-835"><span class="versionmodified">New in version 3.2.</span></span></p></div><p><span class="yiyi-st" id="yiyi-836">Modules or packages can customize how tests are loaded from them during normal test runs or test discovery by implementing a function called <code class="docutils literal"><span class="pre">load_tests</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-837">If a test module defines <code class="docutils literal"><span class="pre">load_tests</span></code> it will be called by <a class="reference internal" href="#unittest.TestLoader.loadTestsFromModule" title="unittest.TestLoader.loadTestsFromModule"><code class="xref py py-meth docutils literal"><span class="pre">TestLoader.loadTestsFromModule()</span></code></a> with the following arguments:</span></p><pre><code class="language-python"><span></span><span class="n">load_tests</span><span class="p">(</span><span class="n">loader</span><span class="p">,</span> <span class="n">standard_tests</span><span class="p">,</span> <span class="n">pattern</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-838">where <em>pattern</em> is passed straight through from <code class="docutils literal"><span class="pre">loadTestsFromModule</span></code>. </span><span class="yiyi-st" id="yiyi-839">It defaults to <code class="docutils literal"><span class="pre">None</span></code>.</span></p><p><span class="yiyi-st" id="yiyi-840">It should return a <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a>.</span></p><p><span class="yiyi-st" id="yiyi-841"><em>loader</em> is the instance of <a class="reference internal" href="#unittest.TestLoader" title="unittest.TestLoader"><code class="xref py py-class docutils literal"><span class="pre">TestLoader</span></code></a> doing the loading. </span><span class="yiyi-st" id="yiyi-842"><em>standard_tests</em> are the tests that would be loaded by default from the module. </span><span class="yiyi-st" id="yiyi-843">It is common for test modules to only want to add or remove tests from the standard set of tests. </span><span class="yiyi-st" id="yiyi-844">The third argument is used when loading packages as part of test discovery.</span></p><p><span class="yiyi-st" id="yiyi-845">A typical <code class="docutils literal"><span class="pre">load_tests</span></code> function that loads tests from a specific set of <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> classes may look like:</span></p><pre><code class="language-python"><span></span><span class="n">test_cases</span> <span class="o">=</span> <span class="p">(</span><span class="n">TestCase1</span><span class="p">,</span> <span class="n">TestCase2</span><span class="p">,</span> <span class="n">TestCase3</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">load_tests</span><span class="p">(</span><span class="n">loader</span><span class="p">,</span> <span class="n">tests</span><span class="p">,</span> <span class="n">pattern</span><span class="p">):</span>
<span class="n">suite</span> <span class="o">=</span> <span class="n">TestSuite</span><span class="p">()</span>
<span class="k">for</span> <span class="n">test_class</span> <span class="ow">in</span> <span class="n">test_cases</span><span class="p">:</span>
<span class="n">tests</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="n">loadTestsFromTestCase</span><span class="p">(</span><span class="n">test_class</span><span class="p">)</span>
<span class="n">suite</span><span class="o">.</span><span class="n">addTests</span><span class="p">(</span><span class="n">tests</span><span class="p">)</span>
<span class="k">return</span> <span class="n">suite</span>
</code></pre><p><span class="yiyi-st" id="yiyi-846">If discovery is started in a directory containing a package, either from the command line or by calling <a class="reference internal" href="#unittest.TestLoader.discover" title="unittest.TestLoader.discover"><code class="xref py py-meth docutils literal"><span class="pre">TestLoader.discover()</span></code></a>, then the package <code class="file docutils literal"><span class="pre">__init__.py</span></code> will be checked for <code class="docutils literal"><span class="pre">load_tests</span></code>. </span><span class="yiyi-st" id="yiyi-847">If that function does not exist, discovery will recurse into the package as though it were just another directory. </span><span class="yiyi-st" id="yiyi-848">Otherwise, discovery of the package’s tests will be left up to <code class="docutils literal"><span class="pre">load_tests</span></code> which is called with the following arguments:</span></p><pre><code class="language-python"><span></span><span class="n">load_tests</span><span class="p">(</span><span class="n">loader</span><span class="p">,</span> <span class="n">standard_tests</span><span class="p">,</span> <span class="n">pattern</span><span class="p">)</span>
</code></pre><p><span class="yiyi-st" id="yiyi-849">This should return a <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a> representing all the tests from the package. </span><span class="yiyi-st" id="yiyi-850">(<code class="docutils literal"><span class="pre">standard_tests</span></code> will only contain tests collected from <code class="file docutils literal"><span class="pre">__init__.py</span></code>.)</span></p><p><span class="yiyi-st" id="yiyi-851">Because the pattern is passed into <code class="docutils literal"><span class="pre">load_tests</span></code> the package is free to continue (and potentially modify) test discovery. </span><span class="yiyi-st" id="yiyi-852">A ‘do nothing’ <code class="docutils literal"><span class="pre">load_tests</span></code> function for a test package would look like:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">load_tests</span><span class="p">(</span><span class="n">loader</span><span class="p">,</span> <span class="n">standard_tests</span><span class="p">,</span> <span class="n">pattern</span><span class="p">):</span>
<span class="c1"># top level directory cached on loader instance</span>
<span class="n">this_dir</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">__file__</span><span class="p">)</span>
<span class="n">package_tests</span> <span class="o">=</span> <span class="n">loader</span><span class="o">.</span><span class="n">discover</span><span class="p">(</span><span class="n">start_dir</span><span class="o">=</span><span class="n">this_dir</span><span class="p">,</span> <span class="n">pattern</span><span class="o">=</span><span class="n">pattern</span><span class="p">)</span>
<span class="n">standard_tests</span><span class="o">.</span><span class="n">addTests</span><span class="p">(</span><span class="n">package_tests</span><span class="p">)</span>
<span class="k">return</span> <span class="n">standard_tests</span>
</code></pre><div class="versionchanged"><p><span class="yiyi-st" id="yiyi-853"><span class="versionmodified">Changed in version 3.5: </span>Discovery no longer checks package names for matching <em>pattern</em> due to the impossibility of package names matching the default pattern.</span></p></div></div></div></div><div class="section" id="class-and-module-fixtures"><h2><span class="yiyi-st" id="yiyi-854">26.4.9. </span><span class="yiyi-st" id="yiyi-855">Class and Module Fixtures</span></h2><p><span class="yiyi-st" id="yiyi-856">Class and module level fixtures are implemented in <a class="reference internal" href="#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal"><span class="pre">TestSuite</span></code></a>. </span><span class="yiyi-st" id="yiyi-857">When the test suite encounters a test from a new class then <code class="xref py py-meth docutils literal"><span class="pre">tearDownClass()</span></code> from the previous class (if there is one) is called, followed by <code class="xref py py-meth docutils literal"><span class="pre">setUpClass()</span></code> from the new class.</span></p><p><span class="yiyi-st" id="yiyi-858">Similarly if a test is from a different module from the previous test then <code class="docutils literal"><span class="pre">tearDownModule</span></code> from the previous module is run, followed by <code class="docutils literal"><span class="pre">setUpModule</span></code> from the new module.</span></p><p><span class="yiyi-st" id="yiyi-859">After all the tests have run the final <code class="docutils literal"><span class="pre">tearDownClass</span></code> and <code class="docutils literal"><span class="pre">tearDownModule</span></code> are run.</span></p><p><span class="yiyi-st" id="yiyi-860">Note that shared fixtures do not play well with [potential] features like test parallelization and they break test isolation. </span><span class="yiyi-st" id="yiyi-861">They should be used with care.</span></p><p><span class="yiyi-st" id="yiyi-862">The default ordering of tests created by the unittest test loaders is to group all tests from the same modules and classes together. </span><span class="yiyi-st" id="yiyi-863">This will lead to <code class="docutils literal"><span class="pre">setUpClass</span></code> / <code class="docutils literal"><span class="pre">setUpModule</span></code> (etc) being called exactly once per class and module. </span><span class="yiyi-st" id="yiyi-864">If you randomize the order, so that tests from different modules and classes are adjacent to each other, then these shared fixture functions may be called multiple times in a single test run.</span></p><p><span class="yiyi-st" id="yiyi-865">Shared fixtures are not intended to work with suites with non-standard ordering. </span><span class="yiyi-st" id="yiyi-866">A <code class="docutils literal"><span class="pre">BaseTestSuite</span></code> still exists for frameworks that don’t want to support shared fixtures.</span></p><p><span class="yiyi-st" id="yiyi-867">If there are any exceptions raised during one of the shared fixture functions the test is reported as an error. </span><span class="yiyi-st" id="yiyi-868">Because there is no corresponding test instance an <code class="docutils literal"><span class="pre">_ErrorHolder</span></code> object (that has the same interface as a <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a>) is created to represent the error. </span><span class="yiyi-st" id="yiyi-869">If you are just using the standard unittest test runner then this detail doesn’t matter, but if you are a framework author it may be relevant.</span></p><div class="section" id="setupclass-and-teardownclass"><h3><span class="yiyi-st" id="yiyi-870">26.4.9.1. setUpClass and tearDownClass</span></h3><p><span class="yiyi-st" id="yiyi-871">These must be implemented as class methods:</span></p><pre><code class="language-python"><span></span><span class="kn">import</span> <span class="nn">unittest</span>
<span class="k">class</span> <span class="nc">Test</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>
<span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">setUpClass</span><span class="p">(</span><span class="n">cls</span><span class="p">):</span>
<span class="n">cls</span><span class="o">.</span><span class="n">_connection</span> <span class="o">=</span> <span class="n">createExpensiveConnectionObject</span><span class="p">()</span>
<span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">tearDownClass</span><span class="p">(</span><span class="n">cls</span><span class="p">):</span>
<span class="n">cls</span><span class="o">.</span><span class="n">_connection</span><span class="o">.</span><span class="n">destroy</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-872">If you want the <code class="docutils literal"><span class="pre">setUpClass</span></code> and <code class="docutils literal"><span class="pre">tearDownClass</span></code> on base classes called then you must call up to them yourself. </span><span class="yiyi-st" id="yiyi-873">The implementations in <a class="reference internal" href="#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal"><span class="pre">TestCase</span></code></a> are empty.</span></p><p><span class="yiyi-st" id="yiyi-874">If an exception is raised during a <code class="docutils literal"><span class="pre">setUpClass</span></code> then the tests in the class are not run and the <code class="docutils literal"><span class="pre">tearDownClass</span></code> is not run. </span><span class="yiyi-st" id="yiyi-875">Skipped classes will not have <code class="docutils literal"><span class="pre">setUpClass</span></code> or <code class="docutils literal"><span class="pre">tearDownClass</span></code> run. </span><span class="yiyi-st" id="yiyi-876">If the exception is a <a class="reference internal" href="#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal"><span class="pre">SkipTest</span></code></a> exception then the class will be reported as having been skipped instead of as an error.</span></p></div><div class="section" id="setupmodule-and-teardownmodule"><h3><span class="yiyi-st" id="yiyi-877">26.4.9.2. setUpModule and tearDownModule</span></h3><p><span class="yiyi-st" id="yiyi-878">These should be implemented as functions:</span></p><pre><code class="language-python"><span></span><span class="k">def</span> <span class="nf">setUpModule</span><span class="p">():</span>
<span class="n">createConnection</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">tearDownModule</span><span class="p">():</span>
<span class="n">closeConnection</span><span class="p">()</span>
</code></pre><p><span class="yiyi-st" id="yiyi-879">If an exception is raised in a <code class="docutils literal"><span class="pre">setUpModule</span></code> then none of the tests in the module will be run and the <code class="docutils literal"><span class="pre">tearDownModule</span></code> will not be run. </span><span class="yiyi-st" id="yiyi-880">If the exception is a <a class="reference internal" href="#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal"><span class="pre">SkipTest</span></code></a> exception then the module will be reported as having been skipped instead of as an error.</span></p></div></div><div class="section" id="signal-handling"><h2><span class="yiyi-st" id="yiyi-881">26.4.10. </span><span class="yiyi-st" id="yiyi-882">Signal Handling</span></h2><div class="versionadded"><p><span class="yiyi-st" id="yiyi-883"><span class="versionmodified">New in version 3.2.</span></span></p></div><p><span class="yiyi-st" id="yiyi-884">The <a class="reference internal" href="#cmdoption-unittest-c"><code class="xref std std-option docutils literal"><span class="pre">-c/--catch</span></code></a> command-line option to unittest, along with the <code class="docutils literal"><span class="pre">catchbreak</span></code> parameter to <a class="reference internal" href="#unittest.main" title="unittest.main"><code class="xref py py-func docutils literal"><span class="pre">unittest.main()</span></code></a>, provide more friendly handling of control-C during a test run. </span><span class="yiyi-st" id="yiyi-885">With catch break behavior enabled control-C will allow the currently running test to complete, and the test run will then end and report all the results so far. </span><span class="yiyi-st" id="yiyi-886">A second control-c will raise a <a class="reference internal" href="exceptions.html#KeyboardInterrupt" title="KeyboardInterrupt"><code class="xref py py-exc docutils literal"><span class="pre">KeyboardInterrupt</span></code></a> in the usual way.</span></p><p><span class="yiyi-st" id="yiyi-887">The control-c handling signal handler attempts to remain compatible with code or tests that install their own <code class="xref py py-const docutils literal"><span class="pre">signal.SIGINT</span></code> handler. </span><span class="yiyi-st" id="yiyi-888">If the <code class="docutils literal"><span class="pre">unittest</span></code> handler is called but <em>isn’t</em> the installed <code class="xref py py-const docutils literal"><span class="pre">signal.SIGINT</span></code> handler, i.e. </span><span class="yiyi-st" id="yiyi-889">it has been replaced by the system under test and delegated to, then it calls the default handler. </span><span class="yiyi-st" id="yiyi-890">This will normally be the expected behavior by code that replaces an installed handler and delegates to it. </span><span class="yiyi-st" id="yiyi-891">For individual tests that need <code class="docutils literal"><span class="pre">unittest</span></code> control-c handling disabled the <a class="reference internal" href="#unittest.removeHandler" title="unittest.removeHandler"><code class="xref py py-func docutils literal"><span class="pre">removeHandler()</span></code></a> decorator can be used.</span></p><p><span class="yiyi-st" id="yiyi-892">There are a few utility functions for framework authors to enable control-c handling functionality within test frameworks.</span></p><dl class="function"><dt id="unittest.installHandler"><span class="yiyi-st" id="yiyi-893"> <code class="descclassname">unittest.</code><code class="descname">installHandler</code><span class="sig-paren">(</span><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-894">Install the control-c handler. </span><span class="yiyi-st" id="yiyi-895">When a <code class="xref py py-const docutils literal"><span class="pre">signal.SIGINT</span></code> is received (usually in response to the user pressing control-c) all registered results have <a class="reference internal" href="#unittest.TestResult.stop" title="unittest.TestResult.stop"><code class="xref py py-meth docutils literal"><span class="pre">stop()</span></code></a> called.</span></p></dd></dl><dl class="function"><dt id="unittest.registerResult"><span class="yiyi-st" id="yiyi-896"> <code class="descclassname">unittest.</code><code class="descname">registerResult</code><span class="sig-paren">(</span><em>result</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-897">Register a <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> object for control-c handling. </span><span class="yiyi-st" id="yiyi-898">Registering a result stores a weak reference to it, so it doesn’t prevent the result from being garbage collected.</span></p><p><span class="yiyi-st" id="yiyi-899">Registering a <a class="reference internal" href="#unittest.TestResult" title="unittest.TestResult"><code class="xref py py-class docutils literal"><span class="pre">TestResult</span></code></a> object has no side-effects if control-c handling is not enabled, so test frameworks can unconditionally register all results they create independently of whether or not handling is enabled.</span></p></dd></dl><dl class="function"><dt id="unittest.removeResult"><span class="yiyi-st" id="yiyi-900"> <code class="descclassname">unittest.</code><code class="descname">removeResult</code><span class="sig-paren">(</span><em>result</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-901">Remove a registered result. </span><span class="yiyi-st" id="yiyi-902">Once a result has been removed then <a class="reference internal" href="#unittest.TestResult.stop" title="unittest.TestResult.stop"><code class="xref py py-meth docutils literal"><span class="pre">stop()</span></code></a> will no longer be called on that result object in response to a control-c.</span></p></dd></dl><dl class="function"><dt id="unittest.removeHandler"><span class="yiyi-st" id="yiyi-903"> <code class="descclassname">unittest.</code><code class="descname">removeHandler</code><span class="sig-paren">(</span><em>function=None</em><span class="sig-paren">)</span></span></dt><dd><p><span class="yiyi-st" id="yiyi-904">When called without arguments this function removes the control-c handler if it has been installed. </span><span class="yiyi-st" id="yiyi-905">This function can also be used as a test decorator to temporarily remove the handler whilst the test is being executed:</span></p><pre><code class="language-python"><span></span><span class="nd">@unittest</span><span class="o">.</span><span class="n">removeHandler</span>
<span class="k">def</span> <span class="nf">test_signal_handling</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="o">...</span>
</code></pre></dd></dl></div></div></div>
Reference in New Issue View Git Blame Copy Permalink