test — Regression tests package for Python¶

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 — Utilities for the Python test suite¶

Thetest.support module provides support for Python’s regressiontest suite.

This module defines the following exceptions:

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.

Thetest.support module defines the following constants:

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¶

True if the running interpreter is Jython.

test.support.is_android¶

True if the system is Android.

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.

Its default value is 5 seconds.

See alsoINTERNET_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().

Its default value is 1 minute.

See alsoLOOPBACK_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.

Its default value is 30 seconds.

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.

Its default value is 5 minutes.

See alsoLOOPBACK_TIMEOUT,INTERNET_TIMEOUT andSHORT_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.

Added in version 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¶

Set to the top level directory that containstest.support.

test.support.TEST_HOME_DIR¶

Set to the top level directory for the test package.

test.support.TEST_DATA_DIR¶

Set to thedata directory within the test package.

test.support.MAX_Py_ssize_t¶

Set tosys.maxsize for big memory tests.

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.

See also theMISSING_C_DOCSTRINGS variable.

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.

Thetest.support module defines the following functions:

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

Run the loop body untilbreak stops the loop.

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

Example:

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

Example of error=False usage:

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

Seebusy_retry() documentation for the parameters usage.

Example raising an exception after SHORT_TIMEOUT seconds:

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

Example of error=False usage:

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

ReturnTrue if Python was not built with-O0 or-Og.

test.support.with_pymalloc()¶

Return_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.

Added in version 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.

Example use with output streams:

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

Example use with input stream:

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.

Usage:

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.

Usage:

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.

Added in version 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.

Added in version 3.9.

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

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

Raise anAssertionError if the process exit code is not equal toexitcode.

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

Added in version 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¶

Decorator for skipping tests ifzlib doesn’t exist.

@test.support.requires_gzip¶

Decorator for skipping tests ifgzip doesn’t exist.

@test.support.requires_bz2¶

Decorator for skipping tests ifbz2 doesn’t exist.

@test.support.requires_lzma¶

Decorator for skipping tests iflzma doesn’t exist.

@test.support.requires_resource(resource)¶

Decorator for skipping tests ifresource is not available.

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

Decorator for bigmem tests.

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.

Usage:

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)

Added in version 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.

By default this skips private attributes beginning with ‘_’ butincludes all magic methods, i.e. those starting and ending in ‘__’.

Added in version 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.

Example use:

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)

Added in version 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.

Added in version 3.10.

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

Assert that typetp cannot be instantiated usingargs andkwds.

Added in version 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.

Added in version 3.11.

Thetest.support module defines the following classes:

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.

On both platforms, the old value is restored by__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 — Utilities for socket tests¶

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 — Utilities for the Python execution tests¶

Thetest.support.script_helper module provides support for Python’sscript execution tests.

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.

Changed in version 3.9:The function no longer strips whitespaces fromstderr.

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.

Changed in version 3.9:The function no longer strips whitespaces fromstderr.

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.

Seeassert_python_ok() for more options.

Changed in version 3.9:The function no longer strips whitespaces fromstderr.

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 — Support tools for testing correct bytecode generation¶

Thetest.support.bytecode_helper module provides support for testingand inspecting bytecode generation.

The module defines the following class:

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

Attributes set when an exception is caught:

• exc_type

• exc_value

• exc_traceback

• thread

Seethreading.excepthook() documentation.

These attributes are deleted at the context manager exit.

Usage:

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)

Added in version 3.8.

test.support.os_helper — Utilities for os tests¶

Thetest.support.os_helper module provides support for os tests.

test.support.os_helper.FS_NONASCII¶

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

test.support.os_helper.SAVEDCWD¶

Set toos.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.

Changed in version 3.1:Added dictionary interface.

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

Temporarily unset the environment variableenvvar.

test.support.os_helper.can_symlink()¶

ReturnTrue if the OS supports symbolic links,Falseotherwise.

test.support.os_helper.can_xattr()¶

ReturnTrue if the OS supports xattr,Falseotherwise.

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 — Utilities for import tests¶

Thetest.support.import_helper module provides support for import tests.

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.

This function will raiseImportError if the named module cannot beimported.

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# implementationpy_warnings=import_fresh_module('warnings',blocked=['_warnings'])c_warnings=import_fresh_module('warnings',fresh=['_warnings'])

Added in version 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.

Added in version 3.1.

test.support.import_helper.modules_setup()¶

Return a copy ofsys.modules.

test.support.import_helper.modules_cleanup(oldmodules)¶

Remove modules except foroldmodules andencodings in order topreserve internal cache.

test.support.import_helper.unload(name)¶

Deletename fromsys.modules.

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 — Utilities for warnings tests¶

Thetest.support.warnings_helper module provides support for warnings tests.

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

Added in version 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.

Added in version 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.

If no arguments are specified, it defaults to:

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.

Changed in version 3.2:New optional argumentsfilters andquiet.

classtest.support.warnings_helper.WarningsRecorder¶

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