Docs4dev
Docs
python / 3.7.2rc1 / all / library-test.html

test —用于 Python 的回归测试包

Note

test软件包仅供 Python 内部使用。它被记录为 Python 核心开发人员的利益。不建议在 Python 标准库之外使用此软件包，因为此处提到的代码可以更改，也可以在不考虑 Python 版本之间删除的情况下删除。

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

test软件包中名称以test_开头的每个模块都是针对特定模块或Function的测试套件。所有新测试都应使用unittest或doctest模块编写。一些较早的测试是使用“传统”测试样式编写的，该样式将打印输出与sys.stdout进行比较；这种测试风格被认为已弃用。

See also

  • Module unittest

  • 编写 PyUnit 回归测试。

  • Module doctest

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

为测试包编写单元测试

使用unittest模块的测试最好遵循一些准则。一种是pass以test_开头并以被测试模块的名称结尾来命名测试模块。测试模块中的测试方法应以test_开头，并以对该方法进行测试的描述结尾。这是必需的，以便测试驱动程序将这些方法识别为测试方法。另外，不应包括该方法的文档字符串。Comments(例如# 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 的脚本或passpython -m unittest CLI 运行。

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

  • 测试套件应使用所有类，函数和常量。这不仅包括要向外界展示的外部 API，还包括“私有”代码。

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

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

  • 耗尽尽可能多的代码路径。测试分支发生的位置，并因此调整 Importing，以确保采用代码中的许多不同路径。

  • 添加一个显式测试，以发现针对测试代码发现的所有错误。如果将来更改代码，这将确保错误不会再次出现。

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

  • 如果测试取决于 os 的特定条件，则在try测试之前，请先验证条件是否已经存在。

  • 导入尽可能少的模块，并尽快进行。这样可以最大程度地减少测试的外部依赖性，还可以最大程度地减少由于导入模块的副作用而可能引起的异常行为。

  • try使代码重用最大化。有时，测试的差异可能与所使用的 Importing 类型一样小。pass使用指定 Importing 的类将基本测试类子类化，从而最大程度地减少代码重复：

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。

See also

  • 测试驱动开发

  • 肯特·贝克(Kent Beck)写的一本关于在代码之前编写测试的书。

使用命令行界面运行测试

借助-m选项，可以将test软件包作为脚本运行以驱动 Python 的回归测试套件：python -m test .在引擎盖下，它使用test.regrtest；先前 Python 版本中使用的调用 python -m test.regrtest 仍然有效.单独运行脚本会自动开始运行test包中的所有回归测试.pass查找包中名称以test_开头的所有模块，将其导入并执行test_main()(如果存在)或pass unittest.TestLoader.loadTestsFromModule 加载测试(如果test_main不存在)来执行此操作.要执行的测试的名称也可以传递给脚本.指定单个回归测试( python -m test test_spam **)将最小化输出，并且仅显示测试pass还是失败。

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

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

test.support — Python 测试套件的 Util

test.support模块提供对 Python 回归测试套件的支持。

Note

test.support不是公共模块。此处记录了该文档，以帮助 Python 开发人员编写测试。该模块的 API 可以更改，而不会在发行版之间向后兼容。

该模块定义以下异常：

  • exception test.support. TestFailed

  • exception test.support. ResourceDenied

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

  • test.support. verbose

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

  • test.support. is_jython

    • True(如果正在运行的 Interpreter 是 Jython)。

  • test.support. is_android

    • True(如果系统是 Android)。

  • test.support. unix_shell

    • 如果不是在 Windows 上，则为 shell 的路径；否则为None。

  • test.support. FS_NONASCII

  • test.support. TESTFN

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

  • test.support. TESTFN_UNICODE

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

  • test.support. TESTFN_ENCODING

  • test.support. TESTFN_UNENCODABLE

    • 设置为一个文件名(str 类型)，该文件名不能以严格模式pass文件系统编码进行编码。如果无法生成这样的文件名，则可能是None。

  • test.support. TESTFN_UNDECODABLE

    • 设置为一个文件名(字节类型)，该文件名在严格模式下不能被文件系统编码解码。如果无法生成这样的文件名，则可能是None。

  • test.support. TESTFN_NONASCII

  • test.support. IPV6_ENABLED

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

  • test.support. SAVEDCWD

  • test.support. PGO

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

  • test.support. PIPE_MAX_SIZE

    • 一个常量，可能大于基础 OS 管道缓冲区的大小，以使写入阻塞。

  • test.support. SOCK_MAX_SIZE

    • 一个可能大于基础 os 套接字缓冲区大小的常数，以使写入阻塞。

  • test.support. TEST_SUPPORT_DIR

  • test.support. TEST_HOME_DIR

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

  • test.support. TEST_DATA_DIR

    • 设置到测试包中的data目录。

  • test.support. MAX_Py_ssize_t

  • test.support. max_memuse

  • test.support. real_max_memuse

  • 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模块定义以下Function：

  • test.support. forget(* module_name *)

    • 从sys.modules中删除名为* module_name *的模块，并删除该模块的所有字节编译文件。

  • test.support. unload(* name *)

    • 从sys.modules删除* name *。

  • test.support. unlink(* filename *)

    • 在* filename *上调用os.unlink()。在 Windows 平台上，这用 await 循环包装，该循环检查文件是否存在。

  • test.support. rmdir(* filename *)

    • 在* filename *上调用os.rmdir()。在 Windows 平台上，此方法包装有一个 await 循环，用于检查文件是否存在。

  • test.support. rmtree(* path *)

    • 在* path *上调用shutil.rmtree()或在os.lstat()和os.rmdir()上删除路径及其内容。在 Windows 平台上，这用 await 循环包装，该循环检查文件是否存在。

  • test.support. make_legacy_pyc(* source *)

    • 将 PEP 3147/ PEP 488 pyc 文件移动到其旧版 pyc 位置，然后将文件系统路径返回到旧版 pyc 文件。 * source *值是源文件的文件系统路径。它不需要存在，但是 PEP 3147/488 pyc 文件必须存在。

  • test.support. is_resource_enabled(资源)

    • 如果* resource *已启用且可用，则返回True。仅当test.regrtest执行测试时才设置可用资源列表。

  • test.support. python_is_optimized ( )

    • 如果不是使用-O0或-Og构建 Python，则返回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 *)

  • test.support. sortdict(* dict *)

    • 返回带有键排序的* dict *的代表。

  • test.support. findfile(* filename ， subdir = None *)

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

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

  • test.support. create_empty_file(* filename *)

    • 使用* filename *创建一个空文件。如果已经存在，请截断它。

  • test.support. fd_count ( )

    • 计算打开文件 Descriptors 的数量。

  • test.support. match_test(* test *)

  • test.support. set_match_tests(模式)

    • 使用正则表达式* patterns *定义匹配测试。

  • test.support. run_unittest(*班)

    • 执行传递给该函数的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 *)
    • 在给定的* module *上运行doctest.testmod()。返回(failure_count, test_count)。

