test — Python 的回归测试包 — Python 文档

来自菜鸟教程
Python/docs/3.7/library/test
跳转至:导航、​搜索

test — Python 的回归测试包

笔记

test 包仅供 Python 内部使用。 为了 Python 的核心开发人员的利益,它被记录下来。 不鼓励在 Python 标准库之外使用此包,因为此处提到的代码可能会在 Python 版本之间更改或删除,恕不另行通知。



test 包包含 Python 的所有回归测试以及模块 test.supporttest.regrtesttest.support 用于增强您的测试,而 test.regrtest 驱动测试套件。

test 包中名称以 test_ 开头的每个模块都是特定模块或功能的测试套件。 所有新测试都应使用 unittestdoctest 模块编写。 一些较旧的测试是使用“传统”测试风格编写的,将打印的输出与 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 CLI 的脚本,或通过 python -m unittest CLI。

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

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

  • 首选白盒测试(在编写测试时检查正在测试的代码)。 黑盒测试(仅测试已发布的用户界面)不足以确保测试所有边界和边缘情况。

  • 确保测试所有可能的值,包括无效值。 这确保不仅所有有效值都是可接受的,而且不正确的值也得到正确处理。

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

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

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

  • 如果测试依赖于操作系统的特定条件,则在尝试测试之前验证该条件已经存在。

  • 导入尽可能少的模块并尽快完成。 这最大限度地减少了测试的外部依赖性,也最大限度地减少了导入模块的副作用可能导致的异常行为。

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

    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

也可以看看

测试驱动开发
Kent Beck 关于在编写代码之前编写测试的书。


使用命令行界面运行测试

test 包可以作为脚本运行来驱动 Python 的回归测试套件,这要归功于 -m 选项:python -m test。 在引擎盖下,它使用 test.regrtest; 在以前的 Python 版本中使用的调用 python -m test.regrtest 仍然有效。 单独运行脚本会自动开始运行 test 包中的所有回归测试。 它通过查找包中名称以 test_ 开头的所有模块,导入它们并执行函数 test_main()(如果存在)或通过 unittest.TestLoader.loadTestsFromModule if test_main 不存在。 要执行的测试的名称也可以传递给脚本。 指定单个回归测试 (python -m test test_spam) 将最小化输出并且只打印测试是通过还是失败。

直接运行 test 可以设置哪些资源可用于测试使用。 您可以使用 -u 命令行选项执行此操作。 将 all 指定为 -u 选项的值将启用所有可能的资源:python -m test -uall。 如果只需要一个资源(一种更常见的情况),则不需要的资源的逗号分隔列表可能会列在 all 之后。 命令 python -m test -uall,-audio,-largefile 将使用除 audiolargefile 资源之外的所有资源运行 test。 有关所有资源和更多命令行选项的列表,请运行 python -m test -h

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


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 启用详细输出时。 当需要有关运行测试的更多详细信息时,应进行检查。 verbosetest.regrtest 设置。
test.support.is_jython
True 如果正在运行的解释器是 Jython。
test.support.is_android
True 如果系统是 Android。
test.support.unix_shell
如果不在 Windows 上,则为 shell 的路径; 否则 None
test.support.FS_NONASCII
os.fsencode() 可编码的非 ASCII 字符。
test.support.TESTFN
设置为可安全用作临时文件名称的名称。 创建的任何临时文件都应关闭并取消链接(删除)。
test.support.TESTFN_UNICODE
设置为临时文件的非 ASCII 名称。
test.support.TESTFN_ENCODING
设置为 sys.getfilesystemencoding()
test.support.TESTFN_UNENCODABLE
设置为文件名(str 类型),在严格模式下,文件系统编码不应对其进行编码。 如果无法生成这样的文件名,则可能是 None
test.support.TESTFN_UNDECODABLE
设置为在严格模式下不能被文件系统编码解码的文件名(字节类型)。 如果无法生成这样的文件名,则可能是 None
test.support.TESTFN_NONASCII
设置为包含 FS_NONASCII 字符的文件名。
test.support.IPV6_ENABLED
如果在此主机上启用 IPV6,则设置为 True,否则设置为 False
test.support.SAVEDCWD
设置为 os.getcwd()
test.support.PGO
设置当测试对 PGO 没有用时可以跳过的时间。
test.support.PIPE_MAX_SIZE
一个可能大于底层操作系统管道缓冲区大小的常量,以使写入阻塞。
test.support.SOCK_MAX_SIZE
一个可能大于底层操作系统套接字缓冲区大小的常量,以使写入阻塞。
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
如果在 CPython 上运行,而不是在 Windows 上运行,并且未使用 WITH_DOC_STRINGS 设置配置,则返回 True
test.support.HAVE_DOCSTRINGS
检查文档字符串的存在。
test.support.TEST_HTTP_URL
为网络测试定义专用 HTTP 服务器的 URL。
test.support.ALWAYS_EQ
等于任何事物的对象。 用于测试混合类型比较。
test.support.LARGEST
比任何事物都大的对象(除了自身)。 用于测试混合类型比较。
test.support.SMALLEST
小于任何东西的对象(除了它本身)。 用于测试混合类型比较。

