test --- Python 的回歸測試 (regression tests) 套件¶

Thetest package contains all regression tests for Python as well as themodulestest.support andtest.regrtest.test.support is used to enhance your tests whiletest.regrtest drives the testing suite.

Each module in thetest package whose name starts withtest_ is atesting suite for a specific module or feature. All new tests should be writtenusing theunittest ordoctest module. Some older tests arewritten using a "traditional" testing style that compares output printed tosys.stdout; this style of test is considered deprecated.

importunittestfromtestimportsupportclassMyTestCase1(unittest.TestCase):# Only use setUp() and tearDown() if necessarydefsetUp(self):...codetoexecuteinpreparationfortests...deftearDown(self):...codetoexecutetocleanupaftertests...deftest_feature_one(self):# Test feature one....testingcode...deftest_feature_two(self):# Test feature two....testingcode......moretestmethods...classMyTestCase2(unittest.TestCase):...samestructureasMyTestCase1......moretestclasses...if__name__=='__main__':unittest.main()

test.support --- Python 測試套件的工具¶

test.support 模組提供 Python 回歸測試套件的支援。

此模組定義了以下例外：

exceptiontest.support.TestFailed¶

Exception to be raised when a test fails. This is deprecated in favor ofunittest-based tests andunittest.TestCase's assertionmethods.

exceptiontest.support.ResourceDenied¶

Subclass ofunittest.SkipTest. Raised when a resource (such as anetwork connection) is not available. Raised by therequires()function.

test.support 模組定義了以下常數：

test.support.verbose¶

True when verbose output is enabled. Should be checked when moredetailed information is desired about a running test.verbose is set bytest.regrtest.

test.support.is_jython¶

如果執行的直譯器是 Jython，則為True。

test.support.is_android¶

如果系統是 Android，則為True。

test.support.unix_shell¶

Path for shell if not on Windows; otherwiseNone.

test.support.LOOPBACK_TIMEOUT¶

Timeout in seconds for tests using a network server listening on the networklocal loopback interface like127.0.0.1.

The timeout is long enough to prevent test failure: it takes into accountthat the client and the server can run in different threads or evendifferent processes.

The timeout should be long enough forconnect(),recv() andsend() methods ofsocket.socket.

預設值為 5 秒。

另請參閱INTERNET_TIMEOUT。

test.support.INTERNET_TIMEOUT¶

Timeout in seconds for network requests going to the internet.

The timeout is short enough to prevent a test to wait for too long if theinternet request is blocked for whatever reason.

Usually, a timeout usingINTERNET_TIMEOUT should not mark a test asfailed, but skip the test instead: seetransient_internet().

預設值為 1 分鐘。

另請參閱LOOPBACK_TIMEOUT。

test.support.SHORT_TIMEOUT¶

Timeout in seconds to mark a test as failed if the test takes "too long".

The timeout value depends on the regrtest--timeout command line option.

If a test usingSHORT_TIMEOUT starts to fail randomly on slowbuildbots, useLONG_TIMEOUT instead.

預設值為 30 秒。

test.support.LONG_TIMEOUT¶

Timeout in seconds to detect when a test hangs.

It is long enough to reduce the risk of test failure on the slowest Pythonbuildbots. It should not be used to mark a test as failed if the test takes"too long". The timeout value depends on the regrtest--timeout commandline option.

預設值為 5 分鐘。

請參閱LOOPBACK_TIMEOUT、INTERNET_TIMEOUT 和SHORT_TIMEOUT。

test.support.PGO¶

Set when tests can be skipped when they are not useful for PGO.

test.support.PIPE_MAX_SIZE¶

A constant that is likely larger than the underlying OS pipe buffer size,to make writes blocking.

test.support.Py_DEBUG¶

True if Python was built with thePy_DEBUG macrodefined, that is, ifPython wasbuilt in debug mode.

在 3.12 版被加入.

test.support.SOCK_MAX_SIZE¶

A constant that is likely larger than the underlying OS socket buffer size,to make writes blocking.

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 byset_memlimit() as the memory limit for big memory tests.Limited byMAX_Py_ssize_t.

test.support.real_max_memuse¶

Set byset_memlimit() as the memory limit for big memory tests. Notlimited byMAX_Py_ssize_t.

test.support.MISSING_C_DOCSTRINGS¶

Set toTrue if Python is built without docstrings (theWITH_DOC_STRINGS macro is not defined).See theconfigure--without-doc-strings option.

See also theHAVE_DOCSTRINGS variable.