如果* verbosity *为None，则在 verbosity 设置为verbose的情况下运行doctest.testmod()。否则，将其详细程度设置为None。 * optionflags *作为optionflags传递给doctest.testmod()。

  • test.support. setswitchinterval(* interval *)

    • 将sys.setswitchinterval()设置为给定的* interval *。定义 Android 系统的最小间隔，以防止系统挂起。

  • test.support. check_impl_detail(**后卫)

    • 使用此检查可以保护 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.simplefilter()设置为always并具有自动验证记录结果的选项来调用warnings.catch_warnings(record=True)的情况。

check_warnings接受格式为("message regexp", WarningCategory)的 2Tuples 作为位置参数。如果提供了一个或多个* filters ，或者可选关键字参数 quiet 是False，它将检查以确保警告符合预期：每个指定的过滤器必须至少与随附代码或测试失败，并且如果引发任何与任何指定过滤器都不匹配的警告，则测试失败。要禁用这些检查中的第一个，请将 quiet *设置为True。

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

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

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

进入上下文 Management 器后，将返回WarningRecorder实例。 catch_warnings()的基础警告列表可pass Logger 对象的warnings属性获得。为方便起见，代表最新警告的对象的属性也可以直接pass Logger 对象访问(请参见下面的示例)。如果没有引发警告，则表示警告的对象上原应具有的任何属性都将返回None。

Logger 对象还具有reset()方法，该方法清除警告列表。

上下文 Management 器的设计用途如下：

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

    • 上下文 Management 器检查是否未引发ResourceWarning。您必须在上下文 Management 器结束之前删除可能发出ResourceWarning的对象。

  • test.support. set_memlimit(* limit *)

  • test.support. record_original_stdout(* stdout *)

    • 存储来自* stdout *的值。它旨在在重新测试开始时保持标准输出。

  • test.support. get_original_stdout ( )

  • test.support. strip_python_strerr(* stderr *)

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

    • 一个上下文 Management 器，它临时用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"

