unittest框架官方翻译：中文版

• ​​指数​​
• ​​模块​​ |
• ​​下一个​​ |
• ​​上一个​​ |

• 

• ​​Python​​ »
• 英语 法国 日本 朝鲜的 开发（3.8） 3.7.3rc1 3.6 3.5 2.7​​文档​​ »
• ​​Python标准库​​ »
• ​​开发工具​​ »
• |

源代码： ​​Lib / unittest / __ init__.py​​

（如果您已经熟悉测试的基本概念，则可能需要跳到​​断言方法列表​​。）

该​​unittest​​单元测试框架最初是由JUnit的启发，也有类似的味道在其他语言主要单元测试框架。它支持测试自动化，共享测试的设置和关闭代码，将测试聚合到集合中，以及测试与报告框架的独立性。

为此，​​unittest​​以面向对象的方式支持一些重要的概念：

• 测试夹具 甲测试夹具表示执行一个或多个测试，以及任何相联清除动作所需要的制剂。这可能涉及，例如，创建临时或代理数据库，目录或启动服务器进程。 测试用例 甲测试用例是测试的各个单元。它检查对特定输入集的特定响应。 ​​unittest​​提供了一个基类， ​​TestCase​​可用于创建新的测试用例。 测试套件 一个测试套件是测试案例，测试套件，或两者的集合。它用于聚合应该一起执行的测试。 试验跑步者 甲测试运行是编排的测试的执行，并提供结果给用户的部件。跑步者可以使用图形界面，文本界面，或返回特殊值来指示执行测试的结果。

也可以看看

• 模 ​​doctest​​ 另一种具有非常不同风味的测试支持模块。 ​​简单的Smalltalk测试：使用模式​​ Kent Beck关于使用共享模式测试框架的原始论文​​unittest​​。 ​​鼻子​​和​​pytest​​ 第三方单元测试框架，具有较轻的语法，用于编写测试。例如，。​​assert func(10) == 42​​​​Python测试工具分类​​ 广泛的Python测试工具列表，包括功能测试框架和模拟对象库。 ​​在Python邮件列表中测试​​ Python中用于讨论测试和测试工具的特殊兴趣小组。

​​Tools/unittestgui/unittestgui.py​​Python源代码发行版中的脚本是用于测试发现和执行的GUI工具。这主要是为了便于那些刚接触单元测试的人使用。对于生产环境，建议测试由​​Buildbot​​，​​Jenkins​​ 或 ​​Hudson​​等持续集成系统驱动 。

基本的例子

该​​unittest​​模块提供了一组丰富的工具，用于构建和运行测试。本节演示了一小部分工具足以满足大多数用户的需求。

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

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()

通过子类化创建测试用例​​unittest.TestCase​​。使用名称以字母开头的方法定义三个单独的测试 ​​test​​。此命名约定通知测试运行器哪些方法代表测试。

每次测试的关键是要求​​assertEqual()​​检查预期结果; ​​assertTrue()​​或​​assertFalse()​​ 核实情况; 或​​assertRaises()​​验证是否引发了特定异常。使用这些方法代替 ​​assert​​语句，以便测试运行器可以累积所有测试结果并生成报告。

该​​setUp()​​和​​tearDown()​​方法允许你定义将在每次测试方法之后执行的指令。它们在​​组织测试代码​​一节中有更详细的介绍。

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

...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

将​​-v​​选项传递给测试脚本将指示​​unittest.main()​​ 启用更高级别的详细程度，并生成以下输出：

test_isupper (__main__.TestStringMethods) ... ok
test_split (__main__.TestStringMethods) ... ok
test_upper (__main__.TestStringMethods) ... ok

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

OK

以上示例显示了最常用的​​unittest​​功能，足以满足许多日常测试需求。本文档的其余部分探讨了第一原则的完整功能集。

命令行界面

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

python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method

您可以使用模块名称和完全限定的类或方法名称的任意组合传递列表。

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

python -m unittest tests/test_something.py

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

您可以通过传入-v标志来运行具有更多详细信息（更高详细程度）的测试：

python -m unittest -v test_module

在没有参数的情况下执行​​Test Discovery​​时：

python -m unittest

有关所有命令行选项的列表：

python -m unittest -h

版本3.2中已更改：在早期版本中，只能运行单独的测试方法，而不能运行模块或类。

命令行选项

unittest支持以下命令行选项：

• ​​-b​​​​, ​​​​--buffer​​

在测试运行期间缓冲标准输出和标准错误流。通过测试期间的输出被丢弃。输出在测试失败或错误时正常回显，并添加到失败消息中。

• ​​-c​​​​, ​​​​--catch​​

Control-C在测试运行期间等待当前测试结束，然后报告所有结果到目前为止。第二个Control-C引发正常​​KeyboardInterrupt​​异常。

有关提供此功能的功能，请参阅​​信号处理​​。

• ​​-f​​​​, ​​​​--failfast​​

在第一次错误或失败时停止测试运​​行。

• ​​-k​​

仅运行与模式或子字符串匹配的测试方法和类。此选项可以多次使用，在这种情况下，包括与给定模式匹配的所有测试用例。

包含通配符（​​*​​）的模式与测试名称匹配使用​​fnmatch.fnmatchcase()​​; 否则使用简单的区分大小写的子串匹配。

模式与测试加载程序导入的完全限定的测试方法名称匹配。

例如，相匹配， 而不是。​​-kfoo​​​​foo_tests.SomeTest.test_something​​​​bar_tests.SomeTest.test_foo​​​​bar_tests.FooTest.test_something​​

• ​​--locals​​

在回溯中显示局部变量。

版本3.2中的新功能：命令行选项​​-b​​，​​-c​​并​​-f​​已添加。

3.5版中的新功能：命令行选项​​--locals​​。

3.7版中的新功能：命令行选项​​-k​​。

命令行还可用于测试发现，用于运行项目中的所有测试或仅运行子集。

测试发现

版本3.2中的新功能。

Unittest支持简单的测试发现。为了与测试发现兼容，所有测试文件必须是可从项目的顶级目录导入的​​模块​​或 ​​包​​（包括​​命名空间包​​）（这意味着它们的文件名必须是有效的​​标识符​​）。

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

cd project_directory
python -m unittest discover

注意

作为捷径，相当于 。如果要将参数传递给测试发现，则必须显式使用子命令。​​python -munittest​​​​python -m unittest discover​​​​discover​​

该​​discover​​子命令具有以下选项：

• ​​-v​​​​, ​​​​--verbose​​

详细输出

• ​​-s​​​​, ​​​​--start-directory​​​​ directory​​

启动发现的目录（​​.​​默认）

• ​​-p​​​​, ​​​​--pattern​​​​ pattern​​

匹配测试文件的模式（​​test*.py​​默认）

• ​​-t​​​​, ​​​​--top-level-directory​​​​ directory​​

项目的顶级目录（默认为启动目录）

的​​-s​​，​​-p​​和​​-t​​选项可以通过在如按顺序位置参数。以下两个命令行是等效的：

python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"

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

警告

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

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

如果您将启动目录作为包名称而不是目录路径提供，则discover会假定它从中导入的位置是您想要的位置，因此您不会收到警告。

测试模块和包可以通过​​load_tests协议​​自定义测试加载和发现。