test.support 模块定义了以下函数:

test.support.forget(module_name)
sys.modules 中删除名为 module_name 的模块,并删除该模块的所有字节编译文件。
test.support.unload(name)
sys.modules 中删除 name
test.support.unlink(filename)
filename 上调用 os.unlink()。 在 Windows 平台上,这包含一个等待循环,用于检查文件是否存在。
test.support.rmdir(filename)
filename 上调用 os.rmdir()。 在 Windows 平台上,这包含一个等待循环,用于检查文件是否存在。
test.support.rmtree(path)
path 上调用 shutil.rmtree() 或调用 os.lstat()os.rmdir() 删除路径和其内容。 在 Windows 平台上,这包含一个等待循环,用于检查文件是否存在。
test.support.make_legacy_pyc(source)
将 PEP 3147/488 pyc 文件移动到其旧 pyc 位置,并将文件系统路径返回到旧 pyc 文件。 source 值是源文件的文件系统路径。 它不需要存在,但是 PEP 3147/488 pyc 文件必须存在。
test.support.is_resource_enabled(resource)
如果 resource 已启用且可用,则返回 True。 可用资源列表仅在 test.regrtest 执行测试时设置。
test.support.python_is_optimized()
如果 Python 不是用 -O0-Og 构建的,则返回 True
test.support.with_pymalloc()
返回 _testcapi.WITH_PYMALLOC
test.support.requires(resource, msg=None)
如果 resource 不可用,则提高 ResourceDeniedmsgResourceDenied 如果它被引发的参数。 如果由 __name__'__main__' 的函数调用,则始终返回 True。 当测试由 test.regrtest 执行时使用。
test.support.system_must_validate_cert(f)
在 TLS 认证验证失败时提高 unittest.SkipTest
test.support.sortdict(dict)
返回 dict 的repr,键已排序。
test.support.findfile(filename, subdir=None)

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

设置 subdir 表示用于查找文件的相对路径,而不是直接在路径目录中查找。

test.support.create_empty_file(filename)
使用 文件名 创建一个空文件。 如果它已经存在,则截断它。
test.support.fd_count()
计算打开的文件描述符的数量。
test.support.match_test(test)
testset_match_tests() 中设置的模式匹配。
test.support.set_match_tests(patterns)
使用正则表达式 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)

如果 verbosityNone,则 doctest.testmod() 运行时详细设置为 verbose。 否则,它会在详细设置为 None 的情况下运行。 optionflags 作为 optionflags 传递给 doctest.testmod()

test.support.setswitchinterval(interval)
sys.setswitchinterval() 设置为给定的 interval。 定义 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.check_warnings(\*filters, quiet=True)

warnings.catch_warnings() 的便利包装器,可以更轻松地测试警告是否正确提出。 它大约相当于调用 warnings.catch_warnings(record=True) 并将 warnings.simplefilter() 设置为 always 并带有自动验证记录结果的选项。