与 Importing 流一起使用的示例：

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 *)
    • 上下文 Management 器，它在* path *处创建一个临时目录并产生该目录。

如果* path 为None，则使用tempfile.mkdtemp()创建临时目录。如果 quiet 是False，则上下文 Management 器会在错误时引发异常。否则，如果指定了 path *并且无法创建，则仅发出警告。

  • test.support. change_cwd(* path ， quiet = False *)
    • 上下文 Management 器，用于临时将当前工作目录更改为* path *并产生该目录。

如果* quiet *为False，则上下文 Management 器将引发错误异常。否则，它仅发出警告，并保持当前工作目录不变。

  • test.support. temp_cwd(* name ='tempcwd'， quiet = False *)
    • 上下文 Management 器，用于临时创建新目录并更改当前工作目录(CWD)。

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

如果* quiet *为False，并且无法创建或更改 CWD，则会引发错误。否则，只会发出警告，并使用原始的 CWD。

  • test.support. temp_umask(* umask *)

    • 临时设置进程 umask 的上下文 Management 器。

  • test.support. transient_internet(* resource_name ，**，* timeout = 30.0 ， errnos =()*)

    • 当互联网连接的各种问题表现为异常时，上下文 Management 器会引发ResourceDenied。

  • test.support. disable_faulthandler ( )

    • 一个上下文 Management 器，将sys.stderr替换为sys.__stderr__。

  • test.support. gc_collect ( )

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

  • test.support. disable_gc ( )

    • 上下文 Management 器，它在进入时禁用垃圾收集器，并在退出时重新启用垃圾收集器。

  • test.support. swap_attr(* obj ， attr ， new_val *)

    • 上下文 Management 器，用于用新对象交换属性。

Usage:

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

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

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

  • test.support. swap_item(* obj ， attr ， new_val *)
    • 上下文 Management 器，用于用新对象交换项目。

Usage:

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

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

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

  • test.support. wait_threads_exit(* timeout = 60.0 *)

    • 上下文 Management 器 await，直到在with语句中创建的所有线程退出。

  • test.support. start_threads(* threads ， unlock = None *)

    • 上下文 Management 器以启动* threads *。它try在退出时加入线程。

  • 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 ，assert o 的sys.getsizeof加上 GC 头大小等于 size *。

  • test.support. can_xattr ( )

    • 如果 os 支持 xattr，则返回True，否则返回False。

  • @ test.support. skip_unless_xattr

    • 装饰器，用于运行需要 xattr 支持的测试。

  • @ test.support. skip_unless_bind_unix_socket

    • 装饰器，用于运行需要 Unix 套接字Function性 bind()的测试。

  • @ test.support. anticipate_failure(条件)

    • 装饰器，有条件地用unittest.expectedFailure()标记测试。对该装饰器的任何使用都应具有关联的 Comments，以标识相关的跟踪器问题。

  • @ test.support. run_with_locale(* catstr ，* locales *)

    • 装饰器，用于在其他区域中运行Function，完成后可以正确将其重置。 * catstr 是字符串形式的语言环境类别(例如"LC_ALL")。传递的 locales *将按 Sequences try，并且将使用第一个有效的语言环境。

  • @ test.support. run_with_tz(* tz *)

    • 装饰器，用于在特定时区中运行Function，并在完成时正确将其重置。

  • @ 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

  • @ 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 运行，则装饰器不会运行测试。在测试期间未设置任何跟踪Function，以防止由跟踪Function导致意外的引用计数。

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

    • pass打开和关闭临时文件，然后返回其 Descriptors 来创建无效的文件 Descriptors。

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

    • passtry编译* statement 来测试 statement *中的语法错误。 * testcase *是该测试的unittest实例。 * errtext 是正则表达式，应与凸起的SyntaxError的字符串表示形式匹配。如果 lineno 不是None，则与异常的行进行比较。如果 offset *不是None，则与异常的偏移量进行比较。

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

    • passtry编译* statement 来测试 statement *中的语法警告。还测试SyntaxWarning仅发出一次，并且在变成错误时将转换为SyntaxError。 * testcase *是测试的unittest实例。 * errtext 是正则表达式，应与发出的SyntaxWarning和提升的SyntaxError的字符串表示形式匹配。如果 lineno 不是None，则与警告和异常的行进行比较。如果 offset *不是None，则与异常的偏移量进行比较。