版本3.4中已更改：测试发现支持​​命名空间包​​。

组织测试代码

单元测试的基本构建块是测试用例 - 必须设置并检查正确性的单个方案。在​​unittest​​，测试用例由​​unittest.TestCase​​实例表示。要创建自己的测试用例，必须编写​​TestCase​​或使用的子类 ​​FunctionTestCase​​。

​​TestCase​​实例的测试代码应该是完全独立的，这样它既可以单独运行，也可以与任意数量的其他测试用例任意组合运行。

最简单的​​TestCase​​子类将简单地实现一个测试方法（即名称以其开头的方法​​test​​），以便执行特定的测试代码：

import unittest

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

请注意，为了测试某些内容，我们使用基类​​assert*()​​ 提供的方法之一​​TestCase​​。如果测试失败，将引发一个带有解释性消息的异常，并将​​unittest​​ 测试用例标识为失败。任何其他异常都将被视为错误。

测试可以很多，并且它们的设置可以是重复的。幸运的是，我们可以通过实现一个被调用的方法来分解设置代码，​​setUp()​​测试框架将自动调用我们运行的每个测试：

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')

注意

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

如果该​​setUp()​​方法在测试运行时引发异常，则框架将认为测试遇到错误，并且不会执行测试方法。

同样，我们可以提供一个​​tearDown()​​在运行测试方法后整理的方法：

import unittest

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

    def tearDown(self):
        self.widget.dispose()

如果​​setUp()​​成功，​​tearDown()​​将运行测试方法是否成功。

测试代码的这种工作环境称为 测试夹具。创建一个新的TestCase实例作为用于执行每个单独测试方法的唯一测试夹具。因此 ​​setUp()​​，​​tearDown()​​和​​__init__()​​ 将在每个测试调用一次。

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

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

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())

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

• 测试模块可以从命令行独立运行。
• 测试代码可以更容易地与发货的代码分开。
• 没有充分理由改变测试代码以适应它测试的代码的诱惑力较小。
• 测试代码的修改频率要低于它测试的代码。
• 经过测试的代码可以更容易地重构。
• 用C语言编写的模块的测试无论如何都必须在单独的模块中，为什么不一致？
• 如果测试策略发生变化，则无需更改源代码。

重用旧的测试代码

一些用户会发现他们有自己想要运行的测试代码​​unittest​​，而不会将每个旧的测试函数转换为 ​​TestCase​​子类。

为此，​​unittest​​提供了一个​​FunctionTestCase​​课程。此子类​​TestCase​​可用于包装现有的测试函数。还可以提供设置和拆卸功能。

鉴于以下测试功能：

def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...

可以使用可选的设置和拆除方法创建一个等效的测试用例实例，如下所示：

testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)

注意

即使​​FunctionTestCase​​可以用于快速将现有测试基础转换为​​unittest​​基于系统，但不建议使用此方法。花时间设置适当的​​TestCase​​ 子类将使未来的测试重构变得无比容易。

在某些情况下，可能已使用该​​doctest​​ 模块编写了现有测试。如果是这样，​​doctest​​提供一个​​DocTestSuite​​可以​​unittest.TestSuite​​从现有​​doctest​​的测试中自动构建实例 的类。

跳过测试和预期的失败

3.1版中的新功能。

Unittest支持跳过单个测试方法甚至整个测试类。此外，它还支持将测试标记为“预期失败”，这项测试已被破坏并将失败，但不应将其视为失败 ​​TestResult​​。

跳过测试只是使用​​装饰器​​ 或其条件变体之一。​​skip()​​

基本跳过看起来像这样：

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

这是以详细模式运行上面示例的输出：

test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'

----------------------------------------------------------------------
Ran 3 tests in 0.005s

OK (skipped=3)

可以像方法一样跳过类：

@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass

​​TestCase.setUp()​​也可以跳过测试。当需要设置的资源不可用时，这很有用。

预期的失败使用​​expectedFailure()​​装饰器。

class ExpectedFailureTestCase(unittest.TestCase):
    @unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")

通过制作一个​​skip()​​在想要跳过测试时调用测试的装饰器，可以很容易地滚动自己的跳过装饰器 。除非传递的对象具有某个属性，否则此装饰器将跳过测试：

def skipUnlessHasattr(obj, attr):
    if hasattr(obj, attr):
        return lambda func: func
    return unittest.skip("{!r}{!r}".format(obj, attr))

以下装饰器实现测试跳过和预期的失败：

• ​​@​​​​unittest.​​​​skip​​（原因）

无条件地跳过装饰测试。 理由应该描述为什么跳过测试。

• ​​@​​​​unittest.​​​​skipIf​​（条件，原因）

如果条件为真，则跳过修饰的测试。

• ​​@​​​​unittest.​​​​skipUnless​​（条件，原因）

除非条件为真，否则跳过修饰的测试。

• ​​@​​​​unittest.​​​​expectedFailure​​

将测试标记为预期的失败。如果测试失败，将被视为成功。如果测试通过，则认为是失败。

• 异常​​unittest.​​​​SkipTest​​（原因）

引发此异常以跳过测试。

通常你可以使用​​TestCase.skipTest()​​或者使用其中一个跳过装饰器而不是直接提升它。

跳过的测试不会有​​setUp()​​或​​tearDown()​​绕过它们。跳过的课程不会有​​setUpClass()​​或没有​​tearDownClass()​​。跳过的模块不会有​​setUpModule()​​或没有​​tearDownModule()​​。

使用子测试区分测试迭代

版本3.4中的新功能。

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

例如，以下测试：