check_warnings 接受 ("message regexp", WarningCategory) 形式的二元组作为位置参数。 如果提供了一个或多个 filters,或者可选关键字参数 quietFalse,它会检查以确保警告如预期:每个指定的过滤器必须匹配至少一个由封闭代码引发的警告或测试失败,如果引发的任何警告与任何指定的过滤器不匹配,则测试失败。 要禁用这些检查中的第一个,请将 quiet 设置为 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 版更改: 新的可选参数 filtersquiet

test.support.check_no_resource_warning(testcase)
上下文管理器检查是否未引发 ResourceWarning。 您必须在上下文管理器结束之前删除可能发出 ResourceWarning 的对象。
test.support.set_memlimit(limit)
为大内存测试设置 max_memusereal_max_memuse 的值。
test.support.record_original_stdout(stdout)
存储来自 stdout 的值。 它旨在在 regrtest 开始时保存标准输出。
test.support.get_original_stdout()
如果未设置,则返回由 record_original_stdout()sys.stdout 设置的原始标准输出。
test.support.strip_python_strerr(stderr)
从解释器发出的潜在调试输出中剥离 Python 进程的 stderr。 这通常会在 subprocess.Popen.communicate() 的结果上运行。
test.support.args_from_interpreter_flags()
返回重现 sys.flagssys.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.temp_dir(path=None, quiet=False)

path 处创建临时目录并生成该目录的上下文管理器。

如果 pathNone,则使用 tempfile.mkdtemp() 创建临时目录。 如果 quietFalse,则上下文管理器会在出错时引发异常。 否则,如果指定了 path 并且无法创建,则只会发出警告。

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

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

如果 quietFalse,则上下文管理器会在出错时引发异常。 否则,它只会发出警告并保持当前工作目录不变。

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

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

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

如果 quietFalse 并且无法创建或更改 CWD,则会引发错误。 否则,只会发出警告并使用原始 CWD。

test.support.temp_umask(umask)
临时设置进程 umask 的上下文管理器。
test.support.transient_internet(resource_name, *, timeout=30.0, errnos=())
当 Internet 连接的各种问题表现为异常时,上下文管理器会引发 ResourceDenied
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):
    ...

这将在 with 块的持续时间内将 obj.attr 设置为 5,在块的末尾恢复旧值。 如果 obj 上不存在 attr,则会在块的末尾创建并删除它。

旧值(或 None 如果不存在)将分配给“as”子句的目标,如果有的话。

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

上下文管理器用新对象换出一个项目。

用法:

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

这将在 with 块的持续时间内将 obj["item"] 设置为 5,在块的末尾恢复旧值。 如果 obj 上不存在 item,则会在块的末尾创建并删除它。

旧值(或 None 如果不存在)将分配给“as”子句的目标,如果有的话。