3.8 版的新Function。

  • 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 版中的新Function。

  • test.support. import_fresh_module(* name ， fresh =()， blocked =()， deprecated = False *)
    • 此函数pass在导入之前从sys.modules中删除命名模块来导入并返回命名 Python 模块的新副本。请注意，与reload()不同，原始模块不受此操作影响。

  • fresh *是可迭代的其他模块名称，这些名称在执行导入之前也已从sys.modules缓存中删除。

  • blocked *是可重复使用的模块名称，在导入过程中模块高速缓存中的模块名称被None替换，以确保导入它们的try引发ImportError。

在开始导入之前，已保存命名模块以及在* fresh 和 blocked *参数中命名的任何模块，然后在完成新导入后重新插入sys.modules。

如果* deprecated *为True，则会在导入过程中禁止使用模块和程序包弃用消息。

如果无法导入命名模块，则此函数将引发ImportError。

Example use:

# 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 版中的新Function。

  • test.support. modules_setup ( )

  • test.support. modules_cleanup(* oldmodules *)

    • 除去* oldmodules *和encodings以外的模块，以保留内部缓存。

  • test.support. threading_setup ( )

    • 返回当前线程数和悬空线程的副本。

  • test.support. threading_cleanup(*原始值)

    • 清理* original_values *中未指定的线程。旨在在测试将运行线程留在后台时发出警告。

  • test.support. join_thread(* thread ， timeout = 30.0 *)

    • 在* timeout 内加入 thread 。如果线程在超时*秒后仍然处于活动状态，则引发AssertionError。

  • test.support. reap_children ( )

    • 每当子流程启动时，请在test_main的末尾使用此选项。这将有助于确保没有多余的孩子(僵尸)会四处寻找生猪资源，并且在寻找返工时不会造成麻烦。

  • test.support. get_attribute(* obj ， name *)

  • test.support. bind_port(* sock ， host = HOST *)

    • 将套接字绑定到空闲端口并返回端口号。依靠临时端口以确保我们使用的是未绑定端口。这很重要，因为许多测试可能同时运行，尤其是在 buildbot 环境中。如果sock.family是AF_INET且sock.type是SOCK_STREAM，并且套接字上设置了SO_REUSEADDR或SO_REUSEPORT，则此方法引发异常。测试绝对不要为 TCP/IP 套接字设置这些套接字选项。设置这些选项的唯一情况是pass多个 UDP 套接字测试多播。

此外，如果SO_EXCLUSIVEADDRUSE套接字选项可用(例如，在 Windows 上)，则会在套接字上进行设置。这将防止其他人在测试期间绑定到我们的主机/端口。

捕获异常时设置的属性：

  • exc_type

  • exc_value

  • exc_traceback

  • thread

请参阅threading.excepthook()文档。

这些属性在上下文 Management 器 Export 处删除。

Usage:

with support.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 版的新Function。

  • test.support. catch_unraisable_exception ( )

存储异常值(cm.unraisable.exc_value)将创建一个参考周期。当上下文 Management 器退出时，引用周期被明确break。

如果将对象(cm.unraisable.object)设置为finally确定的对象，则可以恢复该对象。退出上下文 Management 器将清除存储的对象。

Usage:

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 版的新Function。

  • test.support. find_unused_port(* family = socket.AF_INET ， socktype = socket.SOCK_STREAM *)
    • 返回应该适合绑定的未使用端口。这是pass创建与sock参数具有相同的族和类型(默认值为AF_INET，SOCK_STREAM)的临时套接字，并将其绑定到端口设置为 0 的指定主机地址(默认为0.0.0.0)来实现的，从而引发未使用的临时 os 上的端口。然后关闭并删除该临时套接字，并返回临时端口。

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

  • 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 *的文件系统不区分大小写，则返回True。

  • test.support. detect_api_mismatch(* ref_api ， other_api ，**，* ignore =()*)

    • 返回在* other_api 上找不到的 ref_api 的属性，函数或方法的集合，除了在 ignore *中指定的此检查中将忽略的已定义项列表。

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

3.5 版中的新Function。

  • 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 *)

  • test.support. check_free_after_iterating(* test ， iter ， cls ， args =()*)

    • assert 迭代后释放* 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 =()*)

    • assert* module *的__all__变量包含所有公共名称。

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

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

  • extra *参数可以是一组名称，否则将不会被自动检测为“公共”名称，例如没有适当的__module__属性的对象。如果提供的话，它将被添加到自动检测到的文件中。

  • blacklist *参数可以是一组名称，即使名称另有说明，也不能将其视为公共 API 的一部分。

