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.FS_NONASCII¶

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

test.support.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.TESTFN_UNICODE¶

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

test.support.TESTFN_ENCODING¶

Set tosys.getfilesystemencoding().

test.support.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.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.TESTFN_NONASCII¶

Set to a filename containing theFS_NONASCII character.

test.support.IPV6_ENABLED¶

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

test.support.SAVEDCWD¶

Set toos.getcwd().

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

ReturnTrue if running on CPython, not on Windows, and configurationnot set withWITH_DOC_STRINGS.

test.support.HAVE_DOCSTRINGS¶

Check for presence of 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.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.forget(module_name)¶

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

test.support.unload(name)¶

Deletename fromsys.modules.

test.support.unlink(filename)¶

Callos.unlink() onfilename. On Windows platforms, this iswrapped with a wait loop that checks for the existence fo the file.

test.support.rmdir(filename)¶

Callos.rmdir() onfilename. On Windows platforms, this iswrapped with a wait loop that checks for the existence of the file.

test.support.rmtree(path)¶

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

test.support.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.

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.system_must_validate_cert(f)¶

Raiseunittest.SkipTest on TLS certification validation failures.

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.create_empty_file(filename)¶

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

test.support.fd_count()¶

Count the number of open file descriptors.

test.support.match_test(test)¶

Matchtest to patterns set inset_match_tests().

test.support.set_match_tests(patterns)¶

Define match test with regular expressionpatterns.

test.support.run_unittest(*classes)¶

Executeunittest.TestCase subclasses passed to the function. Thefunction scans the classes for methods starting with the prefixtest_and executes the tests individually.

It is also legal to pass strings as parameters; these should be keys insys.modules. Each associated module will be scanned byunittest.TestLoader.loadTestsFromModule(). This is usually seen in thefollowingtest_main() function:

deftest_main():support.run_unittest(__name__)

This will run all tests defined in the named module.

test.support.run_doctest(module,verbosity=None,optionflags=0)¶

Rundoctest.testmod() on the givenmodule. Return(failure_count,test_count).

Ifverbosity isNone,doctest.testmod() is run with verbosityset toverbose. Otherwise, it is run with verbosity set toNone.optionflags is passed asoptionflags todoctest.testmod().

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:

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

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.

test.support.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.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.strip_python_strerr(stderr)¶

Strip thestderr of a Python process from potential debug outputemitted by the interpreter. This will typically be run on the result ofsubprocess.Popen.communicate().

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.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.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.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.temp_umask(umask)¶

A context manager that temporarily sets the process umask.

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

A context manager that raisesResourceDenied when various issueswith the internet connection manifest themselves as exceptions.

test.support.disable_faulthandler()¶

A context manager that replacessys.stderr withsys.__stderr__.

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 upon entry andreenables it upon exit.

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.wait_threads_exit(timeout=60.0)¶

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

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

Context manager to startthreads. It attempts to join the threads uponexit.

test.support.calcobjsize(fmt)¶

Returnstruct.calcsize() fornP{fmt}0n or, ifgettotalrefcountexists,2PnP{fmt}0P.

test.support.calcvobjsize(fmt)¶

Returnstruct.calcsize() fornPn{fmt}0n or, ifgettotalrefcountexists,2PnPn{fmt}0P.

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

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

test.support.can_symlink()¶

ReturnTrue if the OS supports symbolic links,Falseotherwise.

test.support.can_xattr()¶

ReturnTrue if the OS supports xattr,Falseotherwise.

@test.support.skip_unless_symlink¶

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

@test.support.skip_unless_xattr¶

A decorator for running tests that require support for xattr.

@test.support.skip_unless_bind_unix_socket¶

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

@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.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, raiseunittest.SkipTest.

@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, raiseunittest.SkipTest.

@test.support.requires_mac_version(*min_version)¶

Decorator for the minimum version when running test on Mac OS X. If theMAC OS X version is less than the minimum, raiseunittest.SkipTest.

@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.cpython_only(test)¶

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

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

@test.support.refcount_test(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.reap_threads(func)¶

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

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

Decorator for tests that fill the address space.f is the function towrap.

test.support.make_bad_fd()¶

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

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

New in version 3.8.

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

Openurl. If open fails, raisesTestFailed.

test.support.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.

New in version 3.1.

test.support.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'])

New in version 3.1.

test.support.modules_setup()¶

Return a copy ofsys.modules.

test.support.modules_cleanup(oldmodules)¶

Remove modules except foroldmodules andencodings in order topreserve internal cache.

test.support.threading_setup()¶

Return current thread count and copy of dangling threads.

test.support.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.join_thread(thread,timeout=30.0)¶

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

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.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.bind_unix_socket(sock,addr)¶

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

test.support.catch_threading_exception()¶

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

Attributes set when an exception is catched:

• exc_type

• exc_value

• exc_traceback

• thread

Seethreading.excepthook() documentation.

These attributes are deleted at the context manager exit.

Usage:

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

New in version 3.8.

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)

New in version 3.8.

test.support.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.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.fs_is_case_insensitive(directory)¶

ReturnTrue if the file system fordirectory is case-insensitive.

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 ‘__’.

New 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 thatiter is 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=(),blacklist=())¶

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.

Theblacklist argument can be a set of names that must not be treated as part ofthe 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'}blacklist={'baz'}# Undocumented name.# bar imports part of its API from _bar.support.check__all__(self,bar,('bar','_bar'),extra=extra,blacklist=blacklist)

New in version 3.6.

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.

New in version 3.8.14.

Thetest.support module defines the following classes:

classtest.support.TransientResource(exc,**kwargs)¶

Instances are a context manager that raisesResourceDenied if thespecified exception type is raised. Any keyword arguments are treated asattribute/value pairs to be compared against any exception raised within thewith statement. Only if all pairs match properly againstattributes on the exception isResourceDenied raised.

classtest.support.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.

EnvironmentVarGuard.set(envvar,value)¶

Temporarily set the environment variableenvvar to the value ofvalue.

EnvironmentVarGuard.unset(envvar)¶

Temporarily unset the environment variableenvvar.

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.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.DirsOnSysPath(*paths)¶

A context manager to temporarily add directories to sys.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.

classtest.support.SaveSignals¶

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

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

classtest.support.WarningsRecorder¶

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

classtest.support.BasicTestRunner¶

run(test)¶

Runtest and return the result.

classtest.support.TestHandler(logging.handlers.BufferingHandler)¶

Class for logging support.

classtest.support.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__().

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.

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 is set,env_vars is used as a freshenvironment.

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

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.

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.