class NumbersTest(unittest.TestCase):

    def test_even(self):
        """
for i in range(0, 6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)

将产生以下输出：

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

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

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

类和函数

本节深入介绍了API的API ​​unittest​​。

测试用例

• class ​​unittest.​​​​TestCase​​（methodName ='runTest' ）

​​TestCase​​类的实例表示​​unittest​​Universe中的逻辑测试单元。此类旨在用作基类，具体测试由具体子类实现。此类实现测试运行器所需的接口，以允许它驱动测试，以及测试代码可用于检查和报告各种故障的方法。

每个实例​​TestCase​​将运行一个基本方法：名为methodName的方法。在大多数用途中​​TestCase​​，既不会更改methodName，也不会重新实现默认​​runTest()​​方法。

在3.2版中更改：​​TestCase​​可以在不提供methodName的情况下成功实例化 。这样可以更轻松地​​TestCase​​ 从交互式解释器进行实验。

​​TestCase​​ 实例提供三组方法：一组用于运行测试，另一组用于测试实现以检查条件和报告失败，以及一些查询方法允许收集有关测试本身的信息。

第一组（运行测试）中的方法是：

• ​​setUp​​（）

调用准备测试夹具的方法。在调用测试方法之前立即调用它; 除了​​AssertionError​​或​​SkipTest​​之外，此方法引发的任何异常都将被视为错误而非测试失败。默认实现什么都不做。

• ​​tearDown​​（）

调用测试方法后立即调用的方法并记录结果。即使测试方法引发异常，也会调用此方法，因此子类中的实现可能需要特别注意检查内部状态。任何异常，比其他 ​​AssertionError​​或​​SkipTest​​，通过该方法提出将被视为附加的错误，而不是一个测试失败（从而增加报告的错误的总数）。​​setUp()​​无论测试方法的结果如何，只有成功时才会调用此方法。默认实现什么都不做。

• ​​setUpClass​​（）

运行在单个类中的测试之前调用的类方法。 ​​setUpClass​​以类作为唯一参数调用，必须装饰为​​classmethod()​​：

@classmethod
def setUpClass(cls):
    ...

有关详细信息，请参阅​​类和模块夹具​​。

版本3.2中的新功能。

• ​​tearDownClass​​（）

已经运行了在单个类中的测试之后调用的类方法。 ​​tearDownClass​​以类作为唯一参数调用，必须装饰为​​classmethod()​​：

@classmethod
def tearDownClass(cls):
    ...

有关详细信息，请参阅​​类和模块夹具​​。

版本3.2中的新功能。

• ​​run​​（结果=无）

运行测试，将结果收集到​​TestResult​​作为结果传递的对象中。如果结果被省略或​​None​​，将创建的临时结果对象（通过调用​​defaultTestResult()​​ 方法）并使用。结果对象返回给​​run()​​调用者。

只需调用​​TestCase​​ 实例即可获得相同的效果。

在版本3.3中更改：以前的版本​​run​​没有返回结果。也没有调用实例。

• ​​skipTest​​（原因）

在测试方法期间调用此方法或​​setUp()​​跳过当前测试。有关详细信息，请参阅​​跳过测试和预期的故障​​。

3.1版中的新功能。

• ​​subTest​​（msg =无，**参数）

返回一个上下文管理器，它执行封闭的代码块作为子测试。 msg和params是可选的，任何值都会在子测试失败时显示，允许您清楚地识别它们。

测试用例可以包含任意数量的子测试声明，并且可以任意嵌套。

有关详细信息，请参阅​​使用子测试区分测试迭代​​。

版本3.4中的新功能。

• ​​debug​​（）

运行测试而不收集结果。这允许测试引发的异常传播到调用者，并可用于支持调试器下运行的测试。

本​​TestCase​​类提供了一些断言方法来检查并报告故障。下表列出了最常用的方法（有关更多断言方法，请参阅下表）：

所有assert方法都接受一个msg参数，如果指定，该参数将用作失败时的错误消息（另请参阅​​longMessage​​）。请注意，味精关键字参数可以传递给​​assertRaises()​​， ​​assertRaisesRegex()​​，​​assertWarns()​​，​​assertWarnsRegex()​​ 只有当它们被用作上下文管理器。

• ​​assertEqual​​（第一，第二，msg =无）

测试第一和第二是相等的。如果值不相等，则测试将失败。

此外，如果第一个和第二个是完全相同的类型，并且list，tuple，dict，set，frozenset或str之一或者子类​​addTypeEqualityFunc()​​向特定于类型的相等函数注册的任何类型将被调用，以便生成更有用的默认错误消息（另请参见​​特定于类型的方法列表​​）。

版本3.1中已更改：添加了类型特定的相等功能的自动调用。

在3.2版中更改：​​assertMultiLineEqual()​​添加为用于比较字符串的默认类型相等函数。

• ​​assertNotEqual​​（第一，第二，msg =无）

测试第一个和第二个不相等。如果值比较相等，则测试将失败。

• ​​assertTrue​​（expr，msg =无） ​​assertFalse​​（expr，msg =无）

测试expr是否为真（或假）。

请注意，这相当于而不是（使用后者）。当更具体的方法可用时（例如代替），也应避免使用此方法 ，因为它们在发生故障时提供更好的错误消息。​​bool(expr) is True​​​​expr is True​​​​assertIs(expr,True)​​​​assertEqual(a, b)​​​​assertTrue(a == b)​​

• ​​assertIs​​（第一，第二，msg =无） ​​assertIsNot​​（第一，第二，msg =无）

测试第一个和第二个评估（或不评估）同一个对象。

3.1版中的新功能。

• ​​assertIsNone​​（expr，msg =无） ​​assertIsNotNone​​（expr，msg =无）​​¶​​

测试expr是否（或不是）​​None​​。

3.1版中的新功能。

• ​​assertIn​​（第一，第二，msg =无） ​​assertNotIn​​（第一，第二，msg =无）

首先测试（或不测试）秒。

3.1版中的新功能。

• ​​assertIsInstance​​（obj，cls，msg =无） ​​assertNotIsInstance​​（obj，cls，msg =无）

测试obj是（或不是）cls的实例（可以是类的类或元组，如支持的​​isinstance()​​）。要检查确切的类型，请使用。​​assertIs(type(obj), cls)​​

版本3.2中的新功能。

还可以使用以下方法检查异常，警告和日志消息的生成：

• ​​assertRaises​​（例外，可调用，* args，** kwds ） ​​assertRaises​​（例外，*，msg =无）

在使用也传递给的任何位置或关键字参数 调用callable时，测试是否引发异常​​assertRaises()​​。如果引发异常则测试通过，如果引发另一个异常则为错误，如果没有引发异常则失败。要捕获任何一组异常，可以将包含异常类的元组作为异常传递。

如果只给出异常和可能的msg参数，则返回一个上下文管理器，以便测试中的代码可以内联而不是作为函数编写：

with self.assertRaises(SomeException):
    do_something()

当用作上下文管理器时，​​assertRaises()​​接受附加关键字参数msg。

上下文管理器将捕获的异常对象存储在其 ​​exception​​属性中。如果打算对引发的异常执行额外检查，这可能很有用：

with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)

版本3.1中已更改：添加了​​assertRaises()​​用作上下文管理器的功能。

在3.2版中更改：添加了​​exception​​属性。

在版本3.3中更改：在用作上下文管理器时添加了msg关键字参数。

• ​​assertRaisesRegex​​（例外，正则表达式，可调用，* args，** kwds ） ​​assertRaisesRegex​​（例外，正则表达式，*，msg =无）

喜欢​​assertRaises()​​但也测试正则表达式匹配引发的异常的字符串表示。 regex可以是正则表达式对象，也可以是包含适合使用的正则表达式的字符串​​re.search()​​。例子：

self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')

要么：

with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')

版本3.1中的新功能：名称下​​assertRaisesRegexp​​。

在3.2版中更改：重命名为​​assertRaisesRegex()​​。

在版本3.3中更改：在用作上下文管理器时添加了msg关键字参数。

• ​​assertWarns​​（警告，可调用，* args，** kwds ） ​​assertWarns​​（警告，*，msg =无）

使用也传递给的任何位置或关键字参数 调用callable时，测试是否触发警告​​assertWarns()​​。如果警告被触发则测试通过，否则测试失败。任何异常都是错误。要捕获任何一组警告，可以将包含警告类的元组作为警告传递。

如果只给出警告和可能的msg参数，则返回一个上下文管理器，以便测试中的代码可以内联而不是函数写入：

with self.assertWarns(SomeWarning):
    do_something()

当用作上下文管理器时，​​assertWarns()​​接受附加关键字参数msg。

上下文管理器将捕获的警告对象存储在其 ​​warning​​属性中，以及触发​​filename​​和​​lineno​​属性中的警告的源代码行。如果打算对捕获的警告执行额外检查，这可能很有用：

with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)

无论调用何种警告过滤器，此方法都有效。

版本3.2中的新功能。

在版本3.3中更改：在用作上下文管理器时添加了msg关键字参数。

• ​​assertWarnsRegex​​（警告，正则表达式，可调用，* args，** kwds ） ​​assertWarnsRegex​​（警告，正则表达式，*，msg =无）

喜欢​​assertWarns()​​但也测试正则表达式匹配触发警告的消息。 regex可以是正则表达式对象，也可以是包含适合使用的正则表达式的字符串​​re.search()​​。例：

self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')

要么：

with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')

版本3.2中的新功能。

在版本3.3中更改：在用作上下文管理器时添加了msg关键字参数。

• ​​assertLogs​​（logger = None，level = None ）

一个上下文管理器，用于测试至少一条消息记录在记录器或其子节点上，至少具有给定 级别。

如果给定，则记录器应该是​​logging.Logger​​对象或 ​​str​​给出记录器的名称。默认为根记录器，它将捕获所有消息。

如果给定，level应该是数字日志记录级别或其等效字符串（例如，​​"ERROR"​​或者 ​​logging.ERROR​​）。默认是​​logging.INFO​​。

如果​​with​​ 块内发出的消息至少与记录器和级别条件匹配，则测试通过，否则失败。

上下文管理器返回的对象是一个记录助手，它记录匹配的日志消息。它有两个属性：

• ​​records​​

​​logging.LogRecord​​匹配日志消息的对象列表。

• ​​output​​

​​str​​具有匹配消息的格式化输出的对象列表。

例：

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'])

版本3.4中的新功能。

还有其他方法用于执行更具体的检查，例如：

• ​​assertAlmostEqual​​（第一，第二，places = 7，msg = None，delta = None ） ​​assertNotAlmostEqual​​（第一，第二，places = 7，msg = None，delta = None ）

测试第一和第二近似（或不近似）通过计算差，四舍五入到小数点的给定数目相等的地方（默认7），并与零进行比较。请注意，这些方法将值四舍五入到给定的小数位数（即​​round()​​函数），而不是有效数字。

如果提供delta而不是地点，则第一个和第二个之间的差值必须小于或等于（或大于）delta。

提供delta和place都会提高a ​​TypeError​​。

在版本3.2中更改：​​assertAlmostEqual()​​自动考虑比较相等的几乎相等的对象。 ​​assertNotAlmostEqual()​​如果对象比较相等则自动失败。添加了delta关键字参数。

• ​​assertGreater​​（第一，第二，msg =无） ​​assertGreaterEqual​​（第一，第二，msg =无） ​​assertLess​​（第一，第二，msg =无） ​​assertLessEqual​​（第一，第二，msg =无）

根据方法名称，首先分别测试>，> =，<或<= 秒。如果没有，测试将失败：

>>>

>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"

3.1版中的新功能。

• ​​assertRegex​​（text，regex，msg = None ） ​​assertNotRegex​​（text，regex，msg = None ）

测试正则表达式搜索匹配（或不匹配）文本。如果失败，错误消息将包括模式和文本（或模式和意外匹配的文本部分）。 regex 可以是正则表达式对象，也可以是包含适合使用的正则表达式的字符串​​re.search()​​。

版本3.1中的新功能：名称下​​assertRegexpMatches​​。

版本3.2中已更改：该方法​​assertRegexpMatches()​​已重命名为 ​​assertRegex()​​。

版本3.2中的新功能：​​assertNotRegex()​​。

3.5版中的新功能：该名称​​assertNotRegexpMatches​​是不推荐使用的别名​​assertNotRegex()​​。

• ​​assertCountEqual​​（第一，第二，msg =无）

测试该序列首先包含与第二个相同的元素，而不管它们的顺序如何。如果没有，将生成列出序列之间差异的错误消息。

比较第一个和 第二个时，不会忽略重复元素。它验证每个元素在两个序列中是否具有相同的计数。相当于： 但也适用于不可用对象的序列。​​assertEqual(Counter(list(first)), Counter(list(second)))​​

版本3.2中的新功能。

该​​assertEqual()​​方法将相同类型的对象的相等性检查分派给不同类型的特定方法。这些方法已经针对大多数内置类型实现，但也可以使用​​addTypeEqualityFunc()​​以下方法注册新方法：

• ​​addTypeEqualityFunc​​（typeobj，功能）

注册一个特定于类型的方法，​​assertEqual()​​用于检查两个完全相同的typeobj（而不是子类）的对象是否相等。 函数必须采用两个位置参数和第三个msg = None关键字参数​​assertEqual()​​。​​self.failureException(msg)​​当检测到前两个参数之间的不等式时，它必须提出 - 可能提供有用的信息并在错误消息中详细解释不等式。

3.1版中的新功能。

自动使用的特定于类型的方法列表 ​​assertEqual()​​总结在下表中。请注意，通常不必直接调用这些方法。

• ​​assertMultiLineEqual​​（第一，第二，msg =无）

测试多行字符串首先等于字符串秒。当不相等时，突出显示差异的两个字符串的差异将包含在错误消息中。在比较字符串时，默认使用此方法​​assertEqual()​​。

3.1版中的新功能。

• ​​assertSequenceEqual​​（第一个，第二个，msg =无，seq_type =无）

测试两个序列是否相等。如果提供了seq_type，则 first和second都必须是seq_type的实例，否则将引发失败。如果序列不同，则构造错误消息以显示两者之间的差异。

此方法不是直接调用​​assertEqual()​​，而是用于实现​​assertListEqual()​​和 ​​assertTupleEqual()​​。

3.1版中的新功能。

• ​​assertListEqual​​（第一，第二，msg =无） ​​assertTupleEqual​​（第一，第二，msg =无）

测试两个列表或元组是否相等。如果不是，则构造一条错误消息，仅显示两者之间的差异。如果其中一个参数的类型错误，也会引发错误。在比较列表或元组时，默认使用这些方法 ​​assertEqual()​​。

3.1版中的新功能。

• ​​assertSetEqual​​（第一，第二，msg =无）

测试两组是否相等。如果不是，则构造一个错误消息，列出这些集之间的差异。默认情况下，使用此方法比较set或frozensets时使用此方法​​assertEqual()​​。

如果第一个或第二个中的任何一个没有​​set.difference()​​ 方法，则会失败。

3.1版中的新功能。

• ​​assertDictEqual​​（第一，第二，msg =无）

测试两个词典是否相等。如果不是，则构造一条错误消息，显示字典中的差异。默认情况下，此方法将用于比较调用中的字典​​assertEqual()​​。

3.1版中的新功能。

最后​​TestCase​​提供了以下方法和属性：

• ​​fail​​（msg =无）

使用msg或​​None​​错误消息无条件地发出测试失败信号。

• ​​failureException​​

此类属性提供测试方法引发的异常。如果测试框架需要使用专门的异常，可能携带额外的信息，它必须将此异常子类化，以便与框架“公平”。该属性的初始值为 ​​AssertionError​​。

• ​​longMessage​​

此类属性确定将自定义失败消息作为失败的assertXYY调用的msg参数传递时发生的情况。 ​​True​​是默认值。在这种情况下，自定义消息将附加到标准故障消息的末尾。设置​​False​​为时，自定义消息将替换标准消息。

通过在调用assert方法之前​​True​​或​​False​​之前分配实例属性self.longMessage，可以在单个测试方法中覆盖类设置。

在每次测试调用之前，类设置都会重置。

3.1版中的新功能。

• ​​maxDiff​​

此属性通过断言失败时报告差异的方法来控制输出的差异的最大长度。默认为80 * 8个字符。受此属性影响的断言方法 ​​assertSequenceEqual()​​（包括委托给它的所有序列比较方法）​​assertDictEqual()​​和​​assertMultiLineEqual()​​。

设置​​maxDiff​​为​​None​​表示没有最大差异长度。

版本3.2中的新功能。

测试框架可以使用以下方法收集有关测试的信息：

• ​​countTestCases​​（）

返回此测试对象表示的测试数。对于 ​​TestCase​​情况下，这将永远是​​1​​。

• ​​defaultTestResult​​（）

返回应该用于此测试用例类的测试结果类的实例（如果没有为该​​run()​​方法提供其他结果实例 ）。

对于​​TestCase​​情况下，这将永远是一个实例 ​​TestResult​​; 子类​​TestCase​​应该根据需要覆盖它。

• ​​id​​（）

返回标识特定测试用例的字符串。这通常是测试方法的全名，包括模块和类名。

• ​​shortDescription​​（）

返回测试的描述，或者​​None​​如果没有提供描述。此方法的默认实现返回测试方法的docstring的第一行（如果可用）或​​None​​。

版本3.1中已更改：在3.1中，即使存在docstring，也会将测试名称添加到简短描述中。这导致了unittest扩展的兼容性问题，并且添加了测试名称已移至 ​​TextTestResult​​Python 3.2中。

• ​​addCleanup​​（函数，* args，** kwargs ）

添加要调用的函数以​​tearDown()​​清除测试期间使用的资源。函数将按其添加顺序（LIFO）的相反顺序调用。它们​​addCleanup()​​在添加时通过任何参数和关键字参数调用 。

如果​​setUp()​​失败，意味着​​tearDown()​​没有调用，那么仍然会调用添加的任何清理函数。

3.1版中的新功能。

• ​​doCleanups​​（）

这种方法被无条件后调用​​tearDown()​​，或之后​​setUp()​​如果​​setUp()​​抛出一个异常。

它负责调用所有添加的清理函数 ​​addCleanup()​​。如果你需要清除函数被调用 之前到​​tearDown()​​，那么你可以调用​​doCleanups()​​ 自己。

​​doCleanups()​​ 一次一个地从一堆清理函数中弹出方法，因此可以随时调用它。

3.1版中的新功能。

• class ​​unittest.​​​​FunctionTestCase​​（testFunc，setUp = None，tearDown = None，description = None ）

此类实现​​TestCase​​接口的一部分，允许测试运行器驱动测试，但不提供测试代码可用于检查和报告错误的方法。这用于使用传统测试代码创建测试用例，允许将其集成到 ​​unittest​​基于测试的框架中。

不推荐使用的别名

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

自3.1版以来不推荐使用：第二列中列出的失败*别名。

自3.2版以来不推荐使用：第三列中列出的断言*别名。

自从3.2版本不推荐使用：​​assertRegexpMatches​​与​​assertRaisesRegexp​​已更名为 ​​assertRegex()​​和​​assertRaisesRegex()​​。

从版本3.5开始不推荐使用：​​assertNotRegexpMatches​​赞成的名称​​assertNotRegex()​​。

分组测试

• class ​​unittest.​​​​TestSuite​​（tests =（））

此类表示各个测试用例和测试套件的集合。该类提供了测试运行器所需的接口，以允许它像任何其他测试用例一样运行。运行​​TestSuite​​实例与迭代套件相同，单独运行每个测试。

如果给出了测试，它必须是可以迭代的单个测试用例或最初用于构建套件的其他测试套件。提供了其他方法，以便稍后将测试用例和套件添加到集合中。

​​TestSuite​​对象的行为与​​TestCase​​对象非常相似，除非它们实际上没有实现测试。相反，它们用于将测试聚合到应该一起运行的测试组中。可以使用一些其他方法向​​TestSuite​​实例添加测试：

• ​​addTest​​（测试）

添加一个​​TestCase​​或​​TestSuite​​到套件。

• ​​addTests​​（测试）

将可迭代的 实例​​TestCase​​和​​TestSuite​​实例中的所有测试添加到此测试套件中。

这相当于迭代测试，调用​​addTest()​​每个元素。

​​TestSuite​​与以下方法共享​​TestCase​​：

• ​​run​​（结果）

运行与此套件关联的测试，将结果收集到作为结果传递的测试结果对象中。需要注意的是不同​​TestCase.run()​​，​​TestSuite.run()​​需要的结果对象中进行传递。

• ​​debug​​（）

运行与此套件关联的测试而不收集结果。这允许测试引发的异常传播到调用者，并可用于支持调试器下的运行测试。

• ​​countTestCases​​（）

返回此测试对象表示的测试数，包括所有单独的测试和子套件。

• ​​__iter__​​（）

按a分组的测试​​TestSuite​​始终通过迭代访问。子类可以通过覆盖来懒惰地提供测试​​__iter__()​​。请注意，可以在单个套件上多次调用此方法（例如，在计算测试或比较相等性时），因此之前重复迭代返回的测试​​TestSuite.run()​​对于每次调用迭代必须相同。之后​​TestSuite.run()​​，调用者不应该依赖此方法返回的测试，除非调用者使用覆盖的子类​​TestSuite._removeTestAtIndex()​​来保留测试引用。

在版本3.2中更改：在早期版本中，​​TestSuite​​访问测试直接而不是通过迭代进行测试，因此覆盖​​__iter__()​​不足以提供测试。

改变在3.4版：在早期版本的​​TestSuite​​召开给每个引用 ​​TestCase​​之后​​TestSuite.run()​​。子类可以通过覆盖来恢复该行为​​TestSuite._removeTestAtIndex()​​。

在​​TestSuite​​对象的典型用法中，该​​run()​​方法由​​TestRunner​​而不是由最终用户测试工具调用。

加载和运行测试

• 类​​unittest.​​​​TestLoader​​

所述​​TestLoader​​类被用来创建从类和模块的测试套件。通常，不需要创建此类的实例; 该 ​​unittest​​模块提供了一个可以共享的实例 ​​unittest.defaultTestLoader​​。但是，使用子类或实例可以自定义一些可配置的属性。

​​TestLoader​​ 对象具有以下属性：

• ​​errors​​

加载测试时遇到的非致命错误列表。任何时候都不会被加载器重置。致命错误由相关的方法发出信号，该方法向调用者提出异常。非致命错误也由合成测试指示，该测试将在运行时引发原始错误。

版本3.5中的新功能。

​​TestLoader​​ 对象具有以下方法：

• ​​loadTestsFromTestCase​​（testCaseClass ）

返回包含在​​TestCase​​-derived中 的所有测试用例的套件​​testCaseClass​​。

为每个命名的方法创建一个测试用例实例 ​​getTestCaseNames()​​。默认情况下，这些是以...开头的方法名称​​test​​。如果​​getTestCaseNames()​​没有返回方法，但​​runTest()​​实现了该方法，则会为该方法创建一个测试用例。

• ​​loadTestsFromModule​​（模块，模式=无）

返回给定模块中包含的所有测试用例的套件。此方法在模块中搜索派生自的类，​​TestCase​​并为为该类定义的每个测试方法创建该类的实例。

注意

虽然使用​​TestCase​​-derived类的层次结构可以方便地共享fixture和helper函数，但是在不打算直接实例化的基类上定义测试方法并不适合这种方法。但是，当灯具不同并在子类中定义时，这样做会很有用。

如果模块提供了一个​​load_tests​​函数，则会调用它来加载测试。这允许模块自定义测试加载。这是​​load_tests协议​​。的图案参数作为第三个参数来传递​​load_tests​​。

版本3.2中已更改：支持​​load_tests​​添加。

版本3.5中已更改：已弃用并忽略未记录和非正式的use_load_tests默认参数，但仍可接受向后兼容性。该方法现在还接受仅关键字参数 模式，该模式​​load_tests​​作为第三个参数传递。

• ​​loadTestsFromName​​（名称，模块=无）

给出一个字符串说明符，返回所有测试用例的套件。

说明符名称是“点名称”，可以解析模块，测试用例类，测试用例类中的测试方法， ​​TestSuite​​实例或返回​​TestCase​​或​​TestSuite​​实例的可调用对象 。这些检查按此处列出的顺序应用; 也就是说，可能的测试用例类的方法将被选为“测试用例类中的测试方法”，而不是“可调用对象”。

例如，如果您的模块​​SampleTests​​包含带有三个测试方法（，和）的 ​​TestCase​​-derived类，则说明符将使此方法返回一个将运行所有三个测试方法的套件。使用说明符 会使它返回一个仅运行测试方法的测试套件。说明符可以引用尚未导入的模块和包; 它们将作为副作用导入。​​SampleTestCase​​​​test_one()​​​​test_two()​​​​test_three()​​​​'SampleTests.SampleTestCase'​​​​'SampleTests.SampleTestCase.test_two'​​​​test_two()​​

该方法可选地解析相对于给定模块的名称。

在版本3.5中更改：如果在遍历名称时发生​​ImportError​​或​​AttributeError​​发生， 则将返回在运行时引发该错误的综合测试。这些错误包含在self.errors累积的错误中。

• ​​loadTestsFromNames​​（名称，模块=无）

与之类似​​loadTestsFromName()​​，但采用一系列名称而不是单个名称。返回值是一个测试套件，它支持为每个名称定义的所有测试。

• ​​getTestCaseNames​​（testCaseClass ）

返回在testCaseClass中找到的已排序的方法名称序列; 这应该是一个子类​​TestCase​​。

• ​​discover​​（start_dir，pattern ='test * .py'，top_level_dir = None ）

通过从指定的起始目录递归到子目录中查找所有测试模块，并返回包含它们的TestSuite对象。仅加载与模式匹配的测试文件。（使用shell样式模式匹配。）只加载可导入的模块名称（即有效的Python标识符）。

所有测试模块必须可从项目的顶层导入。如果起始目录不是顶级目录，则必须单独指定顶级目录。

如果导入模块失败（例如由于语法错误），则会将其记录为单个错误，并且将继续发现。如果导致导入失败​​SkipTest​​，则会将其记录为跳过而不是错误。

如果找到包（包含名为file的目录​​__init__.py​​），则将检查包的​​load_tests​​功能。如果存在，那么它将被调用 。测试发现需要注意确保在调用期间仅检查一次包测试，即使load_tests函数本身调用也是如此 。​​package.load_tests(loader, tests, pattern)​​​​loader.discover​​

如果​​load_tests​​存在，那么发现并没有递归放入包中，​​load_tests​​负责加载包中的所有测试。

故意不将该模式存储为loader属性，以便包可以继续自己发现。存储top_level_dir，因此 ​​load_tests​​不需要将此参数传递给 ​​loader.discover()​​。

start_dir可以是虚线模块名称以及目录。

版本3.2中的新功能。

版本3.4中更改：​​SkipTest​​导入时引发的模块记录为跳过，而不是错误。发现适用于​​命名空间包​​。在导入之前对路径进行排序，以便即使基础文件系统的排序不依赖于文件名，执行顺序也是相同的。

在版本3.5中更改：现在检查找到的包​​load_tests​​，无论它们的路径是否与模式匹配，因为包名称不可能与默认模式匹配。

​​TestLoader​​可以通过子类化或在实例上赋值来配置a的以下属性：

• ​​testMethodPrefix​​

给出方法名称前缀的字符串，将被解释为测试方法。默认值为​​'test'​​。

这影响了​​getTestCaseNames()​​所有​​loadTestsFrom*()​​ 方法。

• ​​sortTestMethodsUsing​​

在对它们进行排序​​getTestCaseNames()​​和所有​​loadTestsFrom*()​​方法时用于比较方法名称的函数 。

• ​​suiteClass​​

可调用对象，从测试列表构造测试套件。不需要对结果对象的方法。默认值是 ​​TestSuite​​类。

这会影响所有​​loadTestsFrom*()​​方法。

• ​​testNamePatterns​​

测试方法必须匹配的Unix shell样式通配符测试名称模式列表，以包含在测试套件中（请参阅​​-v​​选项）。

如果此属性不是​​None​​（缺省值），则要包含在测试套件中的所有测试方法都必须与此列表中的某个模式匹配。请注意，匹配始终使用​​fnmatch.fnmatchcase()​​，因此与传递给​​-v​​选项的模式不同，必须使用​​*​​通配符转换简单子字符串模式。

这会影响所有​​loadTestsFrom*()​​方法。

版本3.7中的新功能。

• 类​​unittest.​​​​TestResult​​

此类用于编译有关哪些测试成功以及哪些测试失败的信息。

一个​​TestResult​​对象存储一组测试的结果。在 ​​TestCase​​和​​TestSuite​​班保证结果正确记录; 测试作者无需担心记录测试结果。

构建在其上的测试框架​​unittest​​可能希望访问​​TestResult​​通过运行一组测试生成的 对象以用于报告目的; 为此目的​​TestResult​​，​​TestRunner.run()​​方法返回一个实例 。

​​TestResult​​ 在检查运行一组测试的结果时，实例具有以下属性：

• ​​errors​​

包含2元组​​TestCase​​实例和包含格式化回溯的字符串的列表。每个元组代表一个引发意外异常的测试。

• ​​failures​​

包含2元组​​TestCase​​实例和包含格式化回溯的字符串的列表。每个元组代表一个测试，其中使用这些​​TestCase.assert*()​​方法明确地发出故障信号。

• ​​skipped​​

包含2元组​​TestCase​​实例和字符串的列表，其中包含跳过测试的原因。

3.1版中的新功能。

• ​​expectedFailures​​

包含2元组​​TestCase​​实例和包含格式化回溯的字符串的列表。每个元组代表测试用例的预期失败。

• ​​unexpectedSuccesses​​

包含​​TestCase​​标记为预期失败但成功的实例的列表。

• ​​shouldStop​​

设置为​​True​​应该停止执行测试​​stop()​​。

• ​​testsRun​​

到目前为止测试的总数。

• ​​buffer​​

如果设置为true，​​sys.stdout​​并且​​sys.stderr​​将在之间进行缓冲 ​​startTest()​​和​​stopTest()​​被调用。收集的输出只会回显到真实的​​sys.stdout​​，​​sys.stderr​​如果测试失败或错误。任何输出也附加到故障/错误消息。

版本3.2中的新功能。

• ​​failfast​​

如果​​stop()​​在第一次失败或错误时调用设置为true ，则暂停测试运行。

版本3.2中的新功能。

• ​​tb_locals​​

如果设置为true，则局部变量将显示在回溯中。

版本3.5中的新功能。

• ​​wasSuccessful​​（）

返回​​True​​如果所有测试跑这么远都过去了，否则返回 ​​False​​。

版本3.4中更改：​​False​​如果有任何​​unexpectedSuccesses​​ 来自​​expectedFailure()​​装饰器的测试，则返回。

• ​​stop​​（）

可以调用此方法来表示应该通过将​​shouldStop​​属性设置为中止来运行正在运行的测试集​​True​​。 ​​TestRunner​​对象应该尊重此标志并返回而不运行任何其他测试。

例如，​​TextTestRunner​​当用户通过键盘发出中断信号时，类使用此功能来停止测试框架。提供​​TestRunner​​实现的交互式工具可以以类似的方式使用它。

​​TestResult​​该类的以下方法用于维护内部数据结构，并且可以在子类中进行扩展以支持其他报告要求。这对于构建在运行测试时支持交互式报告的工具特别有用。

• ​​startTest​​（测试）

在即将运行测试用例测试时调用。

• ​​stopTest​​（测试）

无论结果如何，在执行测试用例测试后调用。

• ​​startTestRun​​（）

在执行任何测试之前调用一次。

3.1版中的新功能。

• ​​stopTestRun​​（）

执行所有测试后调用一次。

3.1版中的新功能。

• ​​addError​​（测试，错误）

在测试用例测试引发意外异常时调用。错误是由以下形式返回的形式的元组​​sys.exc_info()​​：。​​(type,value, traceback)​​

默认实现将元组附加到实例的属性，其中formatted_err是从err派生的格式化回溯。​​(test,formatted_err)​​​​errors​​

• ​​addFailure​​（测试，错误）

当测试用例测试发出故障信号时调用。错误是由以下形式返回的形式的元组​​sys.exc_info()​​：。​​(type,value, traceback)​​

默认实现将元组附加到实例的属性，其中formatted_err是从err派生的格式化回溯。​​(test,formatted_err)​​​​failures​​

• ​​addSuccess​​（测试）

在测试用例测试成功时调用。

默认实现什么都不做。

• ​​addSkip​​（测试，原因）

在跳过测试用例测试时调用。 原因是测试给跳过的原因。

默认实现将元组附加到实例的属性。​​(test, reason)​​​​skipped​​

• ​​addExpectedFailure​​（测试，错误）

在测试用例测试失败时调用，但是用​​expectedFailure()​​装饰器标记 。

默认实现将元组附加到实例的属性，其中formatted_err 是从err派生的格式化回溯。​​(test,formatted_err)​​​​expectedFailures​​

• ​​addUnexpectedSuccess​​（测试）

当测试用例测试用​​expectedFailure()​​装饰器标记 时调用，但成功。

默认实现将测试附加到实例的 ​​unexpectedSuccesses​​属性。

• ​​addSubTest​​（测试，分测试，结果）

在子测试结束时调用。 test是与测试方法对应的测试用例。 subtest是​​TestCase​​描述子测试的自定义 实例。

如果结果是​​None​​，则子测试成功。否则，它失败并出现异常，其中结果是由以下形式返回的表单的元组​​sys.exc_info()​​：。​​(type, value, traceback)​​

结果成功时，默认实现不执行任何操作，并将子测试失败记录为正常故障。

版本3.4中的新功能。

• class ​​unittest.​​​​TextTestResult​​（流，描述，详细程度）

具体实现的​​TestResult​​被使用 ​​TextTestRunner​​。

版本3.2中的新功能：此类之前已命名​​_TextTestResult​​。旧名称仍作为别名存在，但已弃用。

• ​​unittest.​​​​defaultTestLoader​​

​​TestLoader​​要共享的类的实例。如果不需要自定义，​​TestLoader​​则可以使用此实例而不是重复创建新实例。

• class ​​unittest.​​​​TextTestRunner​​（stream = None，description = True，verbosity = 1，failfast = False，buffer = False，resultclass = None，warnings = None，*，tb_locals = False ）

将结果输出到流的基本测试运行器实现。如果流 是​​None​​，默认，​​sys.stderr​​用作输出流。这个类有一些可配置的参数，但基本上非常简单。运行测试套件的图形应用程序应提供备用实现。​​**kwargs​​当将功能添加到unittest时，此类实现应该接受构造运行程序更改的接口。

默认情况下，这个亚军显示​​DeprecationWarning​​， ​​PendingDeprecationWarning​​，​​ResourceWarning​​和​​ImportWarning​​即使他们是​​默认被忽略掉​​。不​​推荐使用的单元测试方法​​导致的​​弃用​​警告也是特殊的，当警告过滤器为​​'default'​​或者​​'always'​​，它们每个模块只出现一次，以避免过多的警告消息。这种行为可以使用Python的覆盖​​-Wd​​或​​-Wa​​选项（见​​警告控制​​）和离开 的警告来​​None​​。

版本3.2中已更改：添加了​​warnings​​参数。

在版本3.2中更改：默认流设置为​​sys.stderr​​实例化时间而不是导入时间。

版本3.5中已更改：添加了tb_locals参数。

• ​​_makeResult​​（）

此方法返回​​TestResult​​used 的实例​​run()​​。它不是直接调用的，但可以在子类中重写以提供自定义​​TestResult​​。

​​_makeResult()​​实例化​​TextTestRunner​​构造函数中传递的类或可调 ​​resultclass​​参数作为参数。​​TextTestResult​​如果没有​​resultclass​​提供，则默认为。结果类使用以下参数进行实例化：

stream, descriptions, verbosity

• ​​run​​（测试）

这个方法是主要的公共接口​​TextTestRunner​​。这个方法需要一个​​TestSuite​​或一个​​TestCase​​实例。​​TestResult​​通过调用创建 A ​​_makeResult()​​，运行测试并将结果打印到stdout。

• ​​unittest.​​​​main​​（模块= '__ main__' ，defaultTest =无，argv的=无，TestRunner的=无，testLoader = unittest.defaultTestLoader，出口=真，冗长= 1，FAILFAST =无，catchbreak =无，缓冲=无，警告=无）

一个命令行程序，它从模块加载一组测试并运行它们; 这主要是为了使测试模块可以方便地执行。此函数最简单的用法是在测试脚本的末尾包含以下行：

if __name__ == '__main__':
    unittest.main()

您可以通过传递详细信息参数来运行具有更详细信息的测试：

if __name__ == '__main__':
    unittest.main(verbosity=2)

所述defaultTest参数是一个单一的测试中的名称或测试名称可迭代如果经由未指定试验名称来运行的argv。如果未指定或​​None​​且未通过argv提供测试名称，则运行模块中的所有测试。

该argv的参数可以是传递给程序的选项列表，第一个元素是程序名称。如果未指定​​None​​，​​sys.argv​​则使用值。

所述的TestRunner参数可以是一个测试运行类或它的一个已创建的实例。默认情况下，使用退出代码​​main​​调用​​sys.exit()​​，指示运行测试成功或失败。

该testLoader参数必须是一个​​TestLoader​​实例，并默认为​​defaultTestLoader​​。

​​main​​支持通过传入参数从交互式解释器中使用​​exit=False​​。这将在标准输出上显示结果而不调用​​sys.exit()​​：

>>>

>>> from unittest import main
>>> main(module='test_module', exit=False)

的故障快速转移，catchbreak和缓冲参数具有与相同名称的相同的效果​​的命令行选项​​。

该警告参数指定的​​警告过滤器​​ 应该在运行测试中使用。如果没有指定，它仍将​​None​​如果一个​​-W​​选项传递给蟒蛇 （见​​警告控制​​），否则将被设置为​​'default'​​。

调用​​main​​实际上返回​​TestProgram​​类的实例。这会将测试结果存储为​​result​​属性。

在3.1版本中更改：将退出添加参数。

在版本3.2改变：该冗长，FAILFAST，catchbreak，缓冲液 和警告加入参数。

在3.4版本中更改：将defaultTest参数改为同时接受测试名称的迭代。

load_tests协议

版本3.2中的新功能。

模块或包可以通过实现调用的函数来定制在正常测试运行或测试发现期间如何从中加载测试​​load_tests​​。

如果测试模块定义​​load_tests​​它将 ​​TestLoader.loadTestsFromModule()​​使用以下参数调用：

load_tests(loader, standard_tests, pattern)

其中，模式直接通过从传递​​loadTestsFromModule​​。它默认为​​None​​。

它应该返回一个​​TestSuite​​。

loader是进行加载的实例​​TestLoader​​。 standard_tests是默认从模块加载的测试。测试模块通常只想在标准测试集中添加或删除测试。在将包作为测试发现的一部分加载时使用第三个参数。

​​load_tests​​从一组特定​​TestCase​​类加载测试的典型函数 可能如下所示：

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

如果在包含程序包的目录中启动发现，无论是从命令行还是通过调用​​TestLoader.discover()​​，​​__init__.py​​都将检查包 ​​load_tests​​。如果该函数不存在，则发现将递归到包中，就像它只是另一个目录一样。否则，将​​load_tests​​使用以下参数调用发现包的测试：

load_tests(loader, standard_tests, pattern)

这应该返回一个​​TestSuite​​代表包中的所有测试。（​​standard_tests​​仅包含从中收集的测试​​__init__.py​​。）

因为模式传递到​​load_tests​​包中可以自由地继续（并可能修改）测试发现。​​load_tests​​测试包的“不执行任何操作”功能如下所示：

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

在3.5版本中改变：发现不再检查包名匹配模式，由于匹配的默认模式包名是不可能的。

类和模块夹具

类和模块级夹具在中实现​​TestSuite​​。当测试套件遇到来自新类的测试时，​​tearDownClass()​​ 则调用前一个类（如果有的话），然后调用 ​​setUpClass()​​新类。

同样，如果测试来自与先前测试不同的模块， ​​tearDownModule​​则运行上一个模块，然后运行 ​​setUpModule​​新模块。

在所有测试都运行完毕​​tearDownClass​​并 ​​tearDownModule​​运行之后。

请注意，共享夹具与[潜在]功能（如测试并行化）不能很好地兼容，并且会破坏测试隔离。应小心使用它们。

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

共享装置不适用于具有非标准订购的套件。一个​​BaseTestSuite​​仍然存在不希望支持共享夹具框架。

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

setUpClass和tearDownClass 

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

import unittest

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

    @classmethod
    def tearDownClass(cls):
        cls._connection.destroy()

如果您希望​​setUpClass​​和​​tearDownClass​​呼吁然后在基类必须调用由他们自己。实现 ​​TestCase​​是空的。

如果在a期间引发异常，​​setUpClass​​那么类中的测试不会运行且​​tearDownClass​​不会运行。跳过的课程不会有​​setUpClass​​或没有​​tearDownClass​​。如果异常是一个 ​​SkipTest​​异常，那么该类将被报告为已跳过而不是错误。

setUpModule和tearDownModule 

这些应该作为功能实现：

def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()

如果在a中引发异常则​​setUpModule​​模块中的任何测试都不会运行且​​tearDownModule​​不会运行。如果异常是​​SkipTest​​异常，则模块将被报告为已跳过而不是错误。

信号处理

版本3.2中的新功能。

​​-c/--catch​​unittest 的命令行选项以及​​catchbreak​​参数to ​​unittest.main()​​在测试运行期间提供了对控制-C的更友好的处理。启用catch中断行为后，control-C将允许当前正在运行的测试完成，然后测试运行将结束并报告所有结果。第二个控制-c将以​​KeyboardInterrupt​​通常的方式提升a 。

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

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

• ​​unittest.​​​​installHandler​​（）

安装control-c处理程序。当​​signal.SIGINT​​收到a时（通常是响应用户按下control-c），所有注册的结果都​​stop()​​被调用。

• ​​unittest.​​​​registerResult​​（结果）

注册一个​​TestResult​​对象以进行control-c处理。注册结果会存储对它的弱引用，因此不会阻止结果被垃圾回收。

​​TestResult​​如果未启用control-c处理，则注册对象没有副作用，因此测试框架可以无条件地注册它们创建的所有结果，而与是否启用处理无关。

• ​​unittest.​​​​removeResult​​（结果）

删除注册结果。删除结果后， ​​stop()​​将不再响应control-c调用该结果对象。

• ​​unittest.​​​​removeHandler​​（function = None ）

如果不带参数调用此函数，则删除control-c处理程序（如果已安装）。此函数还可以用作测试装饰器，以便在执行测试时临时删除处理程序：

@unittest.removeHandler
def test_signal_handling(self):
    ...

​​目录​​

• ​​unittest - 单元测试框架​​
• ​​基本的例子​​
• ​​命令行界面​​
• ​​命令行选项​​
• ​​测试发现​​
• ​​组织测试代码​​
• ​​重用旧的测试代码​​
• ​​跳过测试和预期的失败​​
• ​​使用子测试区分测试迭代​​
• ​​类和函数​​
• ​​测试用例​​
• ​​不推荐使用的别名​​
• ​​分组测试​​
• ​​加载和运行测试​​
• ​​load_tests协议​​
• ​​类和模块夹具​​
• ​​setUpClass和tearDownClass​​
• ​​setUpModule和tearDownModule​​
• ​​信号处理​​

上一主题

​​doctest - 测试交互式Python示例​​

下一个主题

​​unittest.mock - 模拟对象库​​

这一页

• ​​报告错误​​
• ​​显示来源​​

«

• ​​指数​​
• ​​模块​​ |
• ​​下一个​​ |
• ​​上一个​​ |

• 

• ​​Python​​ »
• 英语 法国 日本 朝鲜的 开发（3.8） 3.7.3rc1 3.6 3.5 2.7 ​​文档​​ » 
• ​​Python标准库​​ »
• ​​开发工具​​ »

• 
  

• |

© ​​版权所有​​ 2001-2019，Python Software Foundation。 
Python软件基金会是一家非营利性公司。 ​​请捐款。​​ 
最后更新于2013年3月23日。 ​​发现了一个错误​​？ 
使用​​Sphinx​​ 1.8.4 创建