test.support.wait_threads_exit(timeout=60.0)
上下文管理器等待所有在 with 语句中创建的线程退出。
test.support.start_threads(threads, unlock=None)
上下文管理器启动 线程 。 它尝试在退出时加入线程。
test.support.calcobjsize(fmt)
nP{fmt}0n 返回 struct.calcsize(),或者,如果 gettotalrefcount 存在,则返回 2PnP{fmt}0P
test.support.calcvobjsize(fmt)
nPn{fmt}0n 返回 struct.calcsize(),或者,如果 gettotalrefcount 存在,则返回 2PnPn{fmt}0P
test.support.checksizeof(test, o, size)
对于测试用例 test,断言 osys.getsizeof 加上 GC 头大小等于 size
test.support.can_symlink()
如果操作系统支持符号链接,则返回 True,否则返回 False
test.support.can_xattr()
如果操作系统支持 xattr,则返回 True,否则返回 False
@test.support.skip_unless_symlink
用于运行需要支持符号链接的测试的装饰器。
@test.support.skip_unless_xattr
用于运行需要支持 xattr 的测试的装饰器。
@test.support.skip_unless_bind_unix_socket
用于运行需要 Unix 套接字功能性 bind() 的测试的装饰器。
@test.support.anticipate_failure(condition)
使用 unittest.expectedFailure() 有条件地标记测试的装饰器。 对这个装饰器的任何使用都应该有一个相关的注释来标识相关的跟踪器问题。
@test.support.run_with_locale(catstr, *locales)
一个装饰器,用于在不同的语言环境中运行一个函数,在它完成后正确地重置它。 catstr 是字符串形式的语言环境类别(例如 "LC_ALL")。 传递的 locales 将依次尝试,并使用第一个有效的语言环境。
@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)
如果 resource 不可用,则用于跳过测试的装饰器。
@test.support.requires_docstrings
仅在 HAVE_DOCSTRINGS 时运行测试的装饰器。
@test.support.cpython_only(test)
用于测试的装饰器仅适用于 CPython。
@test.support.impl_detail(msg=None, **guards)
用于在 guards 上调用 check_impl_detail() 的装饰器。 如果返回 False,则使用 msg 作为跳过测试的原因。
@test.support.no_tracing(func)
装饰器在测试期间暂时关闭跟踪。
@test.support.refcount_test(test)
涉及引用计数的测试的装饰器。 如果不是由 CPython 运行,装饰器不会运行测试。 在测试期间未设置任何跟踪功能,以防止由跟踪功能引起的意外引用计数。
@test.support.reap_threads(func)
装饰器以确保即使测试失败也清理线程。
@test.support.bigmemtest(size, memuse, dry_run=True)

bigmem 测试的装饰器。

size 是测试请求的大小(以任意的、测试解释的单位)。 memuse 是测试的每个单元的字节数,或者对它的一个很好的估计。 例如,需要两个字节缓冲区(每个 4 GiB)的测试可以用 @bigmemtest(size=_4G, memuse=2) 修饰。

size 参数通常作为额外参数传递给修饰的测试方法。 如果 dry_runTrue,则传递给测试方法的值可能小于请求的值。 如果 dry_runFalse,则表示当未指定 -M 时,测试不支持虚拟运行。

@test.support.bigaddrspacetest(f)
用于填充地址空间的测试的装饰器。 f 是要换行的函数。
test.support.make_bad_fd()
通过打开和关闭临时文件并返回其描述符来创建无效的文件描述符。
test.support.check_syntax_error(testcase, statement, errtext=, *, lineno=None, offset=None)
通过尝试编译 语句 来测试 语句 中的语法错误。 testcase 是测试的 unittest 实例。 errtext 是由 SyntaxError 引发的错误的文本。 如果 lineno 不是 None,则与 SyntaxError 的行进行比较。 如果 offset 不是 None,则与 SyntaxError 的偏移量进行比较。
test.support.open_urlresource(url, *args, **kw)
打开url。 如果打开失败,则引发 TestFailed
test.support.import_module(name, deprecated=False, *, required_on())

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

如果 deprecatedTrue,则在此导入过程中会抑制模块和包弃用消息。 如果一个模块在平台上是必需的,但对其他人是可选的,请将 required_on 设置为平台前缀的可迭代对象,将与 sys.platform 进行比较。

3.1 版中的新功能。

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

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

fresh 是附加模块名称的迭代,在执行导入之前也从 sys.modules 缓存中删除。

blocked 是一个可迭代的模块名称,在导入期间在模块缓存中替换为 None,以确保尝试导入它们会引发 ImportError

在开始导入之前保存命名模块以及在 freshblocked 参数中命名的任何模块,然后在新导入完成后重新插入到 sys.modules 中。

如果 deprecatedTrue,则在此导入过程中会抑制模块和包弃用消息。

如果无法导入命名模块,此函数将引发 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.modules_setup()
返回 sys.modules 的副本。
test.support.modules_cleanup(oldmodules)
删除除 oldmodulesencodings 之外的模块以保留内部缓存。
test.support.threading_setup()
返回当前线程数和悬空线程的副本。
test.support.threading_cleanup(*original_values)
清理 original_values 中未指定的线程。 设计用于在测试将正在运行的线程留在后台时发出警告。
test.support.join_thread(thread, timeout=30.0)
超时 内加入 线程 。 如果线程在 timeout 秒后仍处于活动状态,则引发 AssertionError
test.support.reap_children()
每当启动子进程时,在 test_main 的末尾使用它。 这将有助于确保没有额外的孩子(僵尸)在寻找 refleaks 时留下来掠夺资源并造成问题。
test.support.get_attribute(obj, name)
获取属性,如果 AttributeError 引发,则引发 unittest.SkipTest
test.support.bind_port(sock, host=HOST)