Example use:

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 版的新Function。

test.support模块定义以下类别：

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

  • 类别 test.support. EnvironmentVarGuard

    • 用于临时设置或取消设置环境变量的类。实例可以用作上下文 Management 器，并具有用于查询/修改基础os.environ的完整词典接口。从上下文 Management 器退出后，pass该实例完成的所有对环境变量的更改将被回滚。

在版本 3.1 中更改：添加了词典界面。

  • EnvironmentVarGuard. set(* envvar ， value *)

    • 暂时将环境变量envvar设置为value的值。

  • EnvironmentVarGuard. unset(* envvar *)

    • 暂时取消设置环境变量envvar。

  • 类别 test.support. SuppressCrashReport

    • 一个上下文 Management 器，用于try防止预期会使子流程崩溃的测试上的崩溃对话框弹出窗口。

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

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

在两个平台上，旧值都由exit()恢复。

  • 类别 test.support. CleanImport(*模块名称)
    • 上下文 Management 器强制导入以返回新的模块引用。这对于测试模块级别的行为(例如在导入时发出 DeprecationWarning)很有用。用法示例：
with CleanImport('foo'):
    importlib.import_module('foo')  # New reference.
  • 类别 test.support. DirsOnSysPath(*路径)
    • 上下文 Management 器，用于将目录临时添加到 sys.path。

这将制作sys.path的副本，追加作为位置参数给出的所有目录，然后在上下文结束时将sys.path还原为复制的设置。

请注意，上下文 Management 器主体中的* all * sys.path修改(包括对象的替换)将在块的末尾恢复。

  • 类别 test.support. SaveSignals

    • 保存和恢复 Pythonsignal 处理程序注册的 signal 处理程序的类。

  • 类别 test.support. Matcher

      • matches((* self ， d ，** kwargs *)
      • try将单个字典与提供的参数匹配。

  • match_value(* self ， k ， dv ， v *)

    • try将单个存储的值(* dv )与提供的值( v *)相匹配。

  • 类别 test.support. WarningsRecorder

    • 用于记录单元测试警告的类。有关更多详细信息，请参见上面的check_warnings()文档。

  • 类别 test.support. BasicTestRunner

      • run(测试)
      • 运行* test *并返回结果。
    • class * test.support. TestHandler(* logging.handlers.BufferingHandler *)
    • 日志支持的类。

  • 类别 test.support. FakePath(路径)

    • 简单的path-like object。它实现了__fspath__()方法，该方法仅返回* path 参数。如果 path *是一个 exception，它将在__fspath__()中引发。

test.support.script_helper — Python 执行测试的 Util

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

  • test.support.script_helper. interpreter_requires_environment ( )
    • 如果sys.executable interpreter需要环境变量才能完全运行，则返回True。

它被设计为与@unittest.skipIf()一起使用，以 Comments 需要使用assert_python*()函数启动隔离模式(-I)或无环境模式(-E)子解释程序的测试。

正常的构建和测试不会遇到这种情况，但是当try从解释器运行标准库测试套件时，可能会发生这种情况，而该解释器没有 Python 当前的归位逻辑的明显归宿。

设置 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 *)

    • assert 使用* args 和可选环境变量 env_vars *运行解释器成功(rc == 0)，并返回(return code, stdout, stderr)Tuples。

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

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

  • test.support.script_helper. assert_python_failure( *args ， * env_vars *)
    • assert 使用* args 和可选的环境变量 env_vars *运行解释器失败(rc != 0)，并返回(return code, stdout, stderr)Tuples。

有关更多选项，请参见assert_python_ok()。

  • test.support.script_helper. spawn_python( *args ， stdout = subprocess.PIPE ， stderr = subprocess.STDOUT ， * kw *)
    • 使用给定的参数运行 Python 子进程。

  • test.support.script_helper. kill_python(* p *)

  • 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 *)

    • 在 extensions 为zip的* zip_dir 和 zip_basename 处创建 zip 文件，其中包含 script_name *中的文件。 * name_in_zip *是 Files 名称。返回一个包含(full path, full path of archive name)的 Tuples。

  • test.support.script_helper. make_pkg(* pkg_dir ， init_source =“''*)

    • 创建一个名为* pkg_dir *的目录，其中包含带有_init_source *作为其内容的__init__文件。

  • 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 。如果 compiled *为True，则两个源文件都将被编译并添加到 zip 包中。返回完整 zip 路径的 Tuples 和 zip 文件的 Files 名称。