查看“Python/docs/3.10/library/unittest”的源代码

{{DISPLAYTITLE:unittest — 单元测试框架 — Python 文档}}
<div id="module-unittest" class="section">

<span id="unittest-unit-testing-framework"></span>
= unittest — 单元测试框架 =

'''源代码：''' [[#id1|<span id="id2" class="problematic">:source:`Lib/unittest/__init__.py`</span>]]


-----

（如果您已经熟悉测试的基本概念，您可能需要跳到 [[#assert-methods|断言方法列表]] 。）

[[#module-unittest|unittest]] 单元测试框架最初受到 JUnit 的启发，与其他语言的主要单元测试框架具有相似的风格。 它支持测试自动化、共享测试的设置和关闭代码、将测试聚合到集合中以及测试独立于报告框架。

为了实现这一点，[[#module-unittest|unittest]] 以面向对象的方式支持一些重要的概念：

; 测试夹具
: ''测试装置'' 表示执行一个或多个测试所需的准备工作，以及任何相关的清理操作。 例如，这可能涉及创建临时或代理数据库、目录或启动服务器进程。
; 测试用例
: ''测试用例'' 是单独的测试单元。 它检查对特定输入集的特定响应。 [[#module-unittest|unittest]] 提供了一个基类，[[#unittest.TestCase|TestCase]]，可用于创建新的测试用例。
; 测试套件
: ''测试套件'' 是测试用例、测试套件或两者的集合。 它用于聚合应该一起执行的测试。
; 测试运行器
: ''测试运行器'' 是一个组件，用于协调测试的执行并向用户提供结果。 运行器可以使用图形界面、文本界面或返回一个特殊值来指示执行测试的结果。

<div class="admonition seealso">

也可以看看

; 模块 [[../doctest#module-doctest|doctest]]
: 另一个具有非常不同风格的测试支持模块。
; [https://web.archive.org/web/20150315073817/http://www.xprogramming.com/testfram.htm 简单的 Smalltalk 测试：使用模式]
: Kent Beck 关于使用 [[#module-unittest|unittest]] 共享模式的测试框架的原始论文。
; [https://docs.pytest.org/ pytest]
: 第三方单元测试框架，具有用于编写测试的轻量级语法。 例如，<code>assert func(10) == 42</code>。
; [https://wiki.python.org/moin/PythonTestingToolsTaxonomy Python 测试工具分类法]
: Python 测试工具的广泛列表，包括功能测试框架和模拟对象库。
; [http://lists.idyll.org/listinfo/testing-in-python 在 Python 邮件列表中测试]
: 在 Python 中讨论测试和测试工具的特殊兴趣小组。

Python源代码分发中的脚本<code>Tools/unittestgui/unittestgui.py</code>是一个用于测试发现和执行的GUI工具。 这主要是为了便于那些不熟悉单元测试的人使用。 对于生产环境，建议测试由持续集成系统驱动，例如 [https://buildbot.net/ Buildbot]、[https://jenkins.io/ Jenkins] 或 [https://travis-ci.com Travis-CI] 或 [https://www.appveyor.com/ AppVeyor] ]。


</div>
<div id="basic-example" class="section">

<span id="unittest-minimal-example"></span>
== 基本示例 ==

[[#module-unittest|unittest]] 模块提供了一套丰富的工具来构建和运行测试。 本节展示了一小部分工具足以满足大多数用户的需求。

这是测试三个字符串方法的简短脚本：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">import unittest

class TestStringMethods(unittest.TestCase):

    def test_upper(self):
        self.assertEqual('foo'.upper(), 'FOO')

    def test_isupper(self):
        self.assertTrue('FOO'.isupper())
        self.assertFalse('Foo'.isupper())

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', 'world'])
        # check that s.split fails when the separator is not a string
        with self.assertRaises(TypeError):
            s.split(2)

if __name__ == '__main__':
    unittest.main()</syntaxhighlight>

</div>

</div>
测试用例是通过子类化 [[#unittest.TestCase|unittest.TestCase]] 创建的。 这三个单独的测试是用名称以字母 <code>test</code> 开头的方法定义的。 此命名约定通知测试运行器哪些方法代表测试。

每个测试的关键是调用 [[#unittest.TestCase.assertEqual|assertEqual()]] 以检查预期结果； [[#unittest.TestCase.assertTrue|assertTrue()]] 或 [[#unittest.TestCase.assertFalse|assertFalse()]] 验证条件； 或 [[#unittest.TestCase.assertRaises|assertRaises()]] 以验证是否引发了特定异常。 这些方法用于代替 [[../../reference/simple_stmts#assert|assert]] 语句，因此测试运行器可以累积所有测试结果并生成报告。

[[#unittest.TestCase.setUp|setUp()]] 和 [[#unittest.TestCase.tearDown|tearDown()]] 方法允许您定义将在每个测试方法之前和之后执行的指令。 它们在 [[#organizing-tests|组织测试代码]] 部分有更详细的介绍。

最后一个块显示了运行测试的简单方法。 [[#unittest.main|unittest.main()]] 为测试脚本提供命令行界面。 从命令行运行时，上面的脚本会生成如下所示的输出：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK</syntaxhighlight>

</div>

</div>
将 <code>-v</code> 选项传递给您的测试脚本将指示 [[#unittest.main|unittest.main()]] 启用更高级别的详细信息，并产生以下输出：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">test_isupper (__main__.TestStringMethods) ... ok
test_split (__main__.TestStringMethods) ... ok
test_upper (__main__.TestStringMethods) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK</syntaxhighlight>

</div>

</div>
上面的例子展示了最常用的 [[#module-unittest|unittest]] 特性，这些特性足以满足许多日常测试需求。 文档的其余部分从首要原则探索了完整的功能集。


</div>
<div id="command-line-interface" class="section">

<span id="unittest-command-line-interface"></span>
== 命令行界面 ==

可以从命令行使用 unittest 模块从模块、类甚至单个测试方法运行测试：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method</syntaxhighlight>

</div>

</div>
您可以传入包含模块名称和完全限定类或方法名称的任意组合的列表。

测试模块也可以通过文件路径指定：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">python -m unittest tests/test_something.py</syntaxhighlight>

</div>

</div>
这允许您使用 shell 文件名完成来指定测试模块。 指定的文件必须仍可作为模块导入。 通过删除“.py”并将路径分隔符转换为“.”，将路径转换为模块名称。 如果要执行不可作为模块导入的测试文件，则应直接执行该文件。

您可以通过传入 -v 标志来运行更详细（更详细）的测试：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">python -m unittest -v test_module</syntaxhighlight>

</div>

</div>
当不带参数执行时 [[#unittest-test-discovery|Test Discovery]] 启动：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">python -m unittest</syntaxhighlight>

</div>

</div>
有关所有命令行选项的列表：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">python -m unittest -h</syntaxhighlight>

</div>

</div>
<div class="versionchanged">

<span class="versionmodified changed"> 3.2 版更改： </span> 在早期版本中，只能运行单独的测试方法，而不能运行模块或类。


</div>
<div id="command-line-options" class="section">

=== 命令行选项 ===

'''unittest''' 支持这些命令行选项：

; <span id="cmdoption-unittest-buffer"></span><span class="sig-name descname"><span class="pre">-b</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--buffer</span></span><span class="sig-prename descclassname"></span>
: 标准输出和标准错误流在测试运行期间被缓冲。 通过测试期间的输出将被丢弃。 输出在测试失败或错误时正常回显，并添加到失败消息中。

<dl>
<dt><span id="cmdoption-unittest-catch"></span><span class="sig-name descname"><span class="pre">-c</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--catch</span></span><span class="sig-prename descclassname"></span></dt>
<dd><p><span class="kbd kbd compound docutils literal notranslate">Control-C</span> 在测试运行期间等待当前测试结束，然后报告到目前为止的所有结果。 第二个 <span class="kbd kbd compound docutils literal notranslate">Control-C</span> 引发正常的 [[../exceptions#KeyboardInterrupt|KeyboardInterrupt]] 异常。</p>
<p>有关提供此功能的函数，请参阅 [[#signal-handling|信号处理]] 。</p></dd></dl>

; <span id="cmdoption-unittest-failfast"></span><span class="sig-name descname"><span class="pre">-f</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--failfast</span></span><span class="sig-prename descclassname"></span>
: 在第一个错误或失败时停止测试运行。

<dl>
<dt><span class="sig-name descname"><span class="pre">-k</span></span><span class="sig-prename descclassname"></span></dt>
<dd><p>仅运行与模式或子字符串匹配的测试方法和类。 此选项可以多次使用，在这种情况下，所有与任何给定模式匹配的测试用例都包括在内。</p>
<p>使用 [[../fnmatch#fnmatch|fnmatch.fnmatchcase()]] 将包含通配符 (<code>*</code>) 的模式与测试名称进行匹配； 否则使用简单的区分大小写的子字符串匹配。</p>
<p>模式与测试加载器导入的完全限定的测试方法名称匹配。</p>
<p>例如，<code>-k foo</code> 匹配 <code>foo_tests.SomeTest.test_something</code>、<code>bar_tests.SomeTest.test_foo</code>，但不匹配 <code>bar_tests.FooTest.test_something</code>。</p></dd></dl>

; <span class="sig-name descname"><span class="pre">--locals</span></span><span class="sig-prename descclassname"></span>
: 在回溯中显示局部变量。

<div class="versionadded">

<span class="versionmodified added"> 3.2 新功能： </span> 添加了命令行选项 <code>-b</code>、<code>-c</code> 和 <code>-f</code>。


</div>
<div class="versionadded">

<span class="versionmodified added">3.5 新功能：</span>命令行选项<code>--locals</code>。


</div>
<div class="versionadded">

<span class="versionmodified added">3.7 版新功能：</span>命令行选项<code>-k</code>。


</div>
命令行也可用于测试发现、运行项目中的所有测试或仅运行一个子集。


</div>

</div>
<div id="test-discovery" class="section">

<span id="unittest-test-discovery"></span>
== 测试发现 ==

<div class="versionadded">

<span class="versionmodified added">3.2 版中的新功能。</span>


</div>
Unittest 支持简单的测试发现。 为了兼容测试发现，所有的测试文件必须是 [[../../tutorial/modules#tut-modules|modules]] 或 [[../../tutorial/modules#tut-packages|packages]]（包括 [[../../glossary#term-namespace-package|namespace packages]]），可以从项目（这意味着它们的文件名必须是有效的 [[../../reference/lexical_analysis#identifiers|标识符]] ）。

测试发现在 [[#unittest.TestLoader.discover|TestLoader.discover()]] 中实现，但也可以从命令行使用。 基本的命令行用法是：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">cd project_directory
python -m unittest discover</syntaxhighlight>

</div>

</div>
<div class="admonition note">

笔记

作为快捷方式，<code>python -m unittest</code> 相当于 <code>python -m unittest discover</code>。 如果要传递参数来测试发现，则必须显式使用 <code>discover</code> 子命令。


</div>
<code>discover</code> 子命令有以下选项：

; <span id="cmdoption-unittest-discover-verbose"></span><span class="sig-name descname"><span class="pre">-v</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--verbose</span></span><span class="sig-prename descclassname"></span>
: 详细输出

; <span id="cmdoption-unittest-discover-start-directory"></span><span class="sig-name descname"><span class="pre">-s</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--start-directory</span></span><span class="sig-prename descclassname"> <span class="pre">directory</span></span>
: 开始发现的目录（<code>.</code> 默认）

; <span id="cmdoption-unittest-discover-pattern"></span><span class="sig-name descname"><span class="pre">-p</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--pattern</span></span><span class="sig-prename descclassname"> <span class="pre">pattern</span></span>
: 匹配测试文件的模式（<code>test*.py</code> 默认）

; <span id="cmdoption-unittest-discover-top-level-directory"></span><span class="sig-name descname"><span class="pre">-t</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--top-level-directory</span></span><span class="sig-prename descclassname"> <span class="pre">directory</span></span>
: 项目的顶级目录（默认为启动目录）

[[#cmdoption-unittest-discover-s|-s]]、[[#cmdoption-unittest-discover-p|-p]] 和 [[#cmdoption-unittest-discover-t|-t]] 选项可以按该顺序作为位置参数传入。 以下两个命令行是等效的：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"</syntaxhighlight>

</div>

</div>
除了作为路径之外，还可以传递包名，例如 <code>myproject.subpackage.test</code>，作为起始目录。 然后将导入您提供的包名称，并将其在文件系统上的位置用作起始目录。

<div class="admonition caution">

警告

测试发现通过导入来加载测试。 一旦测试发现从您指定的开始目录中找到所有测试文件，它就会将路径转换为要导入的包名称。 例如，<code>foo/bar/baz.py</code> 将被导入为 <code>foo.bar.baz</code>。

如果您有一个全局安装的软件包并尝试在该软件包的不同副本上进行测试发现，那么导入 '''' 可能发生在错误的位置。 如果发生这种情况，测试发现将警告您并退出。

如果您将起始目录作为包名而不是目录路径提供，那么discover 假定它从哪个位置导入就是您想要的位置，因此您不会收到警告。


</div>
测试模块和包可以通过[[#load-tests-protocol|load_tests协议]]自定义测试加载和发现。

<div class="versionchanged">

<span class="versionmodified changed"> 3.4 版更改： </span> 测试发现支持 [[../../glossary#term-namespace-package|命名空间包]] 作为起始目录。 请注意，您还需要指定顶级目录（例如 <code>python -m unittest discover -s root/namespace -t root</code>）。


</div>

</div>
<div id="organizing-test-code" class="section">

<span id="organizing-tests"></span>
== 组织测试代码 ==

单元测试的基本构建块是 ''测试用例'' — 必须设置并检查正确性的单个场景。 在 [[#module-unittest|unittest]] 中，测试用例由 [[#unittest.TestCase|unittest.TestCase]] 实例表示。 要制作自己的测试用例，您必须编写 [[#unittest.TestCase|TestCase]] 的子类或使用 [[#unittest.FunctionTestCase|FunctionTestCase]]。

[[#unittest.TestCase|TestCase]] 实例的测试代码应该是完全自包含的，这样它就可以单独运行或与任意数量的其他测试用例任意组合运行。

最简单的 [[#unittest.TestCase|TestCase]] 子类将简单地实现一个测试方法（即 名称以 <code>test</code>) 开头的方法，以执行特定的测试代码：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def test_default_widget_size(self):
        widget = Widget('The widget')
        self.assertEqual(widget.size(), (50, 50))</syntaxhighlight>

</div>

</div>
请注意，为了测试某些内容，我们使用 [[#unittest.TestCase|TestCase]] 基类提供的 <code>assert*()</code> 方法之一。 如果测试失败，将引发带有解释性消息的异常，并且 [[#module-unittest|unittest]] 会将测试用例标识为 ''failure''。 任何其他异常将被视为 ''错误'' 。

测试可能很多，并且它们的设置可能是重复的。 幸运的是，我们可以通过实现一个名为 [[#unittest.TestCase.setUp|setUp()]] 的方法来分解设置代码，测试框架会为我们运行的每个测试自动调用它：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def test_default_widget_size(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

    def test_widget_resize(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')</syntaxhighlight>

</div>

</div>
<div class="admonition note">

笔记

运行各种测试的顺序是通过根据字符串的内置顺序对测试方法名称进行排序来确定的。


</div>
如果在测试运行时 [[#unittest.TestCase.setUp|setUp()]] 方法引发异常，框架将认为测试发生了错误，并且不会执行测试方法。

同样，我们可以提供一个 [[#unittest.TestCase.tearDown|tearDown()]] 方法，在测试方法运行后进行整理：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()</syntaxhighlight>

</div>

</div>
如果 [[#unittest.TestCase.setUp|setUp()]] 成功，无论测试方法成功与否，都会运行 [[#unittest.TestCase.tearDown|tearDown()]]。

这种用于测试代码的工作环境称为 ''测试装置'' 。 创建一个新的 TestCase 实例作为唯一的测试装置，用于执行每个单独的测试方法。 因此，每次测试将调用 [[#unittest.TestCase.setUp|setUp()]]、[[#unittest.TestCase.tearDown|tearDown()]] 和 <code>__init__()</code> 一次。

建议您使用 TestCase 实现根据测试的功能将测试组合在一起。 [[#module-unittest|unittest]]为此提供了一种机制：''测试套件''，由[[#module-unittest|unittest]]的[[#unittest.TestSuite|TestSuite]]类表示。 在大多数情况下，调用 [[#unittest.main|unittest.main()]] 会做正确的事情并为您收集模块的所有测试用例并执行它们。

但是，如果您想自定义测试套件的构建，您可以自己完成：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('test_default_widget_size'))
    suite.addTest(WidgetTestCase('test_widget_resize'))
    return suite

if __name__ == '__main__':
    runner = unittest.TextTestRunner()
    runner.run(suite())</syntaxhighlight>

</div>

</div>
您可以将测试用例和测试套件的定义放在与它们要测试的代码相同的模块中（例如 <code>widget.py</code>），但是将测试代码放在单独的模块中有几个优点，例如<code>test_widget.py</code>：

* 测试模块可以从命令行独立运行。
* 测试代码可以更容易地从交付的代码中分离出来。
* 在没有充分理由的情况下更改测试代码以适应它测试的代码的诱惑较小。
* 测试代码的修改频率应该远低于它测试的代码。
* 可以更轻松地重构经过测试的代码。
* 无论如何，用 C 编写的模块的测试必须在单独的模块中，那么为什么不保持一致呢？
* 如果测试策略发生变化，则无需更改源代码。


</div>
<div id="re-using-old-test-code" class="section">

<span id="legacy-unit-tests"></span>
== 重用旧的测试代码 ==

一些用户会发现他们有现有的测试代码，他们希望从 [[#module-unittest|unittest]] 运行，而无需将每个旧的测试函数转换为 [[#unittest.TestCase|TestCase]] 子类。

为此，[[#module-unittest|unittest]] 提供了一个 [[#unittest.FunctionTestCase|FunctionTestCase]] 类。 [[#unittest.TestCase|TestCase]] 的这个子类可用于包装现有的测试函数。 还可以提供设置和拆卸功能。

给定以下测试函数：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...</syntaxhighlight>

</div>

</div>
可以创建一个等效的测试用例实例，如下所示，具有可选的设置和拆卸方法：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)</syntaxhighlight>

</div>

</div>
<div class="admonition note">

笔记

尽管 [[#unittest.FunctionTestCase|FunctionTestCase]] 可用于将现有测试库快速转换为基于 [[#module-unittest|unittest]] 的系统，但不推荐这种方法。 花时间设置适当的 [[#unittest.TestCase|TestCase]] 子类将使未来的测试重构变得更加容易。


</div>
在某些情况下，现有测试可能是使用 [[../doctest#module-doctest|doctest]] 模块编写的。 如果是这样，[[../doctest#module-doctest|doctest]] 提供了一个 <code>DocTestSuite</code> 类，可以从现有的基于 [[../doctest#module-doctest|doctest]] 的测试中自动构建 [[#unittest.TestSuite|unittest.TestSuite]] 实例。


</div>
<div id="skipping-tests-and-expected-failures" class="section">

<span id="unittest-skipping"></span>
== 跳过测试和预期失败 ==

<div class="versionadded">

<span class="versionmodified added">3.1 版中的新功能。</span>


</div>
Unittest 支持跳过单个测试方法甚至整个测试类。 此外，它还支持将测试标记为“预期失败”，该测试被破坏并将失败，但不应在 [[#unittest.TestResult|TestResult]] 上被视为失败。

跳过测试只是使用 [[#unittest.skip|skip()]] [[../../glossary#term-decorator|装饰器]] 或其条件变体之一，在 [[#unittest.TestCase.setUp|中调用]] [[#unittest.TestCase.skipTest|TestCase.skipTest()]] setUp() 或测试方法，或直接提高 [[#unittest.SkipTest|SkipTest]]。

基本跳过看起来像这样：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">class MyTestCase(unittest.TestCase):

    @unittest.skip("demonstrating skipping")
    def test_nothing(self):
        self.fail("shouldn't happen")

    @unittest.skipIf(mylib.__version__ < (1, 3),
                     "not supported in this library version")
    def test_format(self):
        # Tests that work for only a certain version of the library.
        pass

    @unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
    def test_windows_support(self):
        # windows specific testing code
        pass

    def test_maybe_skipped(self):
        if not external_resource_available():
            self.skipTest("external resource not available")
        # test code that depends on the external resource
        pass</syntaxhighlight>

</div>

</div>
这是在详细模式下运行上述示例的输出：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
test_maybe_skipped (__main__.MyTestCase) ... skipped 'external resource not available'
test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'

----------------------------------------------------------------------
Ran 4 tests in 0.005s

OK (skipped=4)</syntaxhighlight>

</div>

</div>
可以像方法一样跳过类：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass</syntaxhighlight>

</div>

</div>
[[#unittest.TestCase.setUp|TestCase.setUp()]] 也可以跳过测试。 当需要设置的资源不可用时，这很有用。

预期失败使用 [[#unittest.expectedFailure|expectedFailure()]] 装饰器。

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">class ExpectedFailureTestCase(unittest.TestCase):
    @unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")</syntaxhighlight>

</div>

</div>
通过在测试中调用 [[#unittest.skip|skip()]] 的装饰器，当它想要被跳过时，很容易滚动你自己的跳过装饰器。 除非传递的对象具有特定属性，否则此装饰器会跳过测试：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">def skipUnlessHasattr(obj, attr):
    if hasattr(obj, attr):
        return lambda func: func
    return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))</syntaxhighlight>

</div>

</div>
以下装饰器和异常实现了测试跳过和预期失败：

; <span class="sig-prename descclassname"><span class="pre">@</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">skip</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">reason</span></span>''<span class="sig-paren">)</span>
: 无条件跳过装饰测试。 ''reason'' 应该描述跳过测试的原因。

; <span class="sig-prename descclassname"><span class="pre">@</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">skipIf</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">condition</span></span>'', ''<span class="n"><span class="pre">reason</span></span>''<span class="sig-paren">)</span>
: 如果 ''condition'' 为真，则跳过装饰测试。

; <span class="sig-prename descclassname"><span class="pre">@</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">skipUnless</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">condition</span></span>'', ''<span class="n"><span class="pre">reason</span></span>''<span class="sig-paren">)</span>
: 跳过装饰测试，除非 ''condition'' 为真。

; <span class="sig-prename descclassname"><span class="pre">@</span></span><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">expectedFailure</span></span>
: 将测试标记为预期失败或错误。 如果测试失败或测试函数本身出错（而不是 ''测试装置'' 方法之一），那么它将被视为成功。 如果测试通过，将被视为失败。

<dl>
<dt>''<span class="pre">exception</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">SkipTest</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">reason</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>引发此异常以跳过测试。</p>
<p>通常您可以使用 [[#unittest.TestCase.skipTest|TestCase.skipTest()]] 或跳过装饰器之一，而不是直接提高它。</p></dd></dl>

跳过的测试不会有 [[#unittest.TestCase.setUp|setUp()]] 或 [[#unittest.TestCase.tearDown|tearDown()]] 围绕它们运行。 跳过的课程将不会运行 [[#unittest.TestCase.setUpClass|setUpClass()]] 或 [[#unittest.TestCase.tearDownClass|tearDownClass()]]。 跳过的模块将不会运行 <code>setUpModule()</code> 或 <code>tearDownModule()</code>。


</div>
<div id="distinguishing-test-iterations-using-subtests" class="section">

<span id="subtests"></span>
== 使用子测试区分测试迭代 ==

<div class="versionadded">

<span class="versionmodified added">3.4 版中的新功能。</span>


</div>
当您的测试之间存在非常小的差异时，例如某些参数，unittest 允许您使用 [[#unittest.TestCase.subTest|subTest()]] 上下文管理器在测试方法的主体内区分它们。

例如，下面的测试：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">class NumbersTest(unittest.TestCase):

    def test_even(self):
        """
        Test that numbers between 0 and 5 are all even.
        """
        for i in range(0, 6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)</syntaxhighlight>

</div>

</div>
将产生以下输出：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">======================================================================
FAIL: test_even (__main__.NumbersTest) (i=1)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=3)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=5)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0</syntaxhighlight>

</div>

</div>
如果不使用子测试，执行将在第一次失败后停止，并且错误将不太容易诊断，因为 <code>i</code> 的值不会显示：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">======================================================================
FAIL: test_even (__main__.NumbersTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0</syntaxhighlight>

</div>

</div>

</div>
<div id="classes-and-functions" class="section">

<span id="unittest-contents"></span>
== 类和函数 ==

本节深入介绍了[[#module-unittest|unittest]]的API。

<div id="test-cases" class="section">

<span id="testcase-objects"></span>
=== 测试用例 ===

<dl>
<dt>''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">TestCase</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">methodName</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'runTest'</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>[[#unittest.TestCase|TestCase]] 类的实例代表 [[#module-unittest|unittest]] 宇宙中的逻辑测试单元。 此类旨在用作基类，具体测试由具体子类实现。 此类实现了测试运行程序所需的接口以允许它驱动测试，以及测试代码可用于检查和报告各种故障的方法。</p>
<p>[[#unittest.TestCase|TestCase]] 的每个实例都将运行一个基本方法：名为 ''methodName'' 的方法。 在 [[#unittest.TestCase|TestCase]] 的大多数使用中，您既不会更改 ''methodName''，也不会重新实现默认的 <code>runTest()</code> 方法。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span>[[#unittest.TestCase|TestCase]] 可以在不提供 ''methodName'' 的情况下成功实例化。 这使得从交互式解释器中试验 [[#unittest.TestCase|TestCase]] 变得更加容易。</p>

</div>
<p>[[#unittest.TestCase|TestCase]] 实例提供三组方法：一组用于运行测试，另一组由测试实现用于检查条件和报告失败，以及一些查询方法允许收集有关测试本身的信息。</p>
<p>第一组中的方法（运行测试）是：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">setUp</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>调用方法来准备测试夹具。 这是在调用测试方法之前立即调用的； 除了 [[../exceptions#AssertionError|AssertionError]] 或 [[#unittest.SkipTest|SkipTest]]，此方法引发的任何异常都将被视为错误而不是测试失败。 默认实现什么都不做。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">tearDown</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>在调用测试方法并记录结果后立即调用方法。 即使测试方法引发异常也会调用它，因此子类中的实现可能需要特别小心检查内部状态。 除 [[../exceptions#AssertionError|AssertionError]] 或 [[#unittest.SkipTest|SkipTest]] 之外的任何异常，由该方法引发的将被视为额外错误而不是测试失败（从而增加报告错误的总数）。 无论测试方法的结果如何，仅当 [[#unittest.TestCase.setUp|setUp()]] 成功时才会调用此方法。 默认实现什么都不做。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">setUpClass</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>在运行单个类中的测试之前调用的类方法。 <code>setUpClass</code> 以类作为唯一参数被调用，并且必须装饰为 [[../functions#classmethod|classmethod()]]：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">@classmethod
def setUpClass(cls):
    ...</syntaxhighlight>

</div>

</div>
<p>有关更多详细信息，请参阅 [[#class-and-module-fixtures|类和模块装置]] 。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">tearDownClass</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>在单个类中的测试运行后调用的类方法。 <code>tearDownClass</code> 以类作为唯一参数被调用，并且必须装饰为 [[../functions#classmethod|classmethod()]]：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">@classmethod
def tearDownClass(cls):
    ...</syntaxhighlight>

</div>

</div>
<p>有关更多详细信息，请参阅 [[#class-and-module-fixtures|类和模块装置]] 。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">result</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>运行测试，将结果收集到作为 ''result'' 传递的 [[#unittest.TestResult|TestResult]] 对象中。 如果省略 ''result'' 或 <code>None</code>，则创建一个临时结果对象（通过调用 [[#unittest.TestCase.defaultTestResult|defaultTestResult()]] 方法）并使用。 结果对象返回给 [[#unittest.TestCase.run|run()]] 的调用者。</p>
<p>简单地调用 [[#unittest.TestCase|TestCase]] 实例也可以产生同样的效果。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.3 版更改： </span> <code>run</code> 之前的版本没有返回结果。 也没有调用实例。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">skipTest</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">reason</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>在测试方法或 [[#unittest.TestCase.setUp|setUp()]] 期间调用它会跳过当前测试。 有关更多信息，请参阅 [[#unittest-skipping|跳过测试和预期失败]] 。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">subTest</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">params</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>返回一个上下文管理器，它执行封闭的代码块作为子测试。 ''msg'' 和 ''params'' 是可选的任意值，当子测试失败时会显示这些值，让您可以清楚地识别它们。</p>
<p>一个测试用例可以包含任意数量的子测试声明，并且它们可以任意嵌套。</p>
<p>有关详细信息，请参阅 [[#subtests|使用子测试区分测试迭代]] 。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.4 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">debug</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>运行测试而不收集结果。 这允许将测试引发的异常传播给调用者，并可用于支持在调试器下运行测试。</p></dd></dl>

<p>[[#unittest.TestCase|TestCase]] 类提供了几种断言方法来检查和报告失败。 下表列出了最常用的方法（更多断言方法见下表）：</p>
{|
!width="48%"| <p>方法</p>
!width="34%"| <p>检查</p>
!width="18%"| <p>新进</p>
|-
| <p>[[#unittest.TestCase.assertEqual|<code>assertEqual(a, b)</code>]]</p>
| <p><code>a == b</code></p>
|
|-
| <p>[[#unittest.TestCase.assertNotEqual|<code>assertNotEqual(a, b)</code>]]</p>
| <p><code>a != b</code></p>
|
|-
| <p>[[#unittest.TestCase.assertTrue|<code>assertTrue(x)</code>]]</p>
| <p><code>bool(x) is True</code></p>
|
|-
| <p>[[#unittest.TestCase.assertFalse|<code>assertFalse(x)</code>]]</p>
| <p><code>bool(x) is False</code></p>
|
|-
| <p>[[#unittest.TestCase.assertIs|<code>assertIs(a, b)</code>]]</p>
| <p><code>a is b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertIsNot|<code>assertIsNot(a, b)</code>]]</p>
| <p><code>a is not b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertIsNone|<code>assertIsNone(x)</code>]]</p>
| <p><code>x is None</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertIsNotNone|<code>assertIsNotNone(x)</code>]]</p>
| <p><code>x is not None</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertIn|<code>assertIn(a, b)</code>]]</p>
| <p><code>a in b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertNotIn|<code>assertNotIn(a, b)</code>]]</p>
| <p><code>a not in b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertIsInstance|<code>assertIsInstance(a, b)</code>]]</p>
| <p><code>isinstance(a, b)</code></p>
| <p>3.2</p>
|-
| <p>[[#unittest.TestCase.assertNotIsInstance|<code>assertNotIsInstance(a, b)</code>]]</p>
| <p><code>not isinstance(a, b)</code></p>
| <p>3.2</p>
|}

<p>所有断言方法都接受一个 ''msg'' 参数，如果指定，则用作失败时的错误消息（另见 [[#unittest.TestCase.longMessage|longMessage]]）。 注意 ''msg'' 关键字参数可以传递给 [[#unittest.TestCase.assertRaises|assertRaises()]], [[#unittest.TestCase.assertRaisesRegex|assertRaisesRegex()]], [[#unittest.TestCase.assertWarns|assertWarns()]], [[#unittest.TestCase.assertWarnsRegex|assertWarns ()]] 仅当它们用作上下文管理器时。</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">assertEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''first'' 和 ''second'' 是否相等。 如果比较的值不相等，则测试将失败。</p>
<p>此外，如果 ''first'' 和 ''second'' 是完全相同的类型，并且是 list、tuple、dict、set、frozenset 或 str 之一或子类向 [[#unittest.TestCase.addTypeEqualityFunc|addTypeEqualityFunc 注册的任何类型()]] 将调用特定于类型的相等函数以生成更有用的默认错误消息（另请参阅 [[#type-specific-methods|特定于类型的方法列表]] ）。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.1 版本更改： </span> 增加了类型特定相等函数的自动调用。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.2 版更改： </span>[[#unittest.TestCase.assertMultiLineEqual|assertMultiLineEqual()]] 添加为用于比较字符串的默认类型相等函数。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertNotEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''first'' 和 ''second'' 不相等。 如果值比较相等，则测试将失败。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertTrue</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">expr</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertFalse</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">expr</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''expr'' 为真（或假）。</p>
<p>请注意，这相当于 <code>bool(expr) is True</code> 而不是 <code>expr is True</code>（后者使用 <code>assertIs(expr, True)</code>）。 当有更具体的方法可用时，也应避免使用此方法（例如 <code>assertEqual(a, b)</code> 而不是 <code>assertTrue(a == b)</code>)，因为它们在发生故障时提供了更好的错误消息。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertIs</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertIsNot</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''first'' 和 ''second'' 是（或不是）同一个对象。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertIsNone</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">expr</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertIsNotNone</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">expr</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''expr'' 是（或不是）<code>None</code>。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertIn</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">member</span></span>'', ''<span class="n"><span class="pre">container</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertNotIn</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">member</span></span>'', ''<span class="n"><span class="pre">container</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''member'' 是否在 ''容器'' 中。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertIsInstance</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">obj</span></span>'', ''<span class="n"><span class="pre">cls</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertNotIsInstance</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">obj</span></span>'', ''<span class="n"><span class="pre">cls</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''obj'' 是（或不是）''cls'' 的实例（可以是一个类或类的元组，由 [[../functions#isinstance|isinstance()]] 支持） . 要检查确切的类型，请使用 [[#unittest.TestCase.assertIs|assertIs(type(obj), cls)]]。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div></dd></dl>

<p>还可以使用以下方法检查异常、警告和日志消息的产生：</p>
{|
!width="53%"| <p>方法</p>
!width="36%"| <p>检查</p>
!width="11%"| <p>新进</p>
|-
| <p>[[#unittest.TestCase.assertRaises|<code>assertRaises(exc, fun, *args, **kwds)</code>]]</p>
| <p><code>fun(*args, **kwds)</code> 提升 ''exc''</p>
|
|-
| <p>[[#unittest.TestCase.assertRaisesRegex|<code>assertRaisesRegex(exc, r, fun, *args, **kwds)</code>]]</p>
| <p><code>fun(*args, **kwds)</code> 引发 ''exc'' 并且消息匹配正则表达式 ''r''</p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertWarns|<code>assertWarns(warn, fun, *args, **kwds)</code>]]</p>
| <p><code>fun(*args, **kwds)</code> 引发 ''warn''</p>
| <p>3.2</p>
|-
| <p>[[#unittest.TestCase.assertWarnsRegex|<code>assertWarnsRegex(warn, r, fun, *args, **kwds)</code>]]</p>
| <p><code>fun(*args, **kwds)</code> 引发 ''warn'' 并且消息匹配正则表达式 ''r''</p>
| <p>3.2</p>
|-
| <p>[[#unittest.TestCase.assertLogs|<code>assertLogs(logger, level)</code>]]</p>
| <p><code>with</code> 块以最低 ''级别'' 登录 ''logger''</p>
| <p>3.4</p>
|-
| <p>[[#unittest.TestCase.assertNoLogs|<code>assertNoLogs(logger, level)</code>]]</p>
|
<dl>
<dt><code>with</code>块不登录</dt>
<dd><p>''logger'' 最小 ''级别''</p></dd></dl>
| <p>3.10</p>
|}

<dl>
<dt><span class="sig-name descname"><span class="pre">assertRaises</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">exception</span></span>'', ''<span class="n"><span class="pre">callable</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwds</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertRaises</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">exception</span></span>'', ''<span class="o"><span class="pre">*</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试当使用任何位置或关键字参数调用 ''callable'' 时是否引发异常，这些参数也传递给 [[#unittest.TestCase.assertRaises|assertRaises()]]。 如果引发 ''exception''，则测试通过，如果引发另一个异常，则测试为错误，如果未引发异常，则测试失败。 要捕获一组异常中的任何一个，可以将包含异常类的元组作为 ''exception'' 传递。</p>
<p>如果只给出了 ''exception'' 和可能的 ''msg'' 参数，则返回一个上下文管理器，以便被测代码可以内联而不是作为函数编写：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">with self.assertRaises(SomeException):
    do_something()</syntaxhighlight>

</div>

</div>
<p>当用作上下文管理器时，[[#unittest.TestCase.assertRaises|assertRaises()]] 接受额外的关键字参数 ''msg''。</p>
<p>上下文管理器会将捕获的异常对象存储在其 <code>exception</code> 属性中。 如果目的是对引发的异常执行额外检查，这可能很有用：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)</syntaxhighlight>

</div>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.1 版更改： </span> 添加了使用 [[#unittest.TestCase.assertRaises|assertRaises()]] 作为上下文管理器的功能。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span> 添加 <code>exception</code> 属性。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.3 版更改： </span> 在用作上下文管理器时添加了 ''msg'' 关键字参数。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertRaisesRegex</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">exception</span></span>'', ''<span class="n"><span class="pre">regex</span></span>'', ''<span class="n"><span class="pre">callable</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwds</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertRaisesRegex</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">exception</span></span>'', ''<span class="n"><span class="pre">regex</span></span>'', ''<span class="o"><span class="pre">*</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>与 [[#unittest.TestCase.assertRaises|assertRaises()]] 类似，但也测试 ''regex'' 是否与引发异常的字符串表示匹配。 ''regex'' 可以是正则表达式对象，也可以是包含适合 [[../re#re|re.search()]] 使用的正则表达式的字符串。 例子：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')</syntaxhighlight>

</div>

</div>
<p>或者：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')</syntaxhighlight>

</div>

</div>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版新功能：</span>以 <code>assertRaisesRegexp</code> 名称添加。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.2 版更改：</span> 重命名为 [[#unittest.TestCase.assertRaisesRegex|assertRaisesRegex()]]。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.3 版更改： </span> 在用作上下文管理器时添加了 ''msg'' 关键字参数。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertWarns</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">warning</span></span>'', ''<span class="n"><span class="pre">callable</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwds</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertWarns</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">warning</span></span>'', ''<span class="o"><span class="pre">*</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试当使用任何位置或关键字参数调用 ''callable'' 时触发警告，这些参数也传递给 [[#unittest.TestCase.assertWarns|assertWarns()]]。 如果触发了 ''warning''，则测试通过，否则测试失败。 任何异常都是错误。 要捕获一组警告中的任何一个，可以将包含警告类的元组作为 ''warnings'' 传递。</p>
<p>如果只给出了 ''warning'' 和可能的 ''msg'' 参数，则返回一个上下文管理器，以便被测代码可以内联而不是作为函数编写：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">with self.assertWarns(SomeWarning):
    do_something()</syntaxhighlight>

</div>

</div>
<p>当用作上下文管理器时，[[#unittest.TestCase.assertWarns|assertWarns()]] 接受额外的关键字参数 ''msg''。</p>
<p>上下文管理器会将捕获的警告对象存储在其 <code>warning</code> 属性中，并将触发警告的源代码行存储在 <code>filename</code> 和 <code>lineno</code> 属性中。 如果目的是对捕获的警告执行额外检查，这可能很有用：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)</syntaxhighlight>

</div>

</div>
<p>无论调用时是否有警告过滤器，此方法都有效。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.3 版更改： </span> 在用作上下文管理器时添加了 ''msg'' 关键字参数。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertWarnsRegex</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">warning</span></span>'', ''<span class="n"><span class="pre">regex</span></span>'', ''<span class="n"><span class="pre">callable</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwds</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertWarnsRegex</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">warning</span></span>'', ''<span class="n"><span class="pre">regex</span></span>'', ''<span class="o"><span class="pre">*</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>与 [[#unittest.TestCase.assertWarns|assertWarns()]] 类似，但也测试 ''regex'' 是否与触发警告的消息匹配。 ''regex'' 可以是正则表达式对象，也可以是包含适合 [[../re#re|re.search()]] 使用的正则表达式的字符串。 例子：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')</syntaxhighlight>

</div>

</div>
<p>或者：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')</syntaxhighlight>

</div>

</div>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.3 版更改： </span> 在用作上下文管理器时添加了 ''msg'' 关键字参数。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertLogs</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">logger</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>一个上下文管理器，用于测试至少有一条消息记录在 ''logger'' 或其子节点之一上，至少具有给定的 ''级别'' 。</p>
<p>如果给出， ''logger'' 应该是一个 [[../logging#logging|logging.Logger]] 对象或一个 [[../stdtypes#str|str]] 给出记录器的名称。 默认是根记录器，它将捕获所有未被非传播后代记录器阻止的消息。</p>
<p>如果给定，''level'' 应该是数字日志级别或其等效字符串（例如 <code>&quot;ERROR&quot;</code> 或 <code>logging.ERROR</code>）。 默认值为 <code>logging.INFO</code>。</p>
<p>如果 <code>with</code> 块内发出的至少一条消息与 ''logger'' 和 ''level'' 条件匹配，则测试通过，否则失败。</p>
<p>上下文管理器返回的对象是一个记录助手，它跟踪匹配的日志消息。 它有两个属性：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">records</span></span></dt>
<dd><p>匹配日志消息的 [[../logging#logging|logging.LogRecord]] 对象列表。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">output</span></span></dt>
<dd><p>[[../stdtypes#str|str]] 对象列表，带有匹配消息的格式化输出。</p></dd></dl>

<p>例子：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">with self.assertLogs('foo', level='INFO') as cm:
   logging.getLogger('foo').info('first message')
   logging.getLogger('foo.bar').error('second message')
self.assertEqual(cm.output, ['INFO:foo:first message',
                             'ERROR:foo.bar:second message'])</syntaxhighlight>

</div>

</div>
<div class="versionadded">

<p><span class="versionmodified added">3.4 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertNoLogs</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">logger</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">level</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>一个上下文管理器，用于测试在 ''logger'' 或其一个子节点上没有记录任何消息，至少具有给定的 ''级别'' 。</p>
<p>如果给出， ''logger'' 应该是一个 [[../logging#logging|logging.Logger]] 对象或一个 [[../stdtypes#str|str]] 给出记录器的名称。 默认是根记录器，它将捕获所有消息。</p>
<p>如果给定，''level'' 应该是数字日志级别或其等效字符串（例如 <code>&quot;ERROR&quot;</code> 或 <code>logging.ERROR</code>）。 默认值为 <code>logging.INFO</code>。</p>
<p>与 [[#unittest.TestCase.assertLogs|assertLogs()]] 不同，上下文管理器不会返回任何内容。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.10 版中的新功能。</span></p>

</div></dd></dl>

<p>还有其他方法用于执行更具体的检查，例如：</p>
{|
!width="46%"| <p>方法</p>
!width="38%"| <p>检查</p>
!width="16%"| <p>新进</p>
|-
| <p>[[#unittest.TestCase.assertAlmostEqual|<code>assertAlmostEqual(a, b)</code>]]</p>
| <p><code>round(a-b, 7) == 0</code></p>
|
|-
| <p>[[#unittest.TestCase.assertNotAlmostEqual|<code>assertNotAlmostEqual(a, b)</code>]]</p>
| <p><code>round(a-b, 7) != 0</code></p>
|
|-
| <p>[[#unittest.TestCase.assertGreater|<code>assertGreater(a, b)</code>]]</p>
| <p><code>a &gt; b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertGreaterEqual|<code>assertGreaterEqual(a, b)</code>]]</p>
| <p><code>a &gt;= b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertLess|<code>assertLess(a, b)</code>]]</p>
| <p><code>a &lt; b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertLessEqual|<code>assertLessEqual(a, b)</code>]]</p>
| <p><code>a &lt;= b</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertRegex|<code>assertRegex(s, r)</code>]]</p>
| <p><code>r.search(s)</code></p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertNotRegex|<code>assertNotRegex(s, r)</code>]]</p>
| <p><code>not r.search(s)</code></p>
| <p>3.2</p>
|-
| <p>[[#unittest.TestCase.assertCountEqual|<code>assertCountEqual(a, b)</code>]]</p>
| <p>''a'' 和 ''b'' 具有相同数量的相同元素，无论它们的顺序如何。</p>
| <p>3.2</p>
|}

<dl>
<dt><span class="sig-name descname"><span class="pre">assertAlmostEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">places</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">7</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">delta</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertNotAlmostEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">places</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">7</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">delta</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>通过计算差值来测试 ''first'' 和 ''second'' 是否近似（或不近似）相等，四舍五入到给定的小数位数 ''places''（默认为 7），以及与零相比。 请注意，这些方法将值四舍五入到给定的 ''小数位数'' （即 像 [[../functions#round|round()]] 函数）而不是 ''有效数字'' 。</p>
<p>如果提供 ''delta'' 而不是 ''places''，则 ''first'' 和 ''second'' 之间的差异必须小于或等于（或大于）[ X163X]delta。</p>
<p>提供 ''delta'' 和 ''places'' 会引发 [[../exceptions#TypeError|TypeError]]。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span>[[#unittest.TestCase.assertAlmostEqual|assertAlmostEqual()]] 自动考虑比较相等的几乎相等的对象。 [[#unittest.TestCase.assertNotAlmostEqual|assertNotAlmostEqual()]] 如果对象比较相等，则自动失败。 添加了 ''delta'' 关键字参数。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertGreater</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertGreaterEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertLess</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertLessEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试一下''第一的''分别是 &gt;、&gt;=、&lt; 或 &lt;= 比''第二''取决于方法名称。 如果没有，测试将失败：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"</syntaxhighlight>

</div>

</div>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertRegex</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">text</span></span>'', ''<span class="n"><span class="pre">regex</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertNotRegex</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">text</span></span>'', ''<span class="n"><span class="pre">regex</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试 ''regex'' 搜索是否匹配（或不匹配）''text''。 如果失败，错误消息将包括模式和 ''text''（或模式和 ''text'' 意外匹配的部分）。 ''regex'' 可以是正则表达式对象，也可以是包含适合 [[../re#re|re.search()]] 使用的正则表达式的字符串。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版新功能：</span>以 <code>assertRegexpMatches</code> 名称添加。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span> 方法 <code>assertRegexpMatches()</code> 已重命名为 [[#unittest.TestCase.assertRegex|assertRegex()]]。</p>

</div>
<div class="versionadded">

<p><span class="versionmodified added"> 3.2 版新功能：</span>[[#unittest.TestCase.assertNotRegex|assertNotRegex()]]。</p>

</div>
<div class="versionadded">

<p><span class="versionmodified added"> 3.5 版新功能： </span>名称 <code>assertNotRegexpMatches</code> 是 [[#unittest.TestCase.assertNotRegex|assertNotRegex()]] 的弃用别名。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertCountEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试序列 ''first'' 包含与 ''second'' 相同的元素，无论它们的顺序如何。 如果他们不这样做，则会生成一条错误消息，列出序列之间的差异。</p>
<p>比较 ''first'' 和 ''second'' 时，重复元素不会被 ''忽略'' 。 它验证每个元素在两个序列中是否具有相同的计数。 等效于：<code>assertEqual(Counter(list(first)), Counter(list(second)))</code> 但也适用于不可散列对象的序列。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div></dd></dl>

<p>[[#unittest.TestCase.assertEqual|assertEqual()]] 方法将相同类型对象的相等性检查分派给不同的特定于类型的方法。 大多数内置类型已经实现了这些方法，但也可以使用 [[#unittest.TestCase.addTypeEqualityFunc|addTypeEqualityFunc()]] 注册新方法：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">addTypeEqualityFunc</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">typeobj</span></span>'', ''<span class="n"><span class="pre">function</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>注册一个由 [[#unittest.TestCase.assertEqual|assertEqual()]] 调用的特定于类型的方法，以检查完全相同 ''typeobj''（非子类）的两个对象是否比较相等。 ''function'' 必须采用两个位置参数和第三个 msg=None 关键字参数，就像 [[#unittest.TestCase.assertEqual|assertEqual()]] 一样。 当检测到前两个参数之间的不等式时，它必须引发 [[#unittest.TestCase.failureException|self.failureException(msg)]] - 可能提供有用的信息并在错误消息中详细解释不等式。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<p>[[#unittest.TestCase.assertEqual|assertEqual()]] 自动使用的特定于类型的方法列表总结在下表中。 请注意，通常不需要直接调用这些方法。</p>
{|
!width="49%"| <p>方法</p>
!width="35%"| <p>用来比较</p>
!width="17%"| <p>新进</p>
|-
| <p>[[#unittest.TestCase.assertMultiLineEqual|<code>assertMultiLineEqual(a, b)</code>]]</p>
| <p>字符串</p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertSequenceEqual|<code>assertSequenceEqual(a, b)</code>]]</p>
| <p>序列</p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertListEqual|<code>assertListEqual(a, b)</code>]]</p>
| <p>列表</p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertTupleEqual|<code>assertTupleEqual(a, b)</code>]]</p>
| <p>元组</p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertSetEqual|<code>assertSetEqual(a, b)</code>]]</p>
| <p>集或冻结集</p>
| <p>3.1</p>
|-
| <p>[[#unittest.TestCase.assertDictEqual|<code>assertDictEqual(a, b)</code>]]</p>
| <p>听写</p>
| <p>3.1</p>
|}

<dl>
<dt><span class="sig-name descname"><span class="pre">assertMultiLineEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试多行字符串 ''first'' 是否等于字符串 ''second''。 当不相等时，突出显示差异的两个字符串的差异将包含在错误消息中。 在将字符串与 [[#unittest.TestCase.assertEqual|assertEqual()]] 进行比较时，默认使用此方法。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertSequenceEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">seq_type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试两个序列是否相等。 如果提供了 ''seq_type''，则 ''first'' 和 ''second'' 都必须是 ''seq_type'' 的实例，否则将引发故障。 如果序列不同，则会构建一条错误消息，显示两者之间的差异。</p>
<p>这个方法不是直接被[[#unittest.TestCase.assertEqual|assertEqual()]]调用，而是用来实现[[#unittest.TestCase.assertListEqual|assertListEqual()]]和[[#unittest.TestCase.assertTupleEqual|assertTupleEqual()]]。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertListEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span><br />
<span class="sig-name descname"><span class="pre">assertTupleEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试两个列表或元组是否相等。 如果不是，则会构建一条错误消息，仅显示两者之间的差异。 如果任一参数的类型错误，也会引发错误。 在将列表或元组与 [[#unittest.TestCase.assertEqual|assertEqual()]] 进行比较时，默认使用这些方法。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertSetEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试两组是否相等。 如果不是，则构建一个错误消息，列出集合之间的差异。 在将集合或冻结集与 [[#unittest.TestCase.assertEqual|assertEqual()]] 进行比较时，默认使用此方法。</p>
<p>如果 ''first'' 或 ''second'' 没有 <code>set.difference()</code> 方法，则失败。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">assertDictEqual</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">first</span></span>'', ''<span class="n"><span class="pre">second</span></span>'', ''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>测试两个字典是否相等。 如果不是，则会构造一条错误消息，显示字典中的差异。 默认情况下，此方法将用于在调用 [[#unittest.TestCase.assertEqual|assertEqual()]] 时比较字典。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<p>最后 [[#unittest.TestCase|TestCase]] 提供了以下方法和属性：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">fail</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>无条件发出测试失败信号，错误消息为 ''msg'' 或 <code>None</code>。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">failureException</span></span></dt>
<dd><p>这个类属性给出了测试方法引发的异常。 如果测试框架需要使用专门的异常，可能携带额外的信息，它必须子类化这个异常，以便与框架“公平竞争”。 该属性的初始值为 [[../exceptions#AssertionError|AssertionError]]。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">longMessage</span></span></dt>
<dd><p>此类属性确定当自定义失败消息作为 msg 参数传递给失败的 assertXYY 调用时会发生什么。 <code>True</code> 是默认值。 在这种情况下，自定义消息会附加到标准失败消息的末尾。 当设置为 <code>False</code> 时，自定义消息将替换标准消息。</p>
<p>通过在调用断言方法之前将实例属性 self.longMessage 分配给 <code>True</code> 或 <code>False</code>，可以在单个测试方法中覆盖类设置。</p>
<p>在每次测试调用之前重置类设置。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">maxDiff</span></span></dt>
<dd><p>此属性通过报告失败差异的断言方法控制差异输出的最大长度。 默认为 80*8 个字符。 受此属性影响的断言方法是 [[#unittest.TestCase.assertSequenceEqual|assertSequenceEqual()]]（包括所有委托给它的序列比较方法）、[[#unittest.TestCase.assertDictEqual|assertDictEqual()]] 和 [[#unittest.TestCase.assertMultiLineEqual|assertMultiLineEqual()]]。</p>
<p>将 <code>maxDiff</code> 设置为 <code>None</code> 意味着没有最大差异长度。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div></dd></dl>

<p>测试框架可以使用以下方法来收集有关测试的信息：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">countTestCases</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>返回此测试对象表示的测试数量。 对于 [[#unittest.TestCase|TestCase]] 实例，这将始终是 <code>1</code>。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">defaultTestResult</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>返回应用于此测试用例类的测试结果类的实例（如果没有其他结果实例提供给 [[#unittest.TestCase.run|run()]] 方法）。</p>
<p>对于 [[#unittest.TestCase|TestCase]] 实例，这将始终是 [[#unittest.TestResult|TestResult]] 的实例； [[#unittest.TestCase|TestCase]] 的子类应该根据需要覆盖它。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">id</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>返回标识特定测试用例的字符串。 这通常是测试方法的全名，包括模块和类名。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">shortDescription</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>返回测试的描述，如果没有提供描述，则返回 <code>None</code>。 此方法的默认实现返回测试方法文档字符串的第一行（如果可用）或 <code>None</code>。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.1 版更改： </span> 在 3.1 中，即使存在文档字符串，也已更改为将测试名称添加到简短描述中。 这导致了 unittest 扩展的兼容性问题，并且添加测试名称已移至 Python 3.2 中的 [[#unittest.TextTestResult|TextTestResult]]。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addCleanup</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">function</span></span>'', ''<span class="o"><span class="pre">/</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>在[[#unittest.TestCase.tearDown|tearDown()]]后添加一个函数，用于清理测试时使用的资源。 函数的调用顺序与它们添加的顺序相反 (LIFO)。 当它们被添加时，任何参数和关键字参数都会被调用到 [[#unittest.TestCase.addCleanup|addCleanup()]] 中。</p>
<p>如果 [[#unittest.TestCase.setUp|setUp()]] 失败，意味着 [[#unittest.TestCase.tearDown|tearDown()]] 没有被调用，那么任何添加的清理函数仍然会被调用。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">doCleanups</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>如果 [[#unittest.TestCase.setUp|setUp()]] 引发异常，则在 [[#unittest.TestCase.tearDown|tearDown()]] 或 [[#unittest.TestCase.setUp|setUp()]] 之后无条件调用此方法。</p>
<p>它负责调用[[#unittest.TestCase.addCleanup|addCleanup()]]添加的所有清理函数。 如果您需要调用清理函数 ''prior'' 到 [[#unittest.TestCase.tearDown|tearDown()]] 那么您可以自己调用 [[#unittest.TestCase.doCleanups|doCleanups()]]。</p>
<p>[[#unittest.TestCase.doCleanups|doCleanups()]] 从清理函数堆栈中一次弹出一个方法，因此可以随时调用。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt>''<span class="pre">classmethod</span>'' <span class="sig-name descname"><span class="pre">addClassCleanup</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">function</span></span>'', ''<span class="o"><span class="pre">/</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>在[[#unittest.TestCase.tearDownClass|tearDownClass()]]之后添加一个函数，用于清理测试类中使用的资源。 函数的调用顺序与它们添加的顺序相反 (LIFO)。 当它们被添加时，任何参数和关键字参数都会被调用到 [[#unittest.TestCase.addClassCleanup|addClassCleanup()]] 中。</p>
<p>如果 [[#unittest.TestCase.setUpClass|setUpClass()]] 失败，意味着 [[#unittest.TestCase.tearDownClass|tearDownClass()]] 没有被调用，那么任何添加的清理函数仍然会被调用。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.8 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt>''<span class="pre">classmethod</span>'' <span class="sig-name descname"><span class="pre">doClassCleanups</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>如果 [[#unittest.TestCase.setUpClass|setUpClass()]] 引发异常，则在 [[#unittest.TestCase.tearDownClass|tearDownClass()]] 或 [[#unittest.TestCase.setUpClass|setUpClass()]] 之后无条件调用此方法。</p>
<p>它负责调用[[#unittest.TestCase.addClassCleanup|addClassCleanup()]]添加的所有清理函数。 如果您需要调用清理函数 ''prior'' 到 [[#unittest.TestCase.tearDownClass|tearDownClass()]] 那么您可以自己调用 [[#unittest.TestCase.doClassCleanups|doClassCleanups()]]。</p>
<p>[[#unittest.TestCase.doClassCleanups|doClassCleanups()]] 一次从清理函数堆栈中弹出一个方法，因此可以随时调用。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.8 版中的新功能。</span></p>

</div></dd></dl>
</dd></dl>

<dl>
<dt>''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">IsolatedAsyncioTestCase</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">methodName</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'runTest'</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>此类提供类似于 [[#unittest.TestCase|TestCase]] 的 API，并且还接受协程作为测试函数。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.8 版中的新功能。</span></p>

</div>
<dl>
<dt><span class="sig-name descname"><span class="pre">addAsyncCleanup</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">function</span></span>'', ''<span class="o"><span class="pre">/</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>此方法接受可用作清理函数的协程。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">result</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>设置一个新的事件循环来运行测试，将结果收集到作为 ''result'' 传递的 [[#unittest.TestResult|TestResult]] 对象中。 如果省略 ''result'' 或 <code>None</code>，则创建一个临时结果对象（通过调用 <code>defaultTestResult()</code> 方法）并使用。 结果对象返回给 [[#unittest.IsolatedAsyncioTestCase.run|run()]] 的调用者。 在测试结束时，事件循环中的所有任务都被取消。</p></dd></dl>

<p>说明顺序的示例：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">from unittest import IsolatedAsyncioTestCase

events = []


class Test(IsolatedAsyncioTestCase):


    def setUp(self):
        events.append("setUp")

    async def asyncSetUp(self):
        self._async_connection = await AsyncConnection()
        events.append("asyncSetUp")

    async def test_response(self):
        events.append("test_response")
        response = await self._async_connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)
        self.addAsyncCleanup(self.on_cleanup)

    def tearDown(self):
        events.append("tearDown")

    async def asyncTearDown(self):
        await self._async_connection.close()
        events.append("asyncTearDown")

    async def on_cleanup(self):
        events.append("cleanup")

if __name__ == "__main__":
    unittest.main()</syntaxhighlight>

</div>

</div>
<p>运行测试后，<code>events</code> 将包含 <code>[&quot;setUp&quot;, &quot;asyncSetUp&quot;, &quot;test_response&quot;, &quot;asyncTearDown&quot;, &quot;tearDown&quot;, &quot;cleanup&quot;]</code>。</p></dd></dl>

; ''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">FunctionTestCase</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">testFunc</span></span>'', ''<span class="n"><span class="pre">setUp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">tearDown</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">description</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span>
: 此类实现了 [[#unittest.TestCase|TestCase]] 接口的一部分，该接口允许测试运行器驱动测试，但不提供测试代码可用于检查和报告错误的方法。 这用于使用遗留测试代码创建测试用例，允许将其集成到基于 [[#module-unittest|unittest]] 的测试框架中。

<div id="deprecated-aliases" class="section">

<span id="id3"></span>
==== 不推荐使用的别名 ====

由于历史原因，某些 [[#unittest.TestCase|TestCase]] 方法具有一个或多个现已弃用的别名。 下表列出了正确的名称及其已弃用的别名：

<blockquote><div>

{|
!width="40%"| 方法名称
!width="28%"| 不推荐使用的别名
!width="31%"| 不推荐使用的别名
|-
| [[#unittest.TestCase.assertEqual|<code>assertEqual()</code>]]
| 失败除非相等
| 断言等于
|-
| [[#unittest.TestCase.assertNotEqual|<code>assertNotEqual()</code>]]
| 失败如果相等
| 断言不等于
|-
| [[#unittest.TestCase.assertTrue|<code>assertTrue()</code>]]
| 除非失败
| 断言_
|-
| [[#unittest.TestCase.assertFalse|<code>assertFalse()</code>]]
| 如果失败
|
|-
| [[#unittest.TestCase.assertRaises|<code>assertRaises()</code>]]
| 失败除非加注
|
|-
| [[#unittest.TestCase.assertAlmostEqual|<code>assertAlmostEqual()</code>]]
| 失败除非几乎相等
| 断言几乎等于
|-
| [[#unittest.TestCase.assertNotAlmostEqual|<code>assertNotAlmostEqual()</code>]]
| 失败如果几乎相等
| assertNotAlmostEquals
|-
| [[#unittest.TestCase.assertRegex|<code>assertRegex()</code>]]
|
| 断言正则表达式匹配
|-
| [[#unittest.TestCase.assertNotRegex|<code>assertNotRegex()</code>]]
|
| assertNotRegexpMatches
|-
| [[#unittest.TestCase.assertRaisesRegex|<code>assertRaisesRegex()</code>]]
|
| assertRaisesRegexp
|}

<div class="deprecated">

<span class="versionmodified deprecated"> 自 3.1 版起已弃用：</span>第二列中列出的失败* 别名已被弃用。


</div>
<div class="deprecated">

<span class="versionmodified deprecated">自 3.2 版起已弃用：</span>第三列中列出的 assert* 别名已被弃用。


</div>
<div class="deprecated">

<span class="versionmodified deprecated"> 自 3.2 版起已弃用：</span><code>assertRegexpMatches</code> 和 <code>assertRaisesRegexp</code> 已重命名为 [[#unittest.TestCase.assertRegex|assertRegex()]] 和 [[#unittest.TestCase.assertRaisesRegex|assertRaisesRegex()]]。


</div>
<div class="deprecated">

<span class="versionmodified deprecated"> 自 3.5 版起已弃用：</span> <code>assertNotRegexpMatches</code> 名称已弃用，取而代之的是 [[#unittest.TestCase.assertNotRegex|assertNotRegex()]]。


</div>

</div></blockquote>

</div>

</div>
<div id="grouping-tests" class="section">

<span id="testsuite-objects"></span>
=== 分组测试 ===

<dl>
<dt>''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">TestSuite</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">tests</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">()</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>此类表示单个测试用例和测试套件的聚合。 该类提供了测试运行器所需的接口，以允许它像任何其他测试用例一样运行。 运行 [[#unittest.TestSuite|TestSuite]] 实例与迭代套件相同，单独运行每个测试。</p>
<p>如果给出 ''tests''，它必须是单个测试用例或其他测试套件的迭代，这些测试套件将用于最初构建套件。 提供了其他方法来稍后将测试用例和套件添加到集合中。</p>
<p>[[#unittest.TestSuite|TestSuite]] 对象的行为与 [[#unittest.TestCase|TestCase]] 对象非常相似，但它们实际上并不实现测试。 相反，它们用于将测试聚合成应该一起运行的测试组。 一些额外的方法可用于向 [[#unittest.TestSuite|TestSuite]] 实例添加测试：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">addTest</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>向套件添加 [[#unittest.TestCase|TestCase]] 或 [[#unittest.TestSuite|TestSuite]]。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addTests</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">tests</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>将来自 [[#unittest.TestCase|TestCase]] 和 [[#unittest.TestSuite|TestSuite]] 实例的迭代中的所有测试添加到此测试套件中。</p>
<p>这相当于迭代 ''tests''，为每个元素调用 [[#unittest.TestSuite.addTest|addTest()]]。</p></dd></dl>

<p>[[#unittest.TestSuite|TestSuite]] 与 [[#unittest.TestCase|TestCase]] 共享以下方法：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">result</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>运行与此套件关联的测试，将结果收集到作为 ''result'' 传递的测试结果对象中。 请注意，与 [[#unittest.TestCase.run|TestCase.run()]] 不同，[[#unittest.TestSuite.run|TestSuite.run()]] 需要传入结果对象。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">debug</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>运行与此套件关联的测试而不收集结果。 这允许将测试引发的异常传播给调用者，并可用于支持在调试器下运行测试。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">countTestCases</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>返回此测试对象表示的测试数量，包括所有单独的测试和子套件。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">__iter__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>由 [[#unittest.TestSuite|TestSuite]] 分组的测试总是通过迭代访问。 子类可以通过覆盖 [[#unittest.TestSuite.__iter__|__iter__()]] 懒惰地提供测试。 请注意，此方法可能会在单个套件上多次调用（例如，在计算测试或比较相等性时），因此每次调用之前通过重复迭代返回的测试 [[#unittest.TestSuite.run|TestSuite.run()]] 必须相同迭代。 在 [[#unittest.TestSuite.run|TestSuite.run()]] 之后，调用者不应依赖此方法返回的测试，除非调用者使用覆盖 <code>TestSuite._removeTestAtIndex()</code> 的子类来保留测试引用。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span> 在早期版本中，[[#unittest.TestSuite|TestSuite]] 直接访问测试而不是通过迭代，因此覆盖 [[#unittest.TestSuite.__iter__|__iter__()]] 不足以提供测试。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.4 版中更改： </span> 在早期版本中，[[#unittest.TestSuite|TestSuite]] 在 [[#unittest.TestSuite.run|TestSuite.run()]] 之后持有对每个 [[#unittest.TestCase|TestCase]] 的引用。 子类可以通过覆盖 <code>TestSuite._removeTestAtIndex()</code> 来恢复该行为。</p>

</div></dd></dl>

<p>在 [[#unittest.TestSuite|TestSuite]] 对象的典型用法中，[[#unittest.TestSuite.run|run()]] 方法由 <code>TestRunner</code> 调用，而不是由最终用户测试工具调用。</p></dd></dl>


</div>
<div id="loading-and-running-tests" class="section">

=== 加载和运行测试 ===

<dl>
<dt>''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">TestLoader</span></span></dt>
<dd><p>[[#unittest.TestLoader|TestLoader]] 类用于从类和模块创建测试套件。 通常，不需要创建此类的实例； [[#module-unittest|unittest]] 模块提供了一个可以作为 [[#unittest.defaultTestLoader|unittest.defaultTestLoader]] 共享的实例。 但是，使用子类或实例允许自定义一些可配置的属性。</p>
<p>[[#unittest.TestLoader|TestLoader]] 对象具有以下属性：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">errors</span></span></dt>
<dd><p>加载测试时遇到的非致命错误的列表。 加载器在任何时候都不会重置。 致命错误由相关的 a 方法发出信号，该方法向调用者引发异常。 非致命错误也由综合测试指示，该测试将在运行时引发原始错误。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.5 版中的新功能。</span></p>

</div></dd></dl>

<p>[[#unittest.TestLoader|TestLoader]] 对象有以下方法：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">loadTestsFromTestCase</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">testCaseClass</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>返回包含在 [[#unittest.TestCase|TestCase]] 派生的 <code>testCaseClass</code> 中的所有测试用例的套件。</p>
<p>为每个由 [[#unittest.TestLoader.getTestCaseNames|getTestCaseNames()]] 命名的方法创建一个测试用例实例。 默认情况下，这些是以 <code>test</code> 开头的方法名称。 如果 [[#unittest.TestLoader.getTestCaseNames|getTestCaseNames()]] 未返回任何方法，但实现了 <code>runTest()</code> 方法，则会为该方法创建单个测试用例。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">loadTestsFromModule</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">module</span></span>'', ''<span class="n"><span class="pre">pattern</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>返回给定模块中包含的所有测试用例的套件。 此方法在 ''模块'' 中搜索从 [[#unittest.TestCase|TestCase]] 派生的类，并为为该类定义的每个测试方法创建该类的实例。</p>
<div class="admonition note">

<p>笔记</p>
<p>虽然使用 [[#unittest.TestCase|TestCase]] 派生类的层次结构可以方便地共享夹具和辅助函数，但在不打算直接实例化的基类上定义测试方法并不适合这种方法。 但是，当设备不同并在子类中定义时，这样做会很有用。</p>

</div>
<p>如果模块提供 <code>load_tests</code> 函数，它将被调用以加载测试。 这允许模块自定义测试加载。 这是[[#load-tests-protocol|load_tests 协议]]。 ''pattern'' 参数作为第三个参数传递给 <code>load_tests</code>。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span> 添加了对 <code>load_tests</code> 的支持。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.5 版更改： </span> 未记录和非官方的 ''use_load_tests'' 默认参数已弃用并被忽略，尽管它仍被接受以实现向后兼容性。 该方法现在还接受一个仅关键字参数 ''pattern''，该参数作为第三个参数传递给 <code>load_tests</code>。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">loadTestsFromName</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">name</span></span>'', ''<span class="n"><span class="pre">module</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>返回一组给定字符串说明符的所有测试用例。</p>
<p>说明符 ''name'' 是一个“点名”，可以解析为模块、测试用例类、测试用例类中的测试方法、[[#unittest.TestSuite|TestSuite]] 实例或可调用的返回 [[#unittest.TestCase|TestCase]] 或 [[#unittest.TestSuite|TestSuite]] 实例的对象。 这些检查按此处列出的顺序应用； 也就是说，可能的测试用例类上的方法将被选择为“测试用例类中的测试方法”，而不是“可调用对象”。</p>
<p>例如，如果您有一个包含 [[#unittest.TestCase|TestCase]] 派生类 <code>SampleTestCase</code> 的模块 <code>SampleTests</code> 和三个测试方法（<code>test_one()</code>、<code>test_two()</code> , 和 <code>test_three()</code>)，说明符 <code>'SampleTests.SampleTestCase'</code> 将导致此方法返回一个将运行所有三个测试方法的套件。 使用说明符 <code>'SampleTests.SampleTestCase.test_two'</code> 将导致它返回一个仅运行 <code>test_two()</code> 测试方法的测试套件。 说明符可以引用尚未导入的模块和包； 它们将作为副作用导入。</p>
<p>该方法可选地解析 ''name'' 相对于给定的 ''模块'' 。</p>
<div class="versionchanged">

<p><span class="versionmodified changed">在 3.5 版中更改：</span>如果在遍历 ''name'' 时发生 [[../exceptions#ImportError|ImportError]] 或 [[../exceptions#AttributeError|AttributeError]]，那么在运行时引发该错误的综合测试将是回来。 这些错误包含在 self.errors 累积的错误中。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">loadTestsFromNames</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">names</span></span>'', ''<span class="n"><span class="pre">module</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>类似于 [[#unittest.TestLoader.loadTestsFromName|loadTestsFromName()]]，但采用一系列名称而不是单个名称。 返回值是一个测试套件，它支持为每个名称定义的所有测试。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">getTestCaseNames</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">testCaseClass</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>返回在 ''testCaseClass'' 中找到的方法名称的排序序列； 这应该是 [[#unittest.TestCase|TestCase]] 的子类。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">discover</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">start_dir</span></span>'', ''<span class="n"><span class="pre">pattern</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'test*.py'</span></span>'', ''<span class="n"><span class="pre">top_level_dir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>通过从指定的起始目录递归到子目录中查找所有测试模块，并返回包含它们的 TestSuite 对象。 只会加载匹配 ''模式'' 的测试文件。 （使用 shell 样式模式匹配。）只有可导入的模块名称（即 是有效的 Python 标识符）将被加载。</p>
<p>所有测试模块都必须可以从项目的顶层导入。 如果起始目录不是顶级目录，则必须单独指定顶级目录。</p>
<p>如果导入模块失败，例如由于语法错误，那么这将被记录为单个错误并且发现将继续。 如果导入失败是由于 [[#unittest.SkipTest|SkipTest]] 被引发，它会被记录为跳过而不是错误。</p>
<p>如果找到包（包含名为 <code>__init__.py</code> 的文件的目录），将检查该包的 <code>load_tests</code> 函数。 如果存在，那么它将被称为 <code>package.load_tests(loader, tests, pattern)</code>。 即使 load_tests 函数本身调用 <code>loader.discover</code>，测试发现也会确保在调用期间只检查一次包的测试。</p>
<p>如果 <code>load_tests</code> 存在，则发现不会 ''不'' 递归到包中，<code>load_tests</code> 负责加载包中的所有测试。</p>
<p>该模式故意不存储为加载程序属性，以便包可以继续自行发现。 ''top_level_dir'' 已存储，因此 <code>load_tests</code> 不需要将此参数传递给 <code>loader.discover()</code>。</p>
<p>''start_dir'' 可以是带点的模块名称也可以是目录。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed">在 3.4 版中更改：</span>在导入时引发 [[#unittest.SkipTest|SkipTest]] 的模块被记录为跳过，而不是错误。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.4 版更改： </span>''start_dir'' 可以是 [[../../glossary#term-namespace-package|命名空间包]] 。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.4 版更改： </span> 路径在导入之前进行排序，因此即使底层文件系统的排序不依赖于文件名，执行顺序也是相同的。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.5 版更改：</span>现在检查找到的包是否有 <code>load_tests</code>，无论它们的路径是否匹配 ''pattern''，因为包名不可能与默认模式匹配.</p>

</div></dd></dl>

<p>[[#unittest.TestLoader|TestLoader]] 的以下属性可以通过实例的子类化或赋值来配置：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">testMethodPrefix</span></span></dt>
<dd><p>给出将被解释为测试方法的方法名称前缀的字符串。 默认值为 <code>'test'</code>。</p>
<p>这会影响 [[#unittest.TestLoader.getTestCaseNames|getTestCaseNames()]] 和所有 <code>loadTestsFrom*()</code> 方法。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">sortTestMethodsUsing</span></span></dt>
<dd><p>在 [[#unittest.TestLoader.getTestCaseNames|getTestCaseNames()]] 和所有 <code>loadTestsFrom*()</code> 方法中对方法名称进行排序时，用于比较方法名称的函数。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">suiteClass</span></span></dt>
<dd><p>从测试列表构建测试套件的可调用对象。 结果对象上不需要任何方法。 默认值为 [[#unittest.TestSuite|TestSuite]] 类。</p>
<p>这会影响所有 <code>loadTestsFrom*()</code> 方法。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">testNamePatterns</span></span></dt>
<dd><p>测试方法必须匹配才能包含在测试套件中的 Unix shell 样式通配符测试名称模式列表（请参阅 <code>-v</code> 选项）。</p>
<p>如果此属性不是 <code>None</code>（默认值），则测试套件中包含的所有测试方法都必须与此列表中的模式之一匹配。 请注意，匹配始终使用 [[../fnmatch#fnmatch|fnmatch.fnmatchcase()]]，因此与传递给 <code>-v</code> 选项的模式不同，简单的子字符串模式必须使用 <code>*</code> 通配符进行转换。</p>
<p>这会影响所有 <code>loadTestsFrom*()</code> 方法。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.7 版中的新功能。</span></p>

</div></dd></dl>
</dd></dl>

<dl>
<dt>''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">TestResult</span></span></dt>
<dd><p>此类用于编译有关哪些测试成功和哪些测试失败的信息。</p>
<p>[[#unittest.TestResult|TestResult]] 对象存储一组测试的结果。 [[#unittest.TestCase|TestCase]] 和 [[#unittest.TestSuite|TestSuite]] 类确保正确记录结果； 测试作者无需担心记录测试结果。</p>
<p>构建在 [[#module-unittest|unittest]] 之上的测试框架可能希望访问通过运行一组测试生成的 [[#unittest.TestResult|TestResult]] 对象以进行报告； 为此，[[#unittest.TestResult|TestResult]] 实例由 <code>TestRunner.run()</code> 方法返回。</p>
<p>[[#unittest.TestResult|TestResult]] 实例具有以下属性，这些属性在检查运行一组测试的结果时会很重要：</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">errors</span></span></dt>
<dd><p>包含 [[#unittest.TestCase|TestCase]] 实例的 2 元组和保存格式化回溯的字符串的列表。 每个元组代表一个引发意外异常的测试。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">failures</span></span></dt>
<dd><p>包含 [[#unittest.TestCase|TestCase]] 实例的 2 元组和保存格式化回溯的字符串的列表。 每个元组代表一个测试，其中使用 <code>TestCase.assert*()</code> 方法明确发出故障信号。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">skipped</span></span></dt>
<dd><p>包含 [[#unittest.TestCase|TestCase]] 实例的 2 元组和包含跳过测试原因的字符串的列表。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">expectedFailures</span></span></dt>
<dd><p>包含 [[#unittest.TestCase|TestCase]] 实例的 2 元组和保存格式化回溯的字符串的列表。 每个元组代表测试用例的预期失败或错误。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">unexpectedSuccesses</span></span></dt>
<dd><p>包含标记为预期失败但成功的 [[#unittest.TestCase|TestCase]] 实例的列表。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">shouldStop</span></span></dt>
<dd><p>当测试的执行应该通过 [[#unittest.TestResult.stop|stop()]] 停止时，设置为 <code>True</code>。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">testsRun</span></span></dt>
<dd><p>到目前为止运行的测试总数。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">buffer</span></span></dt>
<dd><p>如果设置为 true，<code>sys.stdout</code> 和 <code>sys.stderr</code> 将在被调用的 [[#unittest.TestResult.startTest|startTest()]] 和 [[#unittest.TestResult.stopTest|stopTest()]] 之间缓冲。 如果测试失败或错误，收集的输出将仅回显到真实的 <code>sys.stdout</code> 和 <code>sys.stderr</code> 上。 任何输出也附加到失败/错误消息。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">failfast</span></span></dt>
<dd><p>如果设置为 true [[#unittest.TestResult.stop|stop()]] 将在第一次失败或错误时调用，停止测试运行。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.2 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">tb_locals</span></span></dt>
<dd><p>如果设置为 true，则局部变量将显示在回溯中。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.5 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">wasSuccessful</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>如果到目前为止运行的所有测试都通过，则返回 <code>True</code>，否则返回 <code>False</code>。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.4 版中更改： </span> 如果来自用 [[#unittest.expectedFailure|expectedFailure()]] 装饰器标记的测试中有任何 [[#unittest.TestResult.unexpectedSuccesses|unexpectedSuccesses]]，则返回 <code>False</code>。</p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>可以通过将 [[#unittest.TestResult.shouldStop|shouldStop]] 属性设置为 <code>True</code> 来调用此方法，以表示应中止正在运行的测试集。 <code>TestRunner</code> 对象应该尊重这个标志并返回而不运行任何额外的测试。</p>
<p>例如，当用户从键盘发出中断信号时，[[#unittest.TextTestRunner|TextTestRunner]] 类使用此功能来停止测试框架。 提供 <code>TestRunner</code> 实现的交互式工具可以以类似的方式使用它。</p></dd></dl>

<p>[[#unittest.TestResult|TestResult]] 类的以下方法用于维护内部数据结构，并且可以在子类中扩展以支持额外的报告要求。 这对于构建在运行测试时支持交互式报告的工具特别有用。</p>
<dl>
<dt><span class="sig-name descname"><span class="pre">startTest</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>当测试用例 ''test'' 即将运行时调用。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">stopTest</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>在测试用例 ''test'' 执行后调用，无论结果如何。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">startTestRun</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>在执行任何测试之前调用一次。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">stopTestRun</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>在所有测试执行后调用一次。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.1 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addError</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>'', ''<span class="n"><span class="pre">err</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>当测试用例 ''test'' 引发意外异常时调用。 ''err'' 是 [[../sys#sys|sys.exc_info()]]: <code>(type, value, traceback)</code> 返回的形式的元组。</p>
<p>默认实现将元组 <code>(test, formatted_err)</code> 附加到实例的 [[#unittest.TestResult.errors|errors]] 属性，其中 ''formatted_err'' 是从 ''err'' 派生的格式化回溯。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addFailure</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>'', ''<span class="n"><span class="pre">err</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>当测试用例 ''test'' 发出失败信号时调用。 ''err'' 是 [[../sys#sys|sys.exc_info()]]: <code>(type, value, traceback)</code> 返回的形式的元组。</p>
<p>默认实现将元组 <code>(test, formatted_err)</code> 附加到实例的 [[#unittest.TestResult.failures|failures]] 属性，其中 ''formatted_err'' 是从 ''err'' 派生的格式化回溯。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addSuccess</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>当测试用例 ''test'' 成功时调用。</p>
<p>默认实现什么都不做。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addSkip</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>'', ''<span class="n"><span class="pre">reason</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>在跳过测试用例 ''test'' 时调用。 ''reason'' 是测试给出跳过的原因。</p>
<p>默认实现将元组 <code>(test, reason)</code> 附加到实例的 [[#unittest.TestResult.skipped|跳过]] 属性。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addExpectedFailure</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>'', ''<span class="n"><span class="pre">err</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>当测试用例 ''test'' 失败或错误时调用，但被标记为 [[#unittest.expectedFailure|expectedFailure()]] 装饰器。</p>
<p>默认实现将元组 <code>(test, formatted_err)</code> 附加到实例的 [[#unittest.TestResult.expectedFailures|expectedFailures]] 属性，其中 ''formatted_err'' 是从 ''err'' 派生的格式化回溯。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addUnexpectedSuccess</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>当测试用例 ''test'' 被标记为 [[#unittest.expectedFailure|expectedFailure()]] 装饰器时调用，但成功了。</p>
<p>默认实现将测试附加到实例的 [[#unittest.TestResult.unexpectedSuccesses|unexpectedSuccesses]] 属性。</p></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">addSubTest</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>'', ''<span class="n"><span class="pre">subtest</span></span>'', ''<span class="n"><span class="pre">outcome</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>当子测试完成时调用。 ''test''是测试方法对应的测试用例。 ''subtest'' 是描述子测试的自定义 [[#unittest.TestCase|TestCase]] 实例。</p>
<p>如果 ''outcome'' 是 [[../constants#None|None]]，则子测试成功。 否则，它会失败并出现异常，其中 ''outcome'' 是 [[../sys#sys|sys.exc_info()]]: <code>(type, value, traceback)</code> 返回的形式的元组。</p>
<p>当结果为成功时，默认实现不执行任何操作，并将子测试失败记录为正常失败。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.4 版中的新功能。</span></p>

</div></dd></dl>
</dd></dl>

<dl>
<dt>''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">TextTestResult</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">stream</span></span>'', ''<span class="n"><span class="pre">descriptions</span></span>'', ''<span class="n"><span class="pre">verbosity</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>[[#unittest.TextTestRunner|TextTestRunner]] 使用的 [[#unittest.TestResult|TestResult]] 的具体实现。</p>
<div class="versionadded">

<p><span class="versionmodified added"> 3.2 新功能： </span> 这个类以前被命名为 <code>_TextTestResult</code>。 旧名称仍作为别名存在，但已弃用。</p>

</div></dd></dl>

; <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">defaultTestLoader</span></span>
: 旨在共享的 [[#unittest.TestLoader|TestLoader]] 类的实例。 如果不需要自定义 [[#unittest.TestLoader|TestLoader]]，则可以使用此实例而不是重复创建新实例。

<dl>
<dt>''<span class="pre">class</span>'' <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">TextTestRunner</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">stream</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">descriptions</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span>'', ''<span class="n"><span class="pre">verbosity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span>'', ''<span class="n"><span class="pre">failfast</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span>'', ''<span class="n"><span class="pre">buffer</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span>'', ''<span class="n"><span class="pre">resultclass</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">warnings</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="o"><span class="pre">*</span></span>'', ''<span class="n"><span class="pre">tb_locals</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>将结果输出到流的基本测试运行器实现。 如果''stream''为<code>None</code>，则默认使用[[../sys#sys|sys.stderr]]作为输出流。 这个类有一些可配置的参数，但本质上非常简单。 运行测试套件的图形应用程序应该提供替代实现。 此类实现应接受 <code>**kwargs</code> 作为在将功能添加到单元测试时构造运行程序更改的接口。</p>
<p>默认情况下，此运行程序显示 [[../exceptions#DeprecationWarning|DeprecationWarning]]、[[../exceptions#PendingDeprecationWarning|PendingDeprecationWarning]]、[[../exceptions#ResourceWarning|ResourceWarning]] 和 [[../exceptions#ImportWarning|ImportWarning]]，即使它们在默认情况下被 [[../warnings#warning-ignored|X185X]]忽略。 由 [[#deprecated-aliases|已弃用的单元测试方法]] 引起的弃用警告也是特殊情况，当警告过滤器为 <code>'default'</code> 或 <code>'always'</code> 时，它们将按顺序仅在每个模块出现一次以避免过多的警告信息。 可以使用 Python 的 <code>-Wd</code> 或 <code>-Wa</code> 选项（请参阅 [[../../using/cmdline#using-on-warnings|Warning control]]）覆盖此行为，并将 ''warnings'' 保留为 <code>None</code>。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span> 添加 <code>warnings</code> 参数。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.2 版更改： </span> 默认流设置为 [[../sys#sys|sys.stderr]] 在实例化时而不是导入时。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.5 版更改： </span> 添加了 tb_locals 参数。</p>

</div>
<dl>
<dt><span class="sig-name descname"><span class="pre">_makeResult</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>此方法返回 [[#unittest.TextTestRunner.run|run()]] 使用的 <code>TestResult</code> 的实例。 它不打算直接调用，但可以在子类中覆盖以提供自定义 <code>TestResult</code>。</p>
<p><code>_makeResult()</code> 实例化在 <code>TextTestRunner</code> 构造函数中作为 <code>resultclass</code> 参数传递的类或可调用对象。 如果未提供 <code>resultclass</code>，则默认为 [[#unittest.TextTestResult|TextTestResult]]。 结果类使用以下参数实例化：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">stream, descriptions, verbosity</syntaxhighlight>

</div>

</div></dd></dl>

<dl>
<dt><span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">test</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>该方法是<code>TextTestRunner</code>的主要公共接口。 此方法采用 [[#unittest.TestSuite|TestSuite]] 或 [[#unittest.TestCase|TestCase]] 实例。 [[#unittest.TestResult|TestResult]] 是通过调用 [[#unittest.TextTestRunner._makeResult|_makeResult()]] 创建的，然后运行测试并将结果打印到标准输出。</p></dd></dl>
</dd></dl>

<dl>
<dt><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">main</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">module</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'__main__'</span></span>'', ''<span class="n"><span class="pre">defaultTest</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">argv</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">testRunner</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">testLoader</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">unittest.defaultTestLoader</span></span>'', ''<span class="n"><span class="pre">exit</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span>'', ''<span class="n"><span class="pre">verbosity</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span>'', ''<span class="n"><span class="pre">failfast</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">catchbreak</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">buffer</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>'', ''<span class="n"><span class="pre">warnings</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>一个命令行程序，从 ''module'' 加载一组测试并运行它们； 这主要是为了使测试模块可以方便地执行。 此函数最简单的用法是在测试脚本的末尾包含以下行：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">if __name__ == '__main__':
    unittest.main()</syntaxhighlight>

</div>

</div>
<p>您可以通过传入 verbosity 参数来运行具有更详细信息的测试：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">if __name__ == '__main__':
    unittest.main(verbosity=2)</syntaxhighlight>

</div>

</div>
<p>如果没有通过 ''argv'' 指定测试名称，则 ''defaultTest'' 参数是单个测试的名称或要运行的可迭代测试名称。 如果未指定或 <code>None</code> 且未通过 ''argv'' 提供测试名称，则运行 ''模块'' 中的所有测试。</p>
<p>''argv'' 参数可以是传递给程序的选项列表，第一个元素是程序名称。 如果未指定或 <code>None</code>，则使用 [[../sys#sys|sys.argv]] 的值。</p>
<p>''testRunner'' 参数可以是一个测试运行器类，也可以是一个已经创建的实例。 默认情况下，<code>main</code> 调用 [[../sys#sys|sys.exit()]] 并使用退出代码指示测试运行成功或失败。</p>
<p>''testLoader'' 参数必须是一个 [[#unittest.TestLoader|TestLoader]] 实例，并且默认为 [[#unittest.defaultTestLoader|defaultTestLoader]]。</p>
<p><code>main</code> 通过传入参数 <code>exit=False</code> 支持在交互式解释器中使用。 这将在标准输出上显示结果而不调用 [[../sys#sys|sys.exit()]]：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">>>> from unittest import main
>>> main(module='test_module', exit=False)</syntaxhighlight>

</div>

</div>
<p>''failfast''、''catchbreak'' 和 ''buffer'' 参数与同名 [[#command-line-options|命令行选项]] 具有相同的效果。</p>
<p>''warnings'' 参数指定在运行测试时应该使用的 [[../warnings#warning-filter|warning 过滤器]] 。 如果未指定，如果将<code>-W</code>选项传递给'''python'''，则保持<code>None</code>（见[[../../using/cmdline#using-on-warnings|警告控制]]），否则将被设置<code>'default'</code>。</p>
<p>调用 <code>main</code> 实际上返回一个 <code>TestProgram</code> 类的实例。 这将测试运行的结果存储为 <code>result</code> 属性。</p>
<div class="versionchanged">

<p><span class="versionmodified changed"> 3.1 版更改： </span> 添加了 ''出口'' 参数。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed">在 3.2 版更改：</span>''详细''、''failfast''、''catchbreak''、''buffer''和29X警告[X] ] 参数已添加。</p>

</div>
<div class="versionchanged">

<p><span class="versionmodified changed"> 在 3.4 版中更改： </span> ''defaultTest'' 参数已更改为还接受可迭代的测试名称。</p>

</div></dd></dl>

<div id="load-tests-protocol" class="section">

==== load_tests 协议 ====

<div class="versionadded">

<span class="versionmodified added">3.2 版中的新功能。</span>


</div>
通过实现一个名为 <code>load_tests</code> 的函数，模块或包可以自定义在正常测试运行或测试发现期间如何从它们加载测试。

如果测试模块定义了 <code>load_tests</code>，它将被 [[#unittest.TestLoader.loadTestsFromModule|TestLoader.loadTestsFromModule()]] 调用，并带有以下参数：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">load_tests(loader, standard_tests, pattern)</syntaxhighlight>

</div>

</div>
其中 ''pattern'' 从 <code>loadTestsFromModule</code> 直接通过。 默认为 <code>None</code>。

它应该返回一个 [[#unittest.TestSuite|TestSuite]]。

''loader'' 是执行加载的 [[#unittest.TestLoader|TestLoader]] 的实例。 ''standard_tests'' 是默认情况下从模块加载的测试。 测试模块通常只想在标准测试集中添加或删除测试。 第三个参数在加载包作为测试发现的一部分时使用。

从一组特定的 [[#unittest.TestCase|TestCase]] 类加载测试的典型 <code>load_tests</code> 函数可能如下所示：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">test_cases = (TestCase1, TestCase2, TestCase3)

def load_tests(loader, tests, pattern):
    suite = TestSuite()
    for test_class in test_cases:
        tests = loader.loadTestsFromTestCase(test_class)
        suite.addTests(tests)
    return suite</syntaxhighlight>

</div>

</div>
如果发现是在包含包的目录中启动的，无论是从命令行还是通过调用 [[#unittest.TestLoader.discover|TestLoader.discover()]]，那么包 <code>__init__.py</code> 将被检查 <code>load_tests</code> . 如果该函数不存在，则发现将递归到包中，就好像它只是另一个目录。 否则，包测试的发现将留给 <code>load_tests</code>，它使用以下参数调用：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">load_tests(loader, standard_tests, pattern)</syntaxhighlight>

</div>

</div>
这应该返回一个 [[#unittest.TestSuite|TestSuite]] 代表包中的所有测试。 （<code>standard_tests</code> 将只包含从 <code>__init__.py</code> 收集的测试。）

因为模式被传递到 <code>load_tests</code> 包可以自由地继续（并可能修改）测试发现。 测试包的“什么都不做”<code>load_tests</code> 函数如下所示：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">def load_tests(loader, standard_tests, pattern):
    # top level directory cached on loader instance
    this_dir = os.path.dirname(__file__)
    package_tests = loader.discover(start_dir=this_dir, pattern=pattern)
    standard_tests.addTests(package_tests)
    return standard_tests</syntaxhighlight>

</div>

</div>
<div class="versionchanged">

<span class="versionmodified changed"> 在 3.5 版更改： </span> 由于包名称不可能与默认模式匹配，因此发现不再检查包名称是否匹配 ''模式'' 。


</div>

</div>

</div>

</div>
<div id="class-and-module-fixtures" class="section">

== 类和模块夹具 ==

类和模块级装置在 [[#unittest.TestSuite|TestSuite]] 中实现。 当测试套件遇到来自新类的测试时，则调用来自前一个类（如果有）的 <code>tearDownClass()</code>，然后是来自新类的 <code>setUpClass()</code>。

类似地，如果测试来自与先前测试不同的模块，则运行来自先前模块的 <code>tearDownModule</code>，然后是来自新模块的 <code>setUpModule</code>。

在所有测试运行后，运行最终的 <code>tearDownClass</code> 和 <code>tearDownModule</code>。

请注意，共享装置与测试并行化等 [潜在] 功能并不能很好地配合使用，并且它们会破坏测试隔离。 它们应该小心使用。

unittest 测试加载器创建的测试的默认顺序是将来自相同模块和类的所有测试组合在一起。 这将导致 <code>setUpClass</code> / <code>setUpModule</code>（等）每个类和模块只被调用一次。 如果您将顺序随机化，使得来自不同模块和类的测试彼此相邻，那么这些共享的夹具函数可能会在单个测试运行中被多次调用。

共享装置不适用于非标准订购的套件。 对于不想支持共享设备的框架，<code>BaseTestSuite</code> 仍然存在。

如果在共享夹具功能之一期间出现任何异常，则将测试报告为错误。 因为没有相应的测试实例，所以会创建一个 <code>_ErrorHolder</code> 对象（与 [[#unittest.TestCase|TestCase]] 具有相同的接口）来表示错误。 如果您只是使用标准的 unittest 测试运行器，那么这个细节并不重要，但如果您是框架作者，它可能是相关的。

<div id="setupclass-and-teardownclass" class="section">

=== setUpClass 和 tearDownClass ===

这些必须作为类方法实现：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">import unittest

class Test(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls._connection = createExpensiveConnectionObject()

    @classmethod
    def tearDownClass(cls):
        cls._connection.destroy()</syntaxhighlight>

</div>

</div>
如果您想要调用基类上的 <code>setUpClass</code> 和 <code>tearDownClass</code>，那么您必须自己调用它们。 [[#unittest.TestCase|TestCase]] 中的实现是空的。

如果在 <code>setUpClass</code> 期间引发异常，则不会运行类中的测试并且不会运行 <code>tearDownClass</code>。 跳过的课程将不会运行 <code>setUpClass</code> 或 <code>tearDownClass</code>。 如果异常是 [[#unittest.SkipTest|SkipTest]] 异常，则该类将报告为已跳过而不是错误。


</div>
<div id="setupmodule-and-teardownmodule" class="section">

=== setUpModule 和 tearDownModule ===

这些应该作为函数来实现：

<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()</syntaxhighlight>

</div>

</div>
如果在 <code>setUpModule</code> 中引发异常，则模块中的任何测试都不会运行，并且 <code>tearDownModule</code> 将不会运行。 如果异常是 [[#unittest.SkipTest|SkipTest]] 异常，则该模块将报告为已跳过而不是错误。

要添加即使在出现异常的情况下也必须运行的清理代码，请使用 <code>addModuleCleanup</code>：

<dl>
<dt><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">addModuleCleanup</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">function</span></span>'', ''<span class="o"><span class="pre">/</span></span>'', ''<span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span>'', ''<span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>在<code>tearDownModule()</code>之后添加一个函数，用于清理测试类中使用的资源。 函数的调用顺序与它们添加的顺序相反 (LIFO)。 当它们被添加时，任何参数和关键字参数都会被调用到 [[#unittest.addModuleCleanup|addModuleCleanup()]] 中。</p>
<p>如果 <code>setUpModule()</code> 失败，意味着 <code>tearDownModule()</code> 没有被调用，那么任何添加的清理函数仍然会被调用。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.8 版中的新功能。</span></p>

</div></dd></dl>

<dl>
<dt><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">doModuleCleanups</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span></dt>
<dd><p>在 <code>tearDownModule()</code> 之后或 <code>setUpModule()</code> 之后，如果 <code>setUpModule()</code> 引发异常，则无条件调用此函数。</p>
<p>它负责调用<code>addCleanupModule()</code>添加的所有清理函数。 如果您需要调用清理函数 ''prior'' 到 <code>tearDownModule()</code>，那么您可以自己调用 [[#unittest.doModuleCleanups|doModuleCleanups()]]。</p>
<p>[[#unittest.doModuleCleanups|doModuleCleanups()]] 一次从清理函数堆栈中弹出一个方法，因此可以随时调用。</p>
<div class="versionadded">

<p><span class="versionmodified added">3.8 版中的新功能。</span></p>

</div></dd></dl>


</div>

</div>
<div id="signal-handling" class="section">

== 信号处理 ==

<div class="versionadded">

<span class="versionmodified added">3.2 版中的新功能。</span>


</div>
单元测试的 [[#cmdoption-unittest-c|-c/--catch]] 命令行选项，以及 [[#unittest.main|unittest.main()]] 的 <code>catchbreak</code> 参数，提供更友好的控制处理- C 在测试运行期间。 启用 catch break 行为，control-C 将允许当前运行的测试完成，然后测试运行将结束并报告到目前为止的所有结果。 第二个 control-c 将以通常的方式引发 [[../exceptions#KeyboardInterrupt|KeyboardInterrupt]]。

control-c 处理信号处理程序尝试与安装自己的 [[../signal#signal|signal.SIGINT]] 处理程序的代码或测试保持兼容。 如果 <code>unittest</code> 处理程序被调用但 ''不是'' 安装的 [[../signal#signal|signal.SIGINT]] 处理程序，即 它已被被测系统替换并委托给它，然后它调用默认处理程序。 这通常是替换已安装处理程序并将其委托给它的代码的预期行为。 对于需要禁用 <code>unittest</code> control-c 处理的个别测试，可以使用 [[#unittest.removeHandler|removeHandler()]] 装饰器。

框架作者有一些实用函数可以在测试框架中启用 control-c 处理功能。

; <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">installHandler</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span>
: 安装 control-c 处理程序。 当接收到 [[../signal#signal|signal.SIGINT]] 时（通常响应用户按下 control-c），所有注册的结果都会调用 [[#unittest.TestResult.stop|stop()]]。

<dl>
<dt><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">registerResult</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">result</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>注册一个 [[#unittest.TestResult|TestResult]] 对象用于 control-c 处理。 注册结果会存储对它的弱引用，因此它不会阻止结果被垃圾收集。</p>
<p>如果未启用 control-c 处理，则注册 [[#unittest.TestResult|TestResult]] 对象没有副作用，因此测试框架可以无条件地注册它们创建的所有结果，而与是否启用处理无关。</p></dd></dl>

; <span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">removeResult</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">result</span></span>''<span class="sig-paren">)</span>
: 删除已注册的结果。 一旦结果被删除，那么 [[#unittest.TestResult.stop|stop()]] 将不再在该结果对象上调用以响应 control-c。

<dl>
<dt><span class="sig-prename descclassname"><span class="pre">unittest.</span></span><span class="sig-name descname"><span class="pre">removeHandler</span></span><span class="sig-paren">(</span>''<span class="n"><span class="pre">function</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span>''<span class="sig-paren">)</span></dt>
<dd><p>如果不带参数调用此函数，则会删除已安装的 control-c 处理程序。 此函数还可用作测试装饰器，以在执行测试时临时删除处理程序：</p>
<div class="highlight-python3 notranslate">

<div class="highlight">

<syntaxhighlight lang="python3">@unittest.removeHandler
def test_signal_handling(self):
    ...</syntaxhighlight>

</div>

</div></dd></dl>


</div>

</div>
<div class="clearer">



</div>

[[Category:Python 3.10 文档]]