test.support.HAVE_DOCSTRINGS¶

Set toTrue if function docstrings are available.See thepython-OO option, which strips docstrings of functions implemented in Python.

請參閱MISSING_C_DOCSTRINGS 變數。

test.support.TEST_HTTP_URL¶

Define the URL of a dedicated HTTP server for the network tests.

test.support.ALWAYS_EQ¶

Object that is equal to anything. Used to test mixed type comparison.

test.support.NEVER_EQ¶

Object that is not equal to anything (even toALWAYS_EQ).Used to test mixed type comparison.

test.support.LARGEST¶

Object that is greater than anything (except itself).Used to test mixed type comparison.

test.support.SMALLEST¶

Object that is less than anything (except itself).Used to test mixed type comparison.

test.support 模組定義了以下函式：

test.support.busy_retry(timeout,err_msg=None,/,*,error=True)¶

執行迴圈主體直到break 停止迴圈。

Aftertimeout seconds, raise anAssertionError iferror is true,or just stop the loop iferror is false.

範例：

for_insupport.busy_retry(support.SHORT_TIMEOUT):ifcheck():break

error=False 用法範例：

for_insupport.busy_retry(support.SHORT_TIMEOUT,error=False):ifcheck():breakelse:raiseRuntimeError('my custom error')

test.support.sleeping_retry(timeout,err_msg=None,/,*,init_delay=0.010,max_delay=1.0,error=True)¶

Wait strategy that applies exponential backoff.

Run the loop body untilbreak stops the loop. Sleep at each loopiteration, but not at the first iteration. The sleep delay is doubled ateach iteration (up tomax_delay seconds).

請見busy_retry() 文件以瞭解參數用法。

在 SHORT_TIMEOUT 秒後引發例外的範例：

for_insupport.sleeping_retry(support.SHORT_TIMEOUT):ifcheck():break

error=False 用法範例：

for_insupport.sleeping_retry(support.SHORT_TIMEOUT,error=False):ifcheck():breakelse:raiseRuntimeError('my custom error')

test.support.is_resource_enabled(resource)¶

ReturnTrue ifresource is enabled and available. The list ofavailable resources is only set whentest.regrtest is executing thetests.

test.support.python_is_optimized()¶

如果 Python 不是使用-O0 或-Og 建置則回傳True。

test.support.with_pymalloc()¶

回傳_testcapi.WITH_PYMALLOC。

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

RaiseResourceDenied ifresource is not available.msg is theargument toResourceDenied if it is raised. Always returnsTrue if called by a function whose__name__ is'__main__'.Used when tests are executed bytest.regrtest.

test.support.sortdict(dict)¶

Return a repr ofdict with keys sorted.

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

Return the path to the file namedfilename. If no match is foundfilename is returned. This does not equal a failure since it could be thepath to the file.

Settingsubdir indicates a relative path to use to find the filerather than looking directly in the path directories.

test.support.get_pagesize()¶

Get size of a page in bytes.

在 3.12 版被加入.

test.support.setswitchinterval(interval)¶

Set thesys.setswitchinterval() to the giveninterval. Definesa minimum interval for Android systems to prevent the system from hanging.

test.support.check_impl_detail(**guards)¶

Use this check to guard CPython's implementation-specific tests or torun them only on the implementations guarded by the arguments. Thisfunction returnsTrue orFalse depending on the host platform.Example usage:

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

Set the values formax_memuse andreal_max_memuse for bigmemory tests.

test.support.record_original_stdout(stdout)¶

Store the value fromstdout. It is meant to hold the stdout at thetime the regrtest began.

test.support.get_original_stdout()¶

Return the original stdout set byrecord_original_stdout() orsys.stdout if it's not set.

test.support.args_from_interpreter_flags()¶

Return a list of command line arguments reproducing the current settingsinsys.flags andsys.warnoptions.

test.support.optim_args_from_interpreter_flags()¶

Return a list of command line arguments reproducing the currentoptimization settings insys.flags.

test.support.captured_stdin()¶

test.support.captured_stdout()¶

test.support.captured_stderr()¶

A context managers that temporarily replaces the named stream withio.StringIO object.

使用輸出串流的範例：

withcaptured_stdout()asstdout,captured_stderr()asstderr:print("hello")print("error",file=sys.stderr)assertstdout.getvalue()=="hello\n"assertstderr.getvalue()=="error\n"

使用輸入串流的範例：

withcaptured_stdin()asstdin:stdin.write('hello\n')stdin.seek(0)# call test code that consumes from sys.stdincaptured=input()self.assertEqual(captured,"hello")

test.support.disable_faulthandler()¶

A context manager that temporary disablesfaulthandler.

test.support.gc_collect()¶

Force as many objects as possible to be collected. This is needed becausetimely deallocation is not guaranteed by the garbage collector. This meansthat__del__ methods may be called later than expected and weakrefsmay remain alive for longer than expected.

test.support.disable_gc()¶

A context manager that disables the garbage collector on entry. Onexit, the garbage collector is restored to its prior state.

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

Context manager to swap out an attribute with a new object.

用法：

withswap_attr(obj,"attr",5):...

This will setobj.attr to 5 for the duration of thewith block,restoring the old value at the end of the block. Ifattr doesn'texist onobj, it will be created and then deleted at the end of theblock.

The old value (orNone if it doesn't exist) will be assigned to thetarget of the "as" clause, if there is one.

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

Context manager to swap out an item with a new object.

用法：

withswap_item(obj,"item",5):...

This will setobj["item"] to 5 for the duration of thewith block,restoring the old value at the end of the block. Ifitem doesn'texist onobj, it will be created and then deleted at the end of theblock.

The old value (orNone if it doesn't exist) will be assigned to thetarget of the "as" clause, if there is one.

test.support.flush_std_streams()¶

Call theflush() method onsys.stdout and then onsys.stderr. It can be used to make sure that the logs order isconsistent before writing into stderr.

在 3.11 版被加入.

test.support.print_warning(msg)¶

Print a warning intosys.__stderr__. Format the message as:f"Warning--{msg}". Ifmsg is made of multiple lines, add"Warning--" prefix to each line.

在 3.9 版被加入.

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

Wait until processpid completes and check that the process exit code isexitcode.

如果行程退出代號不等於exitcode 則引發AssertionError。

If the process runs longer thantimeout seconds (SHORT_TIMEOUT bydefault), kill the process and raise anAssertionError. The timeoutfeature is not available on Windows.

在 3.9 版被加入.

test.support.calcobjsize(fmt)¶

Return the size of thePyObject whose structure members aredefined byfmt. The returned value includes the size of the Python object header and alignment.

test.support.calcvobjsize(fmt)¶

Return the size of thePyVarObject whose structure members aredefined byfmt. The returned value includes the size of the Python object header and alignment.

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

For testcasetest, assert that thesys.getsizeof foro plus the GCheader size equalssize.

@test.support.anticipate_failure(condition)¶

A decorator to conditionally mark tests withunittest.expectedFailure(). Any use of this decorator shouldhave an associated comment identifying the relevant tracker issue.

test.support.system_must_validate_cert(f)¶

A decorator that skips the decorated test on TLS certification validation failures.

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

A decorator for running a function in a different locale, correctlyresetting it after it has finished.catstr is the locale category asa string (for example"LC_ALL"). Thelocales passed will be triedsequentially, and the first valid locale will be used.

@test.support.run_with_tz(tz)¶

A decorator for running a function in a specific timezone, correctlyresetting it after it has finished.

@test.support.requires_freebsd_version(*min_version)¶

Decorator for the minimum version when running test on FreeBSD. If theFreeBSD version is less than the minimum, the test is skipped.

@test.support.requires_linux_version(*min_version)¶

Decorator for the minimum version when running test on Linux. If theLinux version is less than the minimum, the test is skipped.

@test.support.requires_mac_version(*min_version)¶

Decorator for the minimum version when running test on macOS. If themacOS version is less than the minimum, the test is skipped.

@test.support.requires_gil_enabled¶

Decorator for skipping tests on the free-threaded build. If theGIL is disabled, the test is skipped.

@test.support.requires_IEEE_754¶

Decorator for skipping tests on non-IEEE 754 platforms.

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

Decorator for only running the test ifHAVE_DOCSTRINGS.

@test.support.requires_limited_api¶

Decorator for only running the test ifLimited C APIis available.

@test.support.cpython_only¶

Decorator for tests only applicable to CPython.

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

Decorator for invokingcheck_impl_detail() onguards. If thatreturnsFalse, then usesmsg as the reason for skipping the test.

@test.support.no_tracing¶

Decorator to temporarily turn off tracing for the duration of the test.

@test.support.refcount_test¶

Decorator for tests which involve reference counting. The decorator doesnot run the test if it is not run by CPython. Any trace function is unsetfor the duration of the test to prevent unexpected refcounts caused bythe trace function.

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

大記憶體測試的裝飾器。

size is a requested size for the test (in arbitrary, test-interpretedunits.)memuse is the number of bytes per unit for the test, or a goodestimate of it. For example, a test that needs two byte buffers, of 4 GiBeach, could be decorated with@bigmemtest(size=_4G,memuse=2).

Thesize argument is normally passed to the decorated test method as anextra argument. Ifdry_run isTrue, the value passed to the testmethod may be less than the requested value. Ifdry_run isFalse, itmeans the test doesn't support dummy runs when-M is not specified.

@test.support.bigaddrspacetest¶

Decorator for tests that fill the address space.

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

Test for syntax errors instatement by attempting to compilestatement.testcase is theunittest instance for the test.errtext is theregular expression which should match the string representation of theraisedSyntaxError. Iflineno is notNone, compares tothe line of the exception. Ifoffset is notNone, compares tothe offset of the exception.

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

Openurl. If open fails, raisesTestFailed.

test.support.reap_children()¶

Use this at the end oftest_main whenever sub-processes are started.This will help ensure that no extra children (zombies) stick around tohog resources and create problems when looking for refleaks.

test.support.get_attribute(obj,name)¶

Get an attribute, raisingunittest.SkipTest ifAttributeErroris raised.

test.support.catch_unraisable_exception()¶

Context manager catching unraisable exception usingsys.unraisablehook().

Storing the exception value (cm.unraisable.exc_value) creates areference cycle. The reference cycle is broken explicitly when the contextmanager exits.

Storing the object (cm.unraisable.object) can resurrect it if it is setto an object which is being finalized. Exiting the context manager clearsthe stored object.

用法：

withsupport.catch_unraisable_exception()ascm:# 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)¶

Generic implementation of theunittestload_tests protocol foruse in test packages.pkg_dir is the root directory of the package;loader,standard_tests, andpattern are the arguments expected byload_tests. In simple cases, the test package's__init__.pycan be the following:

importosfromtest.supportimportload_package_testsdefload_tests(*args):returnload_package_tests(os.path.dirname(__file__),*args)

test.support.detect_api_mismatch(ref_api,other_api,*,ignore=())¶

Returns the set of attributes, functions or methods ofref_api notfound onother_api, except for a defined list of items to beignored in this check specified inignore.

這預設會跳過以 '_' 開頭的私有屬性，但會包含所有魔術方法，即以 '__' 開頭和結尾的方法。

在 3.5 版被加入.

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

Overrideobject_to_patch.attr_name withnew_value. Also addcleanup procedure totest_instance to restoreobject_to_patch forattr_name. Theattr_name should be a valid attribute forobject_to_patch.

test.support.run_in_subinterp(code)¶

Runcode in subinterpreter. Raiseunittest.SkipTest iftracemalloc is enabled.

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

Assert instances ofcls are deallocated after iterating.

test.support.missing_compiler_executable(cmd_names=[])¶

Check for the existence of the compiler executables whose names are listedincmd_names or all the compiler executables whencmd_names is emptyand return the first missing executable orNone when none is foundmissing.

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

Assert that the__all__ variable ofmodule contains all public names.

The module's public names (its API) are detected automaticallybased on whether they match the public name convention and were defined inmodule.

Thename_of_module argument can specify (as a string or tuple thereof) whatmodule(s) an API could be defined in order to be detected as a publicAPI. One case for this is whenmodule imports part of its public API fromother modules, possibly a C backend (likecsv and its_csv).

Theextra argument can be a set of names that wouldn't otherwise be automaticallydetected as "public", like objects without a proper__module__attribute. If provided, it will be added to the automatically detected ones.

Thenot_exported argument can be a set of names that must not be treatedas part of the public API even though their names indicate otherwise.

用法範例：

importbarimportfooimportunittestfromtestimportsupportclassMiscTestCase(unittest.TestCase):deftest__all__(self):support.check__all__(self,foo)classOtherTestCase(unittest.TestCase):deftest__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()¶

Skip tests if themultiprocessing.synchronize module is missing, ifthere is no available semaphore implementation, or if creating a lock raisesanOSError.

在 3.10 版被加入.

test.support.check_disallow_instantiation(test_case,tp,*args,**kwds)¶

Assert that typetp cannot be instantiated usingargs andkwds.

在 3.10 版被加入.

test.support.adjust_int_max_str_digits(max_digits)¶

This function returns a context manager that will change the globalsys.set_int_max_str_digits() setting for the duration of thecontext to allow execution of test code that needs a different limiton the number of digits when converting between an integer and string.

在 3.11 版被加入.

test.support 模組定義了以下類別：

classtest.support.SuppressCrashReport¶

A context manager used to try to prevent crash dialog popups on tests thatare expected to crash a subprocess.

On Windows, it disables Windows Error Reporting dialogs usingSetErrorMode.

On UNIX,resource.setrlimit() is used to setresource.RLIMIT_CORE's soft limit to 0 to prevent coredump filecreation.

在兩個平台上，舊值會被__exit__() 還原。

classtest.support.SaveSignals¶

Class to save and restore signal handlers registered by the Python signalhandler.

save(self)¶

Save the signal handlers to a dictionary mapping signal numbers to thecurrent signal handler.

restore(self)¶

Set the signal numbers from thesave() dictionary to the savedhandler.

classtest.support.Matcher¶

matches(self,d,**kwargs)¶

Try to match a single dict with the supplied arguments.

match_value(self,k,dv,v)¶

Try to match a single stored value (dv) with a supplied value (v).

test.support.socket_helper --- 用於 socket 測試的工具¶

Thetest.support.socket_helper module provides support for socket tests.

test.support.socket_helper.IPV6_ENABLED¶

Set toTrue if IPv6 is enabled on this host,False otherwise.

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

Returns an unused port that should be suitable for binding. This isachieved by creating a temporary socket with the same family and type asthesock parameter (default isAF_INET,SOCK_STREAM),and binding it to the specified host address (defaults to0.0.0.0)with the port set to 0, eliciting an unused ephemeral port from the OS.The temporary socket is then closed and deleted, and the ephemeral port isreturned.

Either this method orbind_port() should be used for any testswhere a server socket needs to be bound to a particular port for theduration of the test.Which one to use depends on whether the calling code is creating a Pythonsocket, or if an unused port needs to be provided in a constructoror passed to an external program (i.e. the-accept argument toopenssl's s_server mode). Always preferbind_port() overfind_unused_port() where possible. Using a hard coded port isdiscouraged since it can make multiple instances of the test impossible torun simultaneously, which is a problem for buildbots.

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

Bind the socket to a free port and return the port number. Relies onephemeral ports in order to ensure we are using an unbound port. This isimportant as many tests may be running simultaneously, especially in abuildbot environment. This method raises an exception if thesock.family isAF_INET andsock.type isSOCK_STREAM, and the socket hasSO_REUSEADDR orSO_REUSEPORT set on it.Tests should never set these socket options for TCP/IP sockets.The only case for setting these options is testing multicasting viamultiple UDP sockets.

Additionally, if theSO_EXCLUSIVEADDRUSE socket option isavailable (i.e. on Windows), it will be set on the socket. This willprevent anyone else from binding to our host/port for the duration of thetest.

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

Bind a Unix socket, raisingunittest.SkipTest ifPermissionError is raised.

@test.support.socket_helper.skip_unless_bind_unix_socket¶

A decorator for running tests that require a functionalbind() for Unixsockets.

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

A context manager that raisesResourceDenied whenvarious issues with the internet connection manifest themselves asexceptions.

test.support.script_helper --- 用於 Python 執行測試的工具¶

test.support.script_helper 模組提供 Python 的腳本執行測試的支援。

test.support.script_helper.interpreter_requires_environment()¶

ReturnTrue ifsys.executableinterpreter requires environmentvariables in order to be able to run at all.

This is designed to be used with@unittest.skipIf() to annotate teststhat need to use anassert_python*() function to launch an isolatedmode (-I) or no environment mode (-E) sub-interpreter process.

A normal build & test does not run into this situation but it can happenwhen trying to run the standard library test suite from an interpreter thatdoesn't have an obvious home with Python's current home finding logic.

SettingPYTHONHOME is one way to get most of the testsuite to runin that situation.PYTHONPATH orPYTHONUSERSITE areother common environment variables that might impact whether or not theinterpreter can start.

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

Set up the environment based onenv_vars for running the interpreterin a subprocess. The values can include__isolated,__cleanenv,__cwd, andTERM.

在 3.9 版的變更:此函式不再從stderr 中移除空白。

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

Assert that running the interpreter withargs and optional environmentvariablesenv_vars succeeds (rc==0) and return a(returncode,stdout,stderr) tuple.

If the__cleanenv keyword-only parameter is set,env_vars is used as a freshenvironment.

Python is started in isolated mode (command line option-I),except if the__isolated keyword-only parameter is set toFalse.

在 3.9 版的變更:此函式不再從stderr 中移除空白。

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

Assert that running the interpreter withargs and optional environmentvariablesenv_vars fails (rc!=0) and return a(returncode,stdout,stderr) tuple.

更多選項請見assert_python_ok()。

在 3.9 版的變更:此函式不再從stderr 中移除空白。

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

Run a Python subprocess with the given arguments.

kw is extra keyword args to pass tosubprocess.Popen(). Returns asubprocess.Popen object.

test.support.script_helper.kill_python(p)¶

Run the givensubprocess.Popen process until completion and returnstdout.

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

Create script containingsource in pathscript_dir andscript_basename.Ifomit_suffix isFalse, append.py to the name. Return the fullscript path.

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

Create zip file atzip_dir andzip_basename with extensionzip whichcontains the files inscript_name.name_in_zip is the archive name.Return a tuple containing(fullpath,fullpathofarchivename).

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

Create a directory namedpkg_dir containing an__init__ file withinit_source as its contents.

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

Create a zip package directory with a path ofzip_dir andzip_basenamecontaining an empty__init__ file and a filescript_basenamecontaining thesource. Ifcompiled isTrue, both source files willbe compiled and added to the zip package. Return a tuple of the full zippath and the archive name for the zip file.

test.support.bytecode_helper --- 用於測試位元組碼能正確產生的支援工具¶

test.support.bytecode_helper 模組提供測試和檢查位元組碼產生的支援。

此模組定義了以下類別：

classtest.support.bytecode_helper.BytecodeTestCase(unittest.TestCase)¶

This class has custom assertion methods for inspecting bytecode.

BytecodeTestCase.get_disassembly_as_string(co)¶

Return the disassembly ofco as string.

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

Return instr ifopname is found, otherwise throwsAssertionError.

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

ThrowsAssertionError ifopname is found.

test.support.threading_helper --- Utilities for threading tests¶

Thetest.support.threading_helper module provides support for threading tests.

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

Join athread withintimeout. Raise anAssertionError if threadis still alive aftertimeout seconds.

@test.support.threading_helper.reap_threads¶

Decorator to ensure the threads are cleaned up even if the test fails.

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

Context manager to startthreads, which is a sequence of threads.unlock is a function called after the threads are started, even if anexception was raised; an example would bethreading.Event.set().start_threads will attempt to join the started threads upon exit.

test.support.threading_helper.threading_cleanup(*original_values)¶

Cleanup up threads not specified inoriginal_values. Designed to emita warning if a test leaves running threads in the background.

test.support.threading_helper.threading_setup()¶

Return current thread count and copy of dangling threads.

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

Context manager to wait until all threads created in thewith statementexit.

test.support.threading_helper.catch_threading_exception()¶

Context manager catchingthreading.Thread exception usingthreading.excepthook().

當捕捉到例外時會設定的屬性：

• exc_type

• exc_value

• exc_traceback

• thread

參閱threading.excepthook() 文件。

這些屬性會在離開情境管理器時被刪除。

用法：

withthreading_helper.catch_threading_exception()ascm:# 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 --- 用於 os 測試的工具¶

test.support.os_helper 模組提供 os 測試的支援。

test.support.os_helper.FS_NONASCII¶

A non-ASCII character encodable byos.fsencode().

test.support.os_helper.SAVEDCWD¶

設定為os.getcwd()。

test.support.os_helper.TESTFN¶

Set to a name that is safe to use as the name of a temporary file. Anytemporary file that is created should be closed and unlinked (removed).

test.support.os_helper.TESTFN_NONASCII¶

Set to a filename containing theFS_NONASCII character, if it exists.This guarantees that if the filename exists, it can be encoded and decodedwith the default filesystem encoding. This allows tests that require anon-ASCII filename to be easily skipped on platforms where they can't work.

test.support.os_helper.TESTFN_UNENCODABLE¶

Set to a filename (str type) that should not be able to be encoded by filesystem encoding in strict mode. It may beNone if it's not possible togenerate such a filename.

test.support.os_helper.TESTFN_UNDECODABLE¶

Set to a filename (bytes type) that should not be able to be decoded byfile system encoding in strict mode. It may beNone if it's notpossible to generate such a filename.

test.support.os_helper.TESTFN_UNICODE¶

Set to a non-ASCII name for a temporary file.

classtest.support.os_helper.EnvironmentVarGuard¶

Class used to temporarily set or unset environment variables. Instances canbe used as a context manager and have a complete dictionary interface forquerying/modifying the underlyingos.environ. After exit from thecontext manager all changes to environment variables done through thisinstance will be rolled back.

在 3.1 版的變更:新增字典介面。

classtest.support.os_helper.FakePath(path)¶

Simplepath-like object. It implements the__fspath__()method which just returns thepath argument. Ifpath is an exception,it will be raised in__fspath__().

EnvironmentVarGuard.set(envvar,value)¶

Temporarily set the environment variableenvvar to the value ofvalue.

EnvironmentVarGuard.unset(envvar)¶

暫時取消環境變數envvar。

test.support.os_helper.can_symlink()¶

如果作業系統支援符號連結則回傳True，否則回傳False。

test.support.os_helper.can_xattr()¶

如果作業系統支援 xattr 則回傳True，否則回傳False。

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

A context manager that temporarily changes the current workingdirectory topath and yields the directory.

Ifquiet isFalse, the context manager raises an exceptionon error. Otherwise, it issues only a warning and keeps the currentworking directory the same.

test.support.os_helper.create_empty_file(filename)¶

Create an empty file withfilename. If it already exists, truncate it.

test.support.os_helper.fd_count()¶

Count the number of open file descriptors.

test.support.os_helper.fs_is_case_insensitive(directory)¶

ReturnTrue if the file system fordirectory is case-insensitive.

test.support.os_helper.make_bad_fd()¶

Create an invalid file descriptor by opening and closing a temporary file,and returning its descriptor.

test.support.os_helper.rmdir(filename)¶

Callos.rmdir() onfilename. On Windows platforms, this iswrapped with a wait loop that checks for the existence of the file,which is needed due to antivirus programs that can hold files open and preventdeletion.

test.support.os_helper.rmtree(path)¶

Callshutil.rmtree() onpath or callos.lstat() andos.rmdir() to remove a path and its contents. As withrmdir(),on Windows platformsthis is wrapped with a wait loop that checks for the existence of the files.

@test.support.os_helper.skip_unless_symlink¶

A decorator for running tests that require support for symbolic links.

@test.support.os_helper.skip_unless_xattr¶

A decorator for running tests that require support for xattr.

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

A context manager that temporarily creates a new directory andchanges the current working directory (CWD).

The context manager creates a temporary directory in the currentdirectory with namename before temporarily changing the currentworking directory. Ifname isNone, the temporary directory iscreated usingtempfile.mkdtemp().

Ifquiet isFalse and it is not possible to create or changethe CWD, an error is raised. Otherwise, only a warning is raisedand the original CWD is used.

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

A context manager that creates a temporary directory atpath andyields the directory.

Ifpath isNone, the temporary directory is created usingtempfile.mkdtemp(). Ifquiet isFalse, the context managerraises an exception on error. Otherwise, ifpath is specified andcannot be created, only a warning is issued.

test.support.os_helper.temp_umask(umask)¶

A context manager that temporarily sets the process umask.

test.support.os_helper.unlink(filename)¶

Callos.unlink() onfilename. As withrmdir(),on Windows platforms, this iswrapped with a wait loop that checks for the existence of the file.

test.support.import_helper --- 用於 import 測試的工具¶

test.support.import_helper 模組提供 import 測試的支援。

test.support.import_helper.forget(module_name)¶

Remove the module namedmodule_name fromsys.modules and delete anybyte-compiled files of the module.

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

This function imports and returns a fresh copy of the named Python moduleby removing the named module fromsys.modules before doing the import.Note that unlikereload(), the original module is not affected bythis operation.

fresh is an iterable of additional module names that are also removedfrom thesys.modules cache before doing the import.

blocked is an iterable of module names that are replaced withNonein the module cache during the import to ensure that attempts to importthem raiseImportError.

The named module and any modules named in thefresh andblockedparameters are saved before starting the import and then reinserted intosys.modules when the fresh import is complete.

Module and package deprecation messages are suppressed during this importifdeprecated isTrue.

如果無法引入指定的模組則此函式會引發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# implementationpy_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=())¶

This function imports and returns the named module. Unlike a normalimport, this function raisesunittest.SkipTest if the modulecannot be imported.

Module and package deprecation messages are suppressed during this importifdeprecated isTrue. If a module is required on a platform butoptional for others, setrequired_on to an iterable of platform prefixeswhich will be compared againstsys.platform.

在 3.1 版被加入.

test.support.import_helper.modules_setup()¶

回傳sys.modules 的複本。

test.support.import_helper.modules_cleanup(oldmodules)¶

Remove modules except foroldmodules andencodings in order topreserve internal cache.

test.support.import_helper.unload(name)¶

從sys.modules 中刪除name。

test.support.import_helper.make_legacy_pyc(source)¶

Move aPEP 3147/PEP 488 pyc file to its legacy pyc location and return the filesystem path to the legacy pyc file. Thesource value is the file systempath to the source file. It does not need to exist, however the PEP3147/488 pyc file must exist.

classtest.support.import_helper.CleanImport(*module_names)¶

A context manager to force import to return a new module reference. Thisis useful for testing module-level behaviors, such as the emission of aDeprecationWarning on import. Example usage:

withCleanImport('foo'):importlib.import_module('foo')# New reference.

classtest.support.import_helper.DirsOnSysPath(*paths)¶

A context manager to temporarily add directories tosys.path.

This makes a copy ofsys.path, appends any directories givenas positional arguments, then revertssys.path to the copiedsettings when the context ends.

Note thatallsys.path modifications in the body of thecontext manager, including replacement of the object,will be reverted at the end of the block.

test.support.warnings_helper --- 用於 warnings 測試的工具¶

test.support.warnings_helper 模組提供 warnings 測試的支援。

test.support.warnings_helper.ignore_warnings(*,category)¶

Suppress warnings that are instances ofcategory,which must beWarning or a subclass.Roughly equivalent towarnings.catch_warnings()withwarnings.simplefilter('ignore',category=category).For example:

@warning_helper.ignore_warnings(category=DeprecationWarning)deftest_suppress_warning():# do something

在 3.8 版被加入.

test.support.warnings_helper.check_no_resource_warning(testcase)¶

Context manager to check that noResourceWarning was raised. Youmust remove the object which may emitResourceWarning before theend of the context manager.

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

Test for syntax warning instatement by attempting to compilestatement.Test also that theSyntaxWarning is emitted only once, and that itwill be converted to aSyntaxError when turned into error.testcase is theunittest instance for the test.errtext is theregular expression which should match the string representation of theemittedSyntaxWarning and raisedSyntaxError. Iflinenois notNone, compares to the line of the warning and exception.Ifoffset is notNone, compares to the offset of the exception.

在 3.8 版被加入.

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

A convenience wrapper forwarnings.catch_warnings() that makes iteasier to test that a warning was correctly raised. It is approximatelyequivalent to callingwarnings.catch_warnings(record=True) withwarnings.simplefilter() set toalways and with the option toautomatically validate the results that are recorded.

check_warnings accepts 2-tuples of the form("messageregexp",WarningCategory) as positional arguments. If one or morefilters areprovided, or if the optional keyword argumentquiet isFalse,it checks to make sure the warnings are as expected: each specified filtermust match at least one of the warnings raised by the enclosed code or thetest fails, and if any warnings are raised that do not match any of thespecified filters the test fails. To disable the first of these checks,setquiet toTrue.

如果沒有指定引數，預設為：

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

In this case all warnings are caught and no errors are raised.

On entry to the context manager, aWarningRecorder instance isreturned. The underlying warnings list fromcatch_warnings() is available via the recorder object'swarnings attribute. As a convenience, the attributes of the objectrepresenting the most recent warning can also be accessed directly throughthe recorder object (see example below). If no warning has been raised,then any of the attributes that would otherwise be expected on an objectrepresenting a warning will returnNone.

The recorder object also has areset() method, which clears thewarnings list.

The context manager is designed to be used like this:

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

In this case if either warning was not raised, or some other warning wasraised,check_warnings() would raise an error.

When a test needs to look more deeply into the warnings, rather thanjust checking whether or not they occurred, code like this can be used:

withcheck_warnings(quiet=True)asw:warnings.warn("foo")assertstr(w.args[0])=="foo"warnings.warn("bar")assertstr(w.args[0])=="bar"assertstr(w.warnings[0].args[0])=="foo"assertstr(w.warnings[1].args[0])=="bar"w.reset()assertlen(w.warnings)==0

Here all warnings will be caught, and the test code tests the capturedwarnings directly.

在 3.2 版的變更:新的可選引數filters 和quiet。

classtest.support.warnings_helper.WarningsRecorder¶

Class used to record warnings for unit tests. See documentation ofcheck_warnings() above for more details.