test ——python回归测试包

注解

这个 test 包仅供Python内部使用。它是为了让Python的核心开发人员受益而编写的。不鼓励在Python标准库之外使用此包，因为这里提到的代码可以在Python版本之间更改或删除，而无需注意。

这个 test 包中包含所有针对python的回归测试以及模块 test.support 和 test.regrtest . test.support 用于增强测试， test.regrtest 驱动测试套件。

中的每个模块 test 名称以开头的包 test_ 是特定模块或功能的测试套件。所有新测试都应使用 unittest 或 doctest 模块。一些较旧的测试是使用“传统”测试样式编写的，它将打印的输出与 sys.stdout ；此类型的测试被视为已弃用。

参见

模块 unittest

编写PyUnit回归测试。

模块 doctest

嵌入在文档字符串中的测试。

为编写单元测试 test 包裹

最好使用 unittest 模块遵循一些指导原则。一种方法是通过启动测试模块来命名测试模块 test_ 并以测试模块的名称结束。测试模块中的测试方法应该从 test_ 最后对测试方法进行描述。需要这样做，以便测试驱动程序将这些方法识别为测试方法。此外，不应包括该方法的文档字符串。注释（例如 # Tests function returns only True or False ）应用于提供试验方法的文件。这样做是因为文档字符串在存在时会被打印出来，因此没有说明正在运行的测试。

通常使用基本样板：

import unittest
from test import support

class MyTestCase1(unittest.TestCase):

    # Only use setUp() and tearDown() if necessary

    def setUp(self):
        ... code to execute in preparation for tests ...

    def tearDown(self):
        ... code to execute to clean up after tests ...

    def test_feature_one(self):
        # Test feature one.
        ... testing code ...

    def test_feature_two(self):
        # Test feature two.
        ... testing code ...

    ... more test methods ...

class MyTestCase2(unittest.TestCase):
    ... same structure as MyTestCase1 ...

... more test classes ...

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

此代码模式允许运行测试套件 test.regrtest ，作为支持 unittest 或通过 python -m unittest CLI。

回归测试的目标是尝试破坏代码。这导致了一些需要遵循的准则：

  • 测试套件应该运行所有类、函数和常量。这不仅包括将要呈现给外部世界的外部API，还包括“私有”代码。

  • 首选白盒测试（在编写测试时检查正在测试的代码）。blackbox测试（仅测试发布的用户界面）不够完整，无法确保测试所有边界和边缘情况。

  • 确保测试所有可能的值，包括无效值。这样不仅可以接受所有有效值，而且可以正确处理不正确的值。

  • 排出尽可能多的代码路径。测试发生分支的地方，从而调整输入以确保通过代码采用尽可能多的不同路径。

  • 为测试代码发现的任何错误添加显式测试。这将确保在将来更改代码时不会再次出现错误。

  • 确保在测试后进行清理（例如关闭并删除所有临时文件）。

  • 如果测试依赖于操作系统的特定条件，请在尝试测试之前验证该条件是否已存在。

  • 导入尽可能少的模块，并尽快导入。这样可以最小化测试的外部依赖性，也可以最小化导入模块的副作用可能导致的异常行为。

  • 尝试最大化代码重用。有时，测试会因使用哪种类型的输入而有所不同。通过使用指定输入的类对基本测试类进行子类化，最小化代码重复：

    class TestFuncAcceptsSequencesMixin:

    func = mySuperWhammyFunction

    def test_func(self):
        self.func(self.arg)

class AcceptLists(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = [1, 2, 3]

class AcceptStrings(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = 'abc'

class AcceptTuples(TestFuncAcceptsSequencesMixin, unittest.TestCase):
    arg = (1, 2, 3)

    使用此模式时，请记住继承自 unittest.TestCase 作为测试运行。这个 Mixin 上面示例中的类没有任何数据，因此不能单独运行，因此它不继承自 unittest.TestCase .

参见

测试驱动开发

KentBeck写的一本关于代码前测试的书。

使用命令行界面运行测试

这个 test 包可以作为脚本运行以驱动python的回归测试套件，这要归功于 -m 选项： python -m test . 在引擎盖下面，它使用 test.regrtest ；调用 python -m test.regrtest 在以前的python版本中使用仍然有效。单独运行脚本会自动开始运行 test 包裹。它通过查找包中名称以开头的所有模块来实现这一点。 test_ ，导入它们并执行函数 test_main() 如果存在或通过unittest.testloader.loadtestsfrommodule加载测试，如果 test_main 不存在。要执行的测试的名称也可以传递给脚本。指定单个回归测试 (python -m test test_spam ）将最小化输出并仅打印测试是否通过。

运行 test 直接允许设置可供测试使用的资源。你可以通过使用 -u 命令行选项。指定 all 作为 -u 选项启用所有可能的资源： python -m test -uall . 如果只需要一个资源（更常见的情况是），可以在后面列出一个逗号分隔的不需要的资源列表 all . 命令 python -m test -uall,-audio,-largefile 将运行 test 使用除 audio 和 largefile 资源。有关所有资源和更多命令行选项的列表，请运行 python -m test -h .

执行回归测试的其他一些方法取决于测试在哪个平台上执行。在Unix上，您可以运行 make test 在构建python的顶级目录中。在Windows上，执行 rt.bat 从你 PCbuild 目录将运行所有回归测试。

test.support ---Python测试套件的实用程序

这个 test.support 模块为python的回归测试套件提供支持。

注解

test.support 不是公共模块。这里的文档帮助Python开发人员编写测试。此模块的API可能会发生更改，而不考虑版本之间的向后兼容性问题。

此模块定义以下异常：

exception test.support.TestFailed

测试失败时引发的异常。这已被否决，取而代之的是 unittest -基于测试和 unittest.TestCase 的断言方法。

exception test.support.ResourceDenied

的子类 unittest.SkipTest . 当资源（如网络连接）不可用时引发。提出的 requires() 功能。

这个 test.support 模块定义以下常量：

test.support.verbose

True 当启用详细输出时。当需要有关运行测试的更详细信息时，应进行检查。 verbose 是由 test.regrtest .

test.support.is_jython

True 如果正在运行的解释器是Jython。

test.support.is_android

True 如果系统是安卓系统。

test.support.unix_shell

shell的路径（如果不在Windows上）；否则 None .

test.support.LOOPBACK_TIMEOUT

使用网络服务器侦听网络本地环回接口（如 127.0.0.1 .

超时时间足以防止测试失败：它考虑到客户机和服务器可以在不同的线程甚至不同的进程中运行。

超时时间应该足够长 connect() ， recv() 和 send() 方法 socket.socket .

默认值为5秒。

也见 INTERNET_TIMEOUT .

test.support.INTERNET_TIMEOUT

发送到Internet的网络请求超时（秒）。

超时时间足够短，以防止由于任何原因阻止Internet请求时测试等待太长时间。

通常，使用 INTERNET_TIMEOUT 不应将测试标记为失败，而应跳过该测试：请参阅 transient_internet() .

默认值为1分钟。

也见 LOOPBACK_TIMEOUT .

test.support.SHORT_TIMEOUT

如果测试花费“太长时间”，则将测试标记为失败的超时（秒）。

超时值取决于重新测试 --timeout 命令行选项。

如果测试使用 SHORT_TIMEOUT 在慢速构建机器人上随机失败，使用 LONG_TIMEOUT 相反。

它的默认值是30秒。

test.support.LONG_TIMEOUT

检测测试挂起的超时时间（秒）。

它足够长，可以降低最慢的Python构建机器人的测试失败风险。如果测试花费“太长时间”，则不应使用它将测试标记为失败。超时值取决于重新测试 --timeout 命令行选项。

默认值为5分钟。

也见 LOOPBACK_TIMEOUT ， INTERNET_TIMEOUT 和 SHORT_TIMEOUT .

test.support.PGO

设置当测试对PGO无效时可以跳过的时间。

test.support.PIPE_MAX_SIZE

一个可能大于底层OS管道缓冲区大小的常量，用于进行写操作阻塞。

test.support.SOCK_MAX_SIZE

一个可能大于底层OS套接字缓冲区大小的常量，用于进行写操作阻塞。

test.support.TEST_SUPPORT_DIR

设置为包含 test.support .

test.support.TEST_HOME_DIR

设置为测试包的顶级目录。

test.support.TEST_DATA_DIR

设置为 data 测试包中的目录。

test.support.MAX_Py_ssize_t

设置为 sys.maxsize 用于大内存测试。

test.support.max_memuse

通过设置 set_memlimit() 作为大内存测试的内存限制。受限制 MAX_Py_ssize_t .

test.support.real_max_memuse

通过设置 set_memlimit() 作为大内存测试的内存限制。不受限制 MAX_Py_ssize_t .

test.support.MISSING_C_DOCSTRINGS

返回 True 如果在cpython上运行，而不是在Windows上运行，并且配置未设置为 WITH_DOC_STRINGS .

test.support.HAVE_DOCSTRINGS

检查是否存在文档字符串。

test.support.TEST_HTTP_URL

为网络测试定义专用HTTP服务器的URL。

test.support.ALWAYS_EQ

等于任何东西的物体。用于测试混合类型比较。

test.support.NEVER_EQ

不等于任何东西（甚至等于 ALWAYS_EQ ). 用于测试混合类型比较。

test.support.LARGEST

比任何东西都大的物体（除了它本身）。用于测试混合类型比较。

test.support.SMALLEST

比任何东西都少的对象（除了它本身）。用于测试混合类型比较。

这个 test.support 模块定义以下功能：

test.support.is_resource_enabled(resource)

返回 True 如果 资源 已启用并可用。只有在以下情况下才设置可用资源列表： test.regrtest 正在执行测试。

test.support.python_is_optimized()

返回 True 如果python不是用 -O0 或 -Og .

test.support.with_pymalloc()

返回 _testcapi.WITH_PYMALLOC .

test.support.requires(resource, msg=None)

提高 ResourceDenied 如果 资源 不可用。 msg 是的参数 ResourceDenied 如果它被提起。总是回报 True 如果由函数调用， __name__ 是 '__main__' . 在执行测试时使用 test.regrtest .

test.support.system_must_validate_cert(f)

提高 unittest.SkipTest 在TLS认证验证失败时。

test.support.sortdict(dict)

返回 dict 按键排序。

test.support.findfile(filename, subdir=None)

返回名为的文件的路径 filename . 如果找不到匹配项 filename 返回。这不等于失败，因为它可能是文件的路径。

设置 子迪尔 指示用于查找文件而不是直接在路径目录中查找的相对路径。

test.support.match_test(test)

比赛 test 到模式集 set_match_tests() .

test.support.set_match_tests(patterns)

用正则表达式定义匹配测试 模式 .

test.support.run_unittest(*classes)

执行 unittest.TestCase 传递给函数的子类。函数扫描类中以前缀开头的方法 test_ 并单独执行测试。

将字符串作为参数传递也是合法的；这些字符串应该是 sys.modules . 每个相关模块将由 unittest.TestLoader.loadTestsFromModule() . 这通常出现在下面 test_main() 功能：

def test_main():
    support.run_unittest(__name__)

这将运行命名模块中定义的所有测试。

test.support.run_doctest(module, verbosity=None, optionflags=0)

运行 doctest.testmod() 关于给定 模块 . 返回 (failure_count, test_count) .

如果 冗长 是 None ， doctest.testmod() 运行时的详细程度设置为 verbose . 否则，它将在详细程度设置为的情况下运行 None . 选择标志 传递为 optionflags 到 doctest.testmod() .

test.support.setswitchinterval(interval)

设置 sys.setswitchinterval() 到给定的 间隔 . 为Android系统定义一个最小间隔，以防止系统挂起。

test.support.check_impl_detail(**guards)

使用此检查来保护cpython的特定于实现的测试，或者仅在由参数保护的实现上运行它们：

check_impl_detail()               # Only on CPython (default).
check_impl_detail(jython=True)    # Only on Jython.
check_impl_detail(cpython=False)  # Everywhere except CPython.
test.support.set_memlimit(limit)

设置的值 max_memuse 和 real_max_memuse 用于大内存测试。

test.support.record_original_stdout(stdout)

将值存储在 stdout . 它是为了在重新注册时保持stdout。

test.support.get_original_stdout()

返回由设置的原始stdout record_original_stdout() 或 sys.stdout 如果没有设置。

test.support.args_from_interpreter_flags()

返回命令行参数列表，这些参数在 sys.flags 和 sys.warnoptions .

test.support.optim_args_from_interpreter_flags()

返回命令行参数列表，这些参数在 sys.flags .

test.support.captured_stdin()
test.support.captured_stdout()
test.support.captured_stderr()

上下文管理器，它临时用 io.StringIO 对象。

用于输出流的示例：

with captured_stdout() as stdout, captured_stderr() as stderr:
    print("hello")
    print("error", file=sys.stderr)
assert stdout.getvalue() == "hello\n"
assert stderr.getvalue() == "error\n"

与输入流一起使用的示例：

with captured_stdin() as stdin:
    stdin.write('hello\n')
    stdin.seek(0)
    # call test code that consumes from sys.stdin
    captured = input()
self.assertEqual(captured, "hello")
test.support.disable_faulthandler()

替换上下文管理器 sys.stderr 具有 sys.__stderr__ .

test.support.gc_collect()

强制收集尽可能多的对象。这是必需的，因为垃圾收集器不能保证及时释放。这意味着 __del__ 方法的调用可能比预期晚，weakrefs的生存期可能比预期长。

test.support.disable_gc()

一种上下文管理器，在进入时禁用垃圾收集器，在退出时重新启用它。

test.support.swap_attr(obj, attr, new_val)

上下文管理器，用新对象替换属性。

用法：

with swap_attr(obj, "attr", 5):
    ...

这将设置 obj.attr 在 with 块，恢复块末尾的旧值。如果 attr 不存在于 obj ，它将在块的末尾创建并删除。

旧值（或 None 如果它不存在）将分配给“as”子句的目标（如果有）。

test.support.swap_item(obj, attr, new_val)

上下文管理器，用新对象替换项。

用法：

with swap_item(obj, "item", 5):
    ...

这将设置 obj["item"] 在 with 块，恢复块末尾的旧值。如果 item 不存在于 obj ，它将在块的末尾创建并删除。

旧值（或 None 如果它不存在）将分配给“as”子句的目标（如果有）。

test.support.print_warning(msg)

将警告打印到 sys.__stderr__ . 将邮件格式化为： f"Warning -- {{msg}}" .如果 msg 由多行组成，添加 "Warning -- " 每行的前缀。

3.9 新版功能.

test.support.wait_process(pid, *, exitcode, timeout=None)

等待处理 pid 完成并检查进程退出代码是否为 退出代码 .

养一个 AssertionError 如果进程退出代码不等于 退出代码 .

如果进程运行时间超过 超时 秒 (SHORT_TIMEOUT 默认情况下），终止进程并引发 AssertionError . 超时功能在Windows上不可用。

3.9 新版功能.

test.support.calcobjsize(fmt)

返回 struct.calcsize() 对于 nP{{fmt}}0n 或者，如果 gettotalrefcount 存在， 2PnP{{fmt}}0P .

test.support.calcvobjsize(fmt)

返回 struct.calcsize() 对于 nPn{{fmt}}0n 或者，如果 gettotalrefcount 存在， 2PnPn{{fmt}}0P .

test.support.checksizeof(test, o, size)

对于测试用例 test ，断言 sys.getsizeof 对于 o 加上gc头大小等于 size .

@test.support.anticipate_failure(condition)

有条件地标记测试的修饰器 unittest.expectedFailure() . 任何使用这个装饰器的地方都应该有一个相关的注释来标识相关的跟踪器问题。

@test.support.run_with_locale(catstr, *locales)

用于在其他区域设置中运行函数的装饰器，完成后将其正确重置。 卡特斯特尔 区域设置类别是否为字符串（例如 "LC_ALL" ）这个 场所 将按顺序尝试传递，并将使用第一个有效的区域设置。

@test.support.run_with_tz(tz)

用于在特定时区中运行函数，并在完成后正确重置函数的修饰符。

@test.support.requires_freebsd_version(*min_version)

在FreeBSD上运行测试时的最低版本的修饰器。如果freebsd版本小于最小值，则引发 unittest.SkipTest .

@test.support.requires_linux_version(*min_version)

在Linux上运行测试时的最低版本装饰器。如果Linux版本低于最低版本，则提高 unittest.SkipTest .

@test.support.requires_mac_version(*min_version)

在Mac OS X上运行测试时用于最低版本的修饰程序。如果Mac OS X版本低于最低版本，请提高 unittest.SkipTest .

@test.support.requires_IEEE_754

用于跳过非IEEE 754平台上的测试的装饰器。

@test.support.requires_zlib

用于跳过测试的修饰符，如果 zlib 不存在。

@test.support.requires_gzip

用于跳过测试的修饰符，如果 gzip 不存在。

@test.support.requires_bz2

用于跳过测试的修饰符，如果 bz2 不存在。

@test.support.requires_lzma

用于跳过测试的修饰符，如果 lzma 不存在。

@test.support.requires_resource(resource)

用于跳过测试的修饰符，如果 资源 不可用。

@test.support.requires_docstrings

仅运行测试的decorator if HAVE_DOCSTRINGS .

@test.support.cpython_only(test)

测试装饰器仅适用于CPython。

@test.support.impl_detail(msg=None, **guards)

用于调用的装饰器 check_impl_detail() 在 警卫 . 如果回报 False 然后使用 msg 作为跳过测试的原因。

@test.support.no_tracing(func)

decorator临时关闭测试期间的跟踪。

@test.support.refcount_test(test)

涉及引用计数的测试的修饰器。如果不是由cpython运行，则decorator不会运行测试。在测试期间，将取消设置任何跟踪函数，以防止跟踪函数导致意外的引用计数。

@test.support.bigmemtest(size, memuse, dry_run=True)

Bigmem测试的装饰器。

size 是测试的请求大小（以任意测试解释单位表示）。 内存使用 是测试的每个单元的字节数，或者是对它的一个很好的估计。例如，一个测试需要两个字节的缓冲区，每个缓冲区4 gib，可以用 @bigmemtest(size=_4G, memuse=2) .

这个 size 参数通常作为额外参数传递给修饰测试方法。如果 dry_run 是 True ，传递给测试方法的值可能小于请求的值。如果 dry_run 是 False ，这意味着当 -M 未指定。

@test.support.bigaddrspacetest(f)

用于填充地址空间的测试的修饰器。 f 是要封装的函数。

test.support.check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None)

测试中的语法错误 陈述 通过尝试编译 陈述 . 测试用例 是 unittest 测试的实例。 错误的文本 是应与引发的 SyntaxError . 如果 林诺 不是 None ，与异常行进行比较。如果 抵消 不是 None ，与异常的偏移量进行比较。

test.support.open_urlresource(url, *args, **kw)

正常开放 url . 如果打开失败，则升高 TestFailed .

test.support.reap_children()

在结束时使用这个 test_main 无论何时启动子流程。这将有助于确保没有多余的子项（僵尸）停留在猪资源和创造问题时，寻找反射。

test.support.get_attribute(obj, name)

获取属性，引发 unittest.SkipTest 如果 AttributeError 提高了。

test.support.catch_unraisable_exception()

上下文管理器使用 sys.unraisablehook() .

存储异常值 (cm.unraisable.exc_value ）创建引用循环。当上下文管理器退出时，引用循环将显式中断。

存储对象 (cm.unraisable.object ）如果设置为正在完成的对象，则可以将其恢复。退出上下文管理器将清除存储的对象。

用法：

with support.catch_unraisable_exception() as cm:
    # code creating an "unraisable exception"
    ...

    # check the unraisable exception: use cm.unraisable
    ...

# cm.unraisable attribute no longer exists at this point
# (to break a reference cycle)

3.8 新版功能.

test.support.load_package_tests(pkg_dir, loader, standard_tests, pattern)

通用实现 unittest load_tests 测试包中使用的协议。 pkg_dir 是包的根目录； 加载器 ， standard_tests 和 模式 参数是否应为 load_tests . 在简单的情况下，测试包 __init__.py 可以是以下内容：

import os
from test.support import load_package_tests

def load_tests(*args):
    return load_package_tests(os.path.dirname(__file__), *args)
test.support.detect_api_mismatch(ref_api, other_api, *, ignore=())

返回的一组属性、函数或方法 ref_api 找不到 other_api ，除了在中指定的要在此检查中忽略的已定义项列表 忽视 .

默认情况下，这将跳过以“uuu”开头的私有属性，但包括所有魔法方法，即以“uuu”开头和结尾的方法。

3.5 新版功能.

test.support.patch(test_instance, object_to_patch, attr_name, new_value)

重写 object_to_patch.attr_name 具有 new_value . 同时将清理过程添加到 test_instance 恢复 object_to_patch 对于 attr_name . 这个 attr_name 应该是的有效属性 object_to_patch .

test.support.run_in_subinterp(code)

运行 code 在子解释器中。提高 unittest.SkipTest 如果 tracemalloc 启用。

test.support.check_free_after_iterating(test, iter, cls, args=())

断言 iter 在迭代后释放。

test.support.missing_compiler_executable(cmd_names=[])

检查是否存在名称列在中的编译器可执行文件 cmd_names 或所有编译器可执行文件 cmd_names 为空并返回第一个缺少的可执行文件或 None 当没有发现丢失。

test.support.check__all__(test_case, module, name_of_module=None, extra=(), not_exported=())

断言 __all__ 变量 模块 包含所有公用名。

模块的公共名称（其API）根据是否与公共名称约定匹配自动检测，并在中定义。 模块 .

这个 name_of_module 参数可以指定（作为字符串或元组）可以定义API的哪些模块，以便将其检测为公共API。其中一个例子是 模块 从其他模块导入部分公共API，可能是C后端（如 csv 及其 _csv ）

这个 额外的 参数可以是一组名称，否则不会自动检测为“public”，就像没有适当 __module__ 属性。如果提供，它将添加到自动检测的。

这个 not_exported 参数可以是一组名称，这些名称不能被视为公共API的一部分，即使它们的名称另有指示。

示例用途：

import bar
import foo
import unittest
from test import support

class MiscTestCase(unittest.TestCase):
    def test__all__(self):
        support.check__all__(self, foo)

class OtherTestCase(unittest.TestCase):
    def test__all__(self):
        extra = {'BAR_CONST', 'FOO_CONST'}
        not_exported = {'baz'}  # Undocumented name.
        # bar imports part of its API from _bar.
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, not_exported=not_exported)

3.6 新版功能.

test.support.skip_if_broken_multiprocessing_synchronize()

如果 multiprocessing.synchronize 如果没有可用的信号量实现，或者如果创建锁引发 OSError .

3.10 新版功能.

这个 test.support 模块定义以下类：

class test.support.SuppressCrashReport

一个上下文管理器，用于防止在预期会导致子进程崩溃的测试上弹出崩溃对话框。

在Windows上，它禁用Windows错误报告对话框，使用 SetErrorMode .

在UNIX上， resource.setrlimit() 用于设置 resource.RLIMIT_CORE 的软限制为0，以防止创建coredump文件。

在两个平台上，旧值通过 __exit__() .

class test.support.SaveSignals

类来保存和还原由Python信号处理程序注册的信号处理程序。

class test.support.Matcher
matches(self, d, **kwargs)

尝试将单个dict与提供的参数匹配。

match_value(self, k, dv, v)

尝试匹配单个存储值（ dv ）具有提供的值（ v ）

class test.support.BasicTestRunner
run(test)

运行 test 并返回结果。

test.support.socket_helper ---套接字测试实用程序

这个 test.support.socket_helper 模块为套接字测试提供支持。

3.9 新版功能.

test.support.socket_helper.IPV6_ENABLED

设置为 True 如果此主机上启用了IPv6， False 否则。

test.support.socket_helper.find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)

返回一个应该适合绑定的未使用端口。这是通过创建与 sock 参数（默认为 AF_INET ， SOCK_STREAM ，并将其绑定到指定的主机地址（默认为 0.0.0.0 ）当端口设置为0时，从操作系统中引出一个未使用的临时端口。然后关闭并删除临时套接字，并返回临时端口。

这种方法或 bind_port() 应该用于在测试期间需要将服务器套接字绑定到特定端口的任何测试。使用哪个端口取决于调用代码是创建一个python套接字，还是需要在构造函数中提供一个未使用的端口或将其传递给外部程序（即 -accept openssl的服务器模式的参数）。总是类似于 bind_port() 结束 find_unused_port() 如果可能的话。不鼓励使用硬编码端口，因为它会使测试的多个实例无法同时运行，这对buildbots来说是一个问题。

test.support.socket_helper.bind_port(sock, host=HOST)

将套接字绑定到可用端口并返回端口号。依赖临时端口以确保使用未绑定端口。这一点很重要，因为许多测试可能同时运行，特别是在BuildBot环境中。如果 sock.family 是 AF_INET 和 sock.type 是 SOCK_STREAM 和Socket SO_REUSEADDR 或 SO_REUSEPORT 开始吧。测试不应为TCP/IP套接字设置这些套接字选项。设置这些选项的唯一情况是通过多个UDP套接字测试多播。

此外，如果 SO_EXCLUSIVEADDRUSE 套接字选项可用（即在Windows上），它将设置在套接字上。这将阻止任何其他人在测试期间绑定到我们的主机/端口。

test.support.socket_helper.bind_unix_socket(sock, addr)

绑定Unix套接字，引发 unittest.SkipTest 如果 PermissionError 提高了。

@test.support.socket_helper.skip_unless_bind_unix_socket

用于运行需要 bind() 用于Unix套接字。

test.support.socket_helper.transient_internet(resource_name, *, timeout=30.0, errnos=())

提升的上下文管理器 ResourceDenied 当互联网连接的各种问题表现为异常时。

test.support.script_helper ---用于python执行测试的实用程序

这个 test.support.script_helper 模块为Python的脚本执行测试提供支持。

test.support.script_helper.interpreter_requires_environment()

返回 True 如果 sys.executable interpreter 需要环境变量才能运行。

设计用于 @unittest.skipIf() 注释需要使用 assert_python*() 启动隔离模式的功能 (-I ）或无环境模式 (-E ）副翻译程序。

正常的构建和测试不会遇到这种情况，但是当试图从一个解释器中运行标准库测试套件时，可能会发生这种情况，该解释器对Python当前的查找主逻辑没有明显的基础。

设置 PYTHONHOME 是让大部分测试套件在这种情况下运行的一种方法。 PYTHONPATH 或 PYTHONUSERSITE 是其他可能影响解释器是否可以启动的常见环境变量。

test.support.script_helper.run_python_until_end(*args, **env_vars)

环境设置基于 env_vars 用于在子进程中运行解释器。这些值可以包括 __isolated ， __cleanenv ， __cwd 和 TERM .

在 3.9 版更改: 函数不再从 标准错误 .

test.support.script_helper.assert_python_ok(*args, **env_vars)

断言使用 args 和可选的环境变量 env_vars 成功 (rc == 0 返回A (return code, stdout, stderr) 元组。

如果 __cleanenv 关键字被设置， env_vars 是一个新鲜的环境。

python以隔离模式启动（命令行选项 -I ，除非 __isolated 关键字设置为 False .

在 3.9 版更改: 函数不再从 标准错误 .

test.support.script_helper.assert_python_failure(*args, **env_vars)

断言使用 args 和可选的环境变量 env_vars 失败 (rc != 0 返回A (return code, stdout, stderr) 元组。

见 assert_python_ok() 更多选项。

在 3.9 版更改: 函数不再从 标准错误 .

test.support.script_helper.spawn_python(*args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, **kw)

使用给定的参数运行python子进程。

kw 是要传递到的额外关键字参数 subprocess.Popen() . 返回A subprocess.Popen 对象。

test.support.script_helper.kill_python(p)

运行给定 subprocess.Popen 处理到完成并返回stdout。

test.support.script_helper.make_script(script_dir, script_basename, source, omit_suffix=False)

创建包含 source 在路径中 script_dir 和 script_basename .如果 omit_suffix 是 False 追加 .py 为了这个名字。返回完整的脚本路径。

test.support.script_helper.make_zip_script(zip_dir, zip_basename, script_name, name_in_zip=None)

在以下位置创建zip文件 zip_dir 和 zip_basename 带扩展名 zip 其中包含 script_name . name_in_zip 是存档名称。返回包含 (full path, full path of archive name) .

test.support.script_helper.make_pkg(pkg_dir, init_source='')

创建名为的目录 pkg_dir 包含一个 __init__ 用文件 init_source 作为其内容。

test.support.script_helper.make_zip_pkg(zip_dir, zip_basename, pkg_name, script_basename, source, depth=1, compiled=False)

创建路径为的zip包目录 zip_dir 和 zip_basename 包含一个空的 __init__ 文件和文件 script_basename 包含 source . 如果 编译的 是 True 将编译两个源文件并将其添加到zip包中。返回zip文件的完整zip路径和存档名的元组。

test.support.bytecode_helper ---测试正确字节码生成的支持工具

这个 test.support.bytecode_helper 模块为测试和检查字节码生成提供支持。

3.9 新版功能.

模块定义了以下类：

class test.support.bytecode_helper.BytecodeTestCase(unittest.TestCase)

此类具有用于检查字节码的自定义断言方法。

BytecodeTestCase.get_disassembly_as_string(co)

退回拆卸 co 作为字符串。

BytecodeTestCase.assertInBytecode(x, opname, argval=_UNSPECIFIED)

如果返回仪表 op名字 被发现，否则抛出 AssertionError .

BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED)

投掷 AssertionError 如果 op名字 被发现。

test.support.threading_helper ---线程测试实用程序

这个 test.support.threading_helper 模块为线程测试提供支持。

3.10 新版功能.

test.support.threading_helper.join_thread(thread, timeout=None)

加入一个 线 在内部 timeout . 养一个 AssertionError 如果线程在 timeout 秒。

@test.support.threading_helper.reap_threads(func)

即使测试失败，也要确保线程被清除。

test.support.threading_helper.start_threads(threads, unlock=None)

要启动的上下文管理器 线程 . 它试图在退出时加入线程。

test.support.threading_helper.threading_cleanup(*original_values)

清除中未指定的线程 original_values . 用于在测试将运行线程留在后台时发出警告。

test.support.threading_helper.threading_setup()

返回当前线程数和挂起线程的副本。

test.support.threading_helper.wait_threads_exit(timeout=None)

上下文管理器等待，直到在 with 语句退出。

test.support.threading_helper.catch_threading_exception()

上下文管理器捕获 threading.Thread 异常使用 threading.excepthook() .

捕获异常时设置的属性：

  • exc_type

  • exc_value

  • exc_traceback

  • thread

见 threading.excepthook() 文档。

这些属性在上下文管理器出口处被删除。

用法：

with threading_helper.catch_threading_exception() as cm:
    # code spawning a thread which raises an exception
    ...

    # check the thread exception, use cm attributes:
    # exc_type, exc_value, exc_traceback, thread
    ...

# exc_type, exc_value, exc_traceback, thread attributes of cm no longer
# exists at this point
# (to avoid reference cycles)

3.8 新版功能.

test.support.os_helper ---操作系统测试实用程序

这个 test.support.os_helper 模块为操作系统测试提供支持。

3.10 新版功能.

test.support.os_helper.FS_NONASCII

一个非ASCII字符，可由 os.fsencode() .

test.support.os_helper.SAVEDCWD

设置为 os.getcwd() .

test.support.os_helper.TESTFN

设置为可安全用作临时文件名的名称。创建的任何临时文件都应关闭并取消链接（删除）。

test.support.os_helper.TESTFN_NONASCII

设置为包含 FS_NONASCII 性格。

test.support.os_helper.TESTFN_UNENCODABLE

设置为文件名（str类型），该文件名不应在严格模式下通过文件系统编码进行编码。它可能是 None 如果无法生成这样的文件名。

test.support.os_helper.TESTFN_UNDECODABLE

设置为文件系统编码无法在严格模式下解码的文件名（字节类型）。它可能是 None 如果无法生成这样的文件名。

test.support.os_helper.TESTFN_UNICODE

设置为临时文件的非ASCII名称。

class test.support.os_helper.EnvironmentVarGuard

用于临时设置或取消设置环境变量的类。实例可以用作上下文管理器，并具有用于查询/修改底层的完整字典接口。 os.environ .退出上下文管理器后，通过此实例对环境变量所做的所有更改都将回滚。

在 3.1 版更改: 添加字典接口。

class test.support.os_helper.FakePath(path)

简单的 path-like object . 它实现了 __fspath__() 方法，只返回 path 参数。如果 path 是一个例外，它将在 __fspath__() .

EnvironmentVarGuard.set(envvar, value)

临时设置环境变量 envvar 的价值 value .

EnvironmentVarGuard.unset(envvar)

暂时取消设置环境变量 envvar .

返回 True 如果操作系统支持符号链接， False 否则。

test.support.os_helper.can_xattr()

返回 True 如果操作系统支持xattr， False 否则。

test.support.os_helper.change_cwd(path, quiet=False)

临时将当前工作目录更改为的上下文管理器 path 并生成目录。

如果 安静的 是 False ，上下文管理器在出错时引发异常。否则，它只发出警告并保持当前工作目录不变。

test.support.os_helper.create_empty_file(filename)

创建一个空文件 filename . 如果它已经存在，则截断它。

test.support.os_helper.fd_count()

统计打开的文件描述符的数量。

test.support.os_helper.fs_is_case_insensitive(directory)

返回 True 如果文件系统 目录 不区分大小写。

test.support.os_helper.make_bad_fd()

通过打开和关闭临时文件并返回其描述符来创建无效的文件描述符。

test.support.os_helper.rmdir(filename)

调用 os.rmdir() 在 filename . 在Windows平台上，它被一个检查文件是否存在的等待循环所包围。

test.support.os_helper.rmtree(path)

调用 shutil.rmtree() 在 path 或调用 os.lstat() 和 os.rmdir() 删除路径及其内容。在Windows平台上，它被一个检查文件是否存在的等待循环所包围。

用于运行需要支持符号链接的测试的装饰器。

@test.support.os_helper.skip_unless_xattr

用于运行需要支持xattr的测试的修饰符。

test.support.os_helper.temp_cwd(name='tempcwd', quiet=False)

临时创建新目录并更改当前工作目录（CWD）的上下文管理器。

上下文管理器在当前目录中创建名为的临时目录 name 在临时更改当前工作目录之前。如果 name 是 None ，创建临时目录时使用 tempfile.mkdtemp() .

如果 安静的 是 False 并且不可能创建或更改CWD，会引发错误。否则，只会发出警告并使用原始CWD。

test.support.os_helper.temp_dir(path=None, quiet=False)

在以下位置创建临时目录的上下文管理器 path 并生成目录。

如果 path 是 None ，创建临时目录时使用 tempfile.mkdtemp() . 如果 安静的 是 False ，上下文管理器在出错时引发异常。否则，如果 path 已指定但无法创建，仅发出警告。

test.support.os_helper.temp_umask(umask)

临时设置进程umask的上下文管理器。

调用 os.unlink() 在 filename . 在Windows平台上，它被一个检查文件是否存在的等待循环所包围。

test.support.import_helper ---用于导入测试的实用程序

这个 test.support.import_helper 模块为导入测试提供支持。

3.10 新版功能.

test.support.import_helper.forget(module_name)

删除名为的模块 module_name 从 sys.modules 删除模块的所有字节编译文件。

test.support.import_helper.import_fresh_module(name, fresh=(), blocked=(), deprecated=False)

此函数通过从中删除命名模块来导入并返回命名python模块的新副本。 sys.modules 在进行导入之前。注意，与 reload() ，原始模块不受此操作影响。

新鲜的 是否可以读取其他模块名，这些模块名也将从 sys.modules 在执行导入之前缓存。

此路不通 是否可替换为的模块名称 None 在导入期间在模块缓存中，以确保尝试导入它们会引发 ImportError .

命名模块和 新鲜的 和 此路不通 在开始导入之前保存参数，然后重新插入 sys.modules 当新的导入完成时。

在此导入期间，如果 贬低 是 True .

此功能将引发 ImportError 如果无法导入命名模块。

示例用途：

# Get copies of the warnings module for testing without affecting the
# version being used by the rest of the test suite. One copy uses the
# C implementation, the other is forced to use the pure Python fallback
# implementation
py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
c_warnings = import_fresh_module('warnings', fresh=['_warnings'])

3.1 新版功能.

test.support.import_helper.import_module(name, deprecated=False, *, required_on())

此函数导入并返回命名模块。与普通导入不同，此函数将引发 unittest.SkipTest 如果无法导入模块。

在此导入期间，如果 贬低 是 True . 如果平台上需要模块，但其他模块可选，则设置 required_on 到一个可与之比较的平台前缀 sys.platform .

3.1 新版功能.

test.support.import_helper.modules_setup()

返回的副本 sys.modules .

test.support.import_helper.modules_cleanup(oldmodules)

移除模块，除了 OLED模块 和 encodings 为了保留内部缓存。

test.support.import_helper.unload(name)

删除 name 从 sys.modules .

test.support.import_helper.make_legacy_pyc(source)

移动一 PEP 3147/PEP 488 pyc文件到其旧的pyc位置，并将文件系统路径返回到旧的pyc文件。这个 source 值是源文件的文件系统路径。它不需要存在，但是PEP 3147/488 PYC文件必须存在。

class test.support.import_helper.CleanImport(*module_names)

用于强制导入以返回新模块引用的上下文管理器。这对于测试模块级行为很有用，例如在导入时发出拒绝警告。示例用法：

with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.
class test.support.import_helper.DirsOnSysPath(*paths)

用于临时将目录添加到sys.path的上下文管理器。

这是一份 sys.path ，附加作为位置参数给定的任何目录，然后还原 sys.path 到上下文结束时复制的设置。

注意 all sys.path 上下文管理器主体中的修改（包括对象的替换）将在块的末尾还原。

test.support.warnings_helper ---警告测试实用程序

这个 test.support.warnings_helper 模块提供对警告测试的支持。

3.10 新版功能.

test.support.warnings_helper.check_no_resource_warning(testcase)

上下文管理器检查是否 ResourceWarning 提高了。必须删除可能发出的对象 ResourceWarning 在上下文管理器结束之前。

test.support.warnings_helper.check_syntax_warning(testcase, statement, errtext='', *, lineno=1, offset=None)

中的语法警告测试 陈述 通过尝试编译 陈述 . 同时测试 SyntaxWarning 只发出一次，它将转换为 SyntaxError 当变成错误时。 测试用例 是 unittest 测试的实例。 错误的文本 是应与发出的字符串表示形式匹配的正则表达式。 SyntaxWarning 并提出 SyntaxError . 如果 林诺 不是 None ，与警告和异常行进行比较。如果 抵消 不是 None ，与异常的偏移量进行比较。

3.8 新版功能.

test.support.warnings_helper.check_warnings(*filters, quiet=True)

方便封装 warnings.catch_warnings() 这使得测试是否正确地发出了警告变得更加容易。大约相当于调用 warnings.catch_warnings(record=True) 具有 warnings.simplefilter() 设置为 always 以及自动验证记录结果的选项。

check_warnings 接受窗体的2元组 ("message regexp", WarningCategory) 作为位置参数。如果一个或多个 过滤器 提供，或者如果可选关键字参数 安静的 是 False ，它检查以确保警告符合预期：每个指定的筛选器必须至少匹配由所附代码引发的警告中的一个，否则测试将失败；如果引发的任何警告与任何指定的筛选器都不匹配，则测试将失败。要禁用这些检查中的第一项，请设置 安静的 到 True .

如果未指定参数，则默认为：

check_warnings(("", Warning), quiet=True)

在这种情况下，将捕获所有警告，并且不会引发任何错误。

在进入上下文管理器时， WarningRecorder 返回实例。来自的基础警告列表 catch_warnings() 通过记录器对象的 warnings 属性。为了方便起见，还可以通过记录器对象直接访问表示最新警告的对象的属性（参见下面的示例）。如果没有发出警告，则表示警告的对象上的任何属性都将返回 None .

记录器对象还具有 reset() 方法，清除警告列表。

上下文管理器的设计用途如下：

with check_warnings(("assertion is always true", SyntaxWarning),
                    ("", UserWarning)):
    exec('assert(False, "Hey!")')
    warnings.warn(UserWarning("Hide me!"))

在这种情况下，如果没有发出警告或发出了其他警告， check_warnings() 会引发错误。

当测试需要更深入地查看警告，而不仅仅是检查它们是否发生时，可以使用如下代码：

with check_warnings(quiet=True) as w:
    warnings.warn("foo")
    assert str(w.args[0]) == "foo"
    warnings.warn("bar")
    assert str(w.args[0]) == "bar"
    assert str(w.warnings[0].args[0]) == "foo"
    assert str(w.warnings[1].args[0]) == "bar"
    w.reset()
    assert len(w.warnings) == 0

这里将捕获所有警告，测试代码将直接测试捕获的警告。

在 3.2 版更改: 新建可选参数 过滤器 和 安静的 .

class test.support.warnings_helper.WarningsRecorder

用于记录单元测试警告的类。参见文档 check_warnings() 更多详细信息。