将套接字绑定到一个空闲端口并返回端口号。 依赖临时端口以确保我们使用的是未绑定端口。 这很重要,因为许多测试可能同时运行,尤其是在 buildbot 环境中。 如果 sock.familyAF_INETsock.typeSOCK_STREAM,并且套接字具有 SO_REUSEADDRSO_REUSEPORT 设置就可以了。 测试不应为 TCP/IP 套接字设置这些套接字选项。 设置这些选项的唯一情况是通过多个 UDP 套接字测试多播。

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

test.support.bind_unix_socket(sock, addr)
绑定一个 unix 套接字,如果 PermissionError 被引发,则引发 unittest.SkipTest
test.support.find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM)

返回应适合绑定的未使用端口。 这是通过创建与 sock 参数(默认为 AF_INETSOCK_STREAM)具有相同系列和类型的临时套接字,并将其绑定到指定主机来实现的地址(默认为 0.0.0.0),端口设置为 0,从操作系统中引出一个未使用的临时端口。 然后关闭并删除临时套接字,并返回临时端口。

此方法或 bind_port() 应该用于在测试期间需要将服务器套接字绑定到特定端口的任何测试。 使用哪一个取决于调用代码是否正在创建 Python 套接字,或者是否需要在构造函数中提供未使用的端口或传递给外部程序(即 openssl 的 s_server 模式的 -accept 参数)。 在可能的情况下,始终更喜欢 bind_port() 而不是 find_unused_port()。 不鼓励使用硬编码端口,因为它会使多个测试实例无法同时运行,这对构建机器人来说是一个问题。

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

unittest load_tests 协议的通用实现,用于测试包。 pkg_dir为包的根目录; loaderstandard_testspatternload_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.fs_is_case_insensitive(directory)
如果 directory 的文件系统不区分大小写,则返回 True
test.support.detect_api_mismatch(ref_api, other_api, *, ignore=())

返回在 other_api 上找不到的 ref_api 的属性、函数或方法集,除了 ignore 中指定的要在此检查中忽略的已定义项目列表.

默认情况下,这会跳过以“_”开头的私有属性,但包括所有魔术方法,即 以'__'开头和结尾的那些。

3.5 版中的新功能。

test.support.patch(test_instance, object_to_patch, attr_name, new_value)
new_value 覆盖 object_to_patch.attr_name。 还向 test_instance 添加清理程序以恢复 attr_nameobject_to_patchattr_name 应该是 object_to_patch 的有效属性。
test.support.run_in_subinterp(code)
在子解释器中运行 code。 如果启用 tracemalloc,则提高 unittest.SkipTest
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=(), blacklist=())

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

模块的公共名称(其 API)根据它们是否与公共名称约定匹配并在 module 中定义自动检测。

name_of_module 参数可以指定(作为字符串或元组)API 可以定义哪些模块以便被检测为公共 API。 一种情况是,当 module 从其他模块(可能是 C 后端(如 csv 及其 _csv)导入部分公共 API 时。

extra 参数可以是一组不会被自动检测为“公共”的名称,例如没有正确 __module__ 属性的对象。 如果提供,它将被添加到自动检测到的。

blacklist 参数可以是一组名称,即使它们的名称另有说明,也不能将其视为公共 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'}
        blacklist = {'baz'}  # Undocumented name.
        # bar imports part of its API from _bar.
        support.check__all__(self, bar, ('bar', '_bar'),
                             extra=extra, blacklist=blacklist)

3.6 版中的新功能。

test.support 模块定义了以下类:

class test.support.TransientResource(exc, **kwargs)
实例是一个上下文管理器,如果指定的异常类型被引发,它会引发 ResourceDenied。 任何关键字参数都被视为属性/值对,以与 with 语句中引发的任何异常进行比较。 仅当所有对与异常上的属性正确匹配时,才会引发 ResourceDenied
class test.support.EnvironmentVarGuard

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

3.1 版本变化: 增加字典接口。

EnvironmentVarGuard.set(envvar, value)
临时设置环境变量envvarvalue的值。
EnvironmentVarGuard.unset(envvar)
暂时取消设置环境变量 envvar
class test.support.SuppressCrashReport

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

在 Windows 上,它使用 SetErrorMode 禁用 Windows 错误报告对话框。

在 UNIX 上,resource.setrlimit() 用于将 resource.RLIMIT_CORE 的软限制设置为 0,以防止创建核心转储文件。

在两个平台上,旧值由 __exit__() 恢复。

class test.support.CleanImport(*module_names)

强制导入以返回新模块引用的上下文管理器。 这对于测试模块级行为非常有用,例如在导入时发出 DeprecationWarning。 用法示例:

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

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

这会复制 sys.path,附加任何作为位置参数给出的目录,然后在上下文结束时将 sys.path 恢复到复制的设置。

请注意,上下文管理器主体中的 all sys.path 修改,包括对象的替换,将在块的末尾恢复。

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.WarningsRecorder
用于记录单元测试警告的类。 有关更多详细信息,请参阅上面 check_warnings() 的文档。
class test.support.BasicTestRunner
;; run(test)
运行 test 并返回结果。
class test.support.TestHandler(logging.handlers.BufferingHandler)
用于日志记录支持的类。
class test.support.FakePath(path)
简单的 类路径对象 。 它实现了 __fspath__() 方法,该方法只返回 path 参数。 如果 path 是一个异常,它将在 __fspath__() 中引发。


test.support.script_helper — Python 执行测试的实用程序

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

test.support.script_helper.interpreter_requires_environment()

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

这旨在与 @unittest.skipIf() 一起使用以注释需要使用 assert_python*() 函数来启动隔离模式 (-I) 或无环境模式 ([ X167X]) 子解释器进程。

正常的构建和测试不会遇到这种情况,但是当尝试从解释器运行标准库测试套件时,可能会发生这种情况,该解释器与 Python 当前的 home 查找逻辑没有明显的 home。

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

test.support.script_helper.run_python_until_end(*args, **env_vars)
设置基于 env_vars 的环境以在子进程中运行解释器。 这些值可以包括 __isolated__cleanenv__cwdTERM
test.support.script_helper.assert_python_ok(*args, **env_vars)

断言使用 args 和可选环境变量 env_vars 运行解释器成功(rc == 0)并返回 (return code, stdout, stderr) 元组。

如果设置了 __cleanenv 关键字,则将 env_vars 用作新环境。

Python 以隔离模式启动(命令行选项 -I),除非 __isolated 关键字设置为 False

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

断言使用 args 和可选环境变量 env_vars 运行解释器失败 (rc != 0) 并返回 (return code, stdout, stderr) 元组。

有关更多选项,请参阅 assert_python_ok()

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

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

kw 是传递给 subprocess.Popen() 的额外关键字参数。 返回一个 subprocess.Popen 对象。

test.support.script_helper.kill_python(p)
运行给定的 subprocess.Popen 进程直到完成并返回标准输出。
test.support.script_helper.make_script(script_dir, script_basename, source, omit_suffix=False)
在路径 script_dirscript_basename 中创建包含 source 的脚本。 如果 omit_suffixFalse,将 .py 附加到名称。 返回完整的脚本路径。
test.support.script_helper.make_zip_script(zip_dir, zip_basename, script_name, name_in_zip=None)
zip_dirzip_basename 创建 zip 文件,扩展名为 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_dirzip_basename 的 zip 包目录,其中包含一个空的 __init__ 文件和一个包含 源的文件 script_basename' 。 如果 compiledTrue,两个源文件都将被编译并添加到 zip 包中。 返回 zip 文件的完整 zip 路径和存档名称的元组。