test — Python 的回归测试包 — Python 文档
test — Python 的回归测试包
笔记
test 包仅供 Python 内部使用。 为了 Python 的核心开发人员的利益,它被记录下来。 不鼓励在 Python 标准库之外使用此包,因为此处提到的代码可能会在 Python 版本之间更改或删除,恕不另行通知。
test 包包含 Python 的所有回归测试以及模块 test.support 和 test.regrtest
。 test.support 用于增强您的测试,而 test.regrtest
驱动测试套件。
test 包中名称以 test_
开头的每个模块都是特定模块或功能的测试套件。 所有新测试都应使用 unittest 或 doctest 模块编写。 一些较旧的测试是使用“传统”测试风格编写的,将打印的输出与 sys.stdout
进行比较; 这种测试风格被认为是过时的。
为 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 将使用除 audio
和 largefile
资源之外的所有资源运行 test。 有关所有资源和更多命令行选项的列表,请运行 python -m test -h。
执行回归测试的其他一些方法取决于执行测试的平台。 在 Unix 上,您可以在构建 Python 的顶级目录中运行 make test。 在 Windows 上,从 PCbuild
目录执行 rt.bat 将运行所有回归测试。
test.support — Python 测试套件的实用程序
test.support 模块为 Python 的回归测试套件提供支持。
该模块定义了以下异常:
- 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
如果系统是 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 不可用,则提高 ResourceDenied。 msg 是 ResourceDenied 如果它被引发的参数。 如果由
__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)
- 将 test 与 set_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)
。如果 verbosity 是
None
,则 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,或者可选关键字参数 quiet 是False
,它会检查以确保警告如预期:每个指定的过滤器必须匹配至少一个由封闭代码引发的警告或测试失败,如果引发的任何警告与任何指定的过滤器不匹配,则测试失败。 要禁用这些检查中的第一个,请将 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 版更改: 新的可选参数 filters 和 quiet。
- test.support.check_no_resource_warning(testcase)
- 上下文管理器检查是否未引发 ResourceWarning。 您必须在上下文管理器结束之前删除可能发出 ResourceWarning 的对象。
- test.support.set_memlimit(limit)
- 为大内存测试设置 max_memuse 和 real_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.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.temp_dir(path=None, quiet=False)
在 path 处创建临时目录并生成该目录的上下文管理器。
如果 path 是
None
,则使用 tempfile.mkdtemp() 创建临时目录。 如果 quiet 是False
,则上下文管理器会在出错时引发异常。 否则,如果指定了 path 并且无法创建,则只会发出警告。
- test.support.change_cwd(path, quiet=False)
将当前工作目录临时更改为 path 并生成目录的上下文管理器。
如果 quiet 是
False
,则上下文管理器会在出错时引发异常。 否则,它只会发出警告并保持当前工作目录不变。
- test.support.temp_cwd(name='tempcwd', quiet=False)
临时创建新目录并更改当前工作目录 (CWD) 的上下文管理器。
在临时更改当前工作目录之前,上下文管理器在当前目录中创建一个名为 name 的临时目录。 如果 name 是
None
,则使用 tempfile.mkdtemp() 创建临时目录。如果 quiet 是
False
并且无法创建或更改 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,断言 o 的
sys.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_run 是
True
,则传递给测试方法的值可能小于请求的值。 如果 dry_run 为False
,则表示当未指定-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。
如果 deprecated 是
True
,则在此导入过程中会抑制模块和包弃用消息。 如果一个模块在平台上是必需的,但对其他人是可选的,请将 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。在开始导入之前保存命名模块以及在 fresh 和 blocked 参数中命名的任何模块,然后在新导入完成后重新插入到
sys.modules
中。如果 deprecated 是
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.modules_setup()
- 返回 sys.modules 的副本。
- test.support.modules_cleanup(oldmodules)
- 删除除 oldmodules 和
encodings
之外的模块以保留内部缓存。
- 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.family
为 AF_INET 且sock.type
为 SOCK_STREAM,并且套接字具有SO_REUSEADDR
或SO_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_INET、SOCK_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为包的根目录; loader、standard_tests 和 pattern 是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.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_name 的 object_to_patch。 attr_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)
- 临时设置环境变量
envvar
为value
的值。
- 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 是让大部分测试套件在这种情况下运行的一种方法。 PYTHONPATH 或
PYTHONUSERSITE
是其他常见的环境变量,可能会影响解释器是否可以启动。
- test.support.script_helper.run_python_until_end(*args, **env_vars)
- 设置基于 env_vars 的环境以在子进程中运行解释器。 这些值可以包括
__isolated
、__cleanenv
、__cwd
和TERM
。
- 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_dir 和 script_basename 中创建包含 source 的脚本。 如果 omit_suffix 是
False
,将.py
附加到名称。 返回完整的脚本路径。
- test.support.script_helper.make_zip_script(zip_dir, zip_basename, script_name, name_in_zip=None)
- 在 zip_dir 和 zip_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_dir 和 zip_basename 的 zip 包目录,其中包含一个空的
__init__
文件和一个包含 源的文件 script_basename' 。 如果 compiled 是True
,两个源文件都将被编译并添加到 zip 包中。 返回 zip 文件的完整 zip 路径和存档名称的元组。