1:mod:`test` --- Regression tests package for Python 2=================================================== 3 4.. module:: test 5 :synopsis: Regression tests package containing the testing suite for Python. 6 7.. sectionauthor:: Brett Cannon <brett@python.org> 8 9.. note:: 10 The :mod:`test` package is meant for internal use by Python only. It is 11 documented for the benefit of the core developers of Python. Any use of 12 this package outside of Python's standard library is discouraged as code 13 mentioned here can change or be removed without notice between releases of 14 Python. 15 16-------------- 17 18The :mod:`test` package contains all regression tests for Python as well as the 19modules :mod:`test.support` and :mod:`test.regrtest`. 20:mod:`test.support` is used to enhance your tests while 21:mod:`test.regrtest` drives the testing suite. 22 23Each module in the :mod:`test` package whose name starts with ``test_`` is a 24testing suite for a specific module or feature. All new tests should be written 25using the :mod:`unittest` or :mod:`doctest` module. Some older tests are 26written using a "traditional" testing style that compares output printed to 27``sys.stdout``; this style of test is considered deprecated. 28 29 30.. seealso:: 31 32 Module :mod:`unittest` 33 Writing PyUnit regression tests. 34 35 Module :mod:`doctest` 36 Tests embedded in documentation strings. 37 38 39.. _writing-tests: 40 41Writing Unit Tests for the :mod:`test` package 42---------------------------------------------- 43 44It is preferred that tests that use the :mod:`unittest` module follow a few 45guidelines. One is to name the test module by starting it with ``test_`` and end 46it with the name of the module being tested. The test methods in the test module 47should start with ``test_`` and end with a description of what the method is 48testing. This is needed so that the methods are recognized by the test driver as 49test methods. Also, no documentation string for the method should be included. A 50comment (such as ``# Tests function returns only True or False``) should be used 51to provide documentation for test methods. This is done because documentation 52strings get printed out if they exist and thus what test is being run is not 53stated. 54 55A basic boilerplate is often used:: 56 57 import unittest 58 from test import support 59 60 class MyTestCase1(unittest.TestCase): 61 62 # Only use setUp() and tearDown() if necessary 63 64 def setUp(self): 65 ... code to execute in preparation for tests ... 66 67 def tearDown(self): 68 ... code to execute to clean up after tests ... 69 70 def test_feature_one(self): 71 # Test feature one. 72 ... testing code ... 73 74 def test_feature_two(self): 75 # Test feature two. 76 ... testing code ... 77 78 ... more test methods ... 79 80 class MyTestCase2(unittest.TestCase): 81 ... same structure as MyTestCase1 ... 82 83 ... more test classes ... 84 85 if __name__ == '__main__': 86 unittest.main() 87 88This code pattern allows the testing suite to be run by :mod:`test.regrtest`, 89on its own as a script that supports the :mod:`unittest` CLI, or via the 90``python -m unittest`` CLI. 91 92The goal for regression testing is to try to break code. This leads to a few 93guidelines to be followed: 94 95* The testing suite should exercise all classes, functions, and constants. This 96 includes not just the external API that is to be presented to the outside 97 world but also "private" code. 98 99* Whitebox testing (examining the code being tested when the tests are being 100 written) is preferred. Blackbox testing (testing only the published user 101 interface) is not complete enough to make sure all boundary and edge cases 102 are tested. 103 104* Make sure all possible values are tested including invalid ones. This makes 105 sure that not only all valid values are acceptable but also that improper 106 values are handled correctly. 107 108* Exhaust as many code paths as possible. Test where branching occurs and thus 109 tailor input to make sure as many different paths through the code are taken. 110 111* Add an explicit test for any bugs discovered for the tested code. This will 112 make sure that the error does not crop up again if the code is changed in the 113 future. 114 115* Make sure to clean up after your tests (such as close and remove all temporary 116 files). 117 118* If a test is dependent on a specific condition of the operating system then 119 verify the condition already exists before attempting the test. 120 121* Import as few modules as possible and do it as soon as possible. This 122 minimizes external dependencies of tests and also minimizes possible anomalous 123 behavior from side-effects of importing a module. 124 125* Try to maximize code reuse. On occasion, tests will vary by something as small 126 as what type of input is used. Minimize code duplication by subclassing a 127 basic test class with a class that specifies the input:: 128 129 class TestFuncAcceptsSequencesMixin: 130 131 func = mySuperWhammyFunction 132 133 def test_func(self): 134 self.func(self.arg) 135 136 class AcceptLists(TestFuncAcceptsSequencesMixin, unittest.TestCase): 137 arg = [1, 2, 3] 138 139 class AcceptStrings(TestFuncAcceptsSequencesMixin, unittest.TestCase): 140 arg = 'abc' 141 142 class AcceptTuples(TestFuncAcceptsSequencesMixin, unittest.TestCase): 143 arg = (1, 2, 3) 144 145 When using this pattern, remember that all classes that inherit from 146 :class:`unittest.TestCase` are run as tests. The :class:`Mixin` class in the example above 147 does not have any data and so can't be run by itself, thus it does not 148 inherit from :class:`unittest.TestCase`. 149 150 151.. seealso:: 152 153 Test Driven Development 154 A book by Kent Beck on writing tests before code. 155 156 157.. _regrtest: 158 159Running tests using the command-line interface 160---------------------------------------------- 161 162The :mod:`test` package can be run as a script to drive Python's regression 163test suite, thanks to the :option:`-m` option: :program:`python -m test`. Under 164the hood, it uses :mod:`test.regrtest`; the call :program:`python -m 165test.regrtest` used in previous Python versions still works. Running the 166script by itself automatically starts running all regression tests in the 167:mod:`test` package. It does this by finding all modules in the package whose 168name starts with ``test_``, importing them, and executing the function 169:func:`test_main` if present or loading the tests via 170unittest.TestLoader.loadTestsFromModule if ``test_main`` does not exist. The 171names of tests to execute may also be passed to the script. Specifying a single 172regression test (:program:`python -m test test_spam`) will minimize output and 173only print whether the test passed or failed. 174 175Running :mod:`test` directly allows what resources are available for 176tests to use to be set. You do this by using the ``-u`` command-line 177option. Specifying ``all`` as the value for the ``-u`` option enables all 178possible resources: :program:`python -m test -uall`. 179If all but one resource is desired (a more common case), a 180comma-separated list of resources that are not desired may be listed after 181``all``. The command :program:`python -m test -uall,-audio,-largefile` 182will run :mod:`test` with all resources except the ``audio`` and 183``largefile`` resources. For a list of all resources and more command-line 184options, run :program:`python -m test -h`. 185 186Some other ways to execute the regression tests depend on what platform the 187tests are being executed on. On Unix, you can run :program:`make test` at the 188top-level directory where Python was built. On Windows, 189executing :program:`rt.bat` from your :file:`PCbuild` directory will run all 190regression tests. 191 192 193:mod:`test.support` --- Utilities for the Python test suite 194=========================================================== 195 196.. module:: test.support 197 :synopsis: Support for Python's regression test suite. 198 199 200The :mod:`test.support` module provides support for Python's regression 201test suite. 202 203.. note:: 204 205 :mod:`test.support` is not a public module. It is documented here to help 206 Python developers write tests. The API of this module is subject to change 207 without backwards compatibility concerns between releases. 208 209 210This module defines the following exceptions: 211 212.. exception:: TestFailed 213 214 Exception to be raised when a test fails. This is deprecated in favor of 215 :mod:`unittest`\ -based tests and :class:`unittest.TestCase`'s assertion 216 methods. 217 218 219.. exception:: ResourceDenied 220 221 Subclass of :exc:`unittest.SkipTest`. Raised when a resource (such as a 222 network connection) is not available. Raised by the :func:`requires` 223 function. 224 225 226The :mod:`test.support` module defines the following constants: 227 228.. data:: verbose 229 230 ``True`` when verbose output is enabled. Should be checked when more 231 detailed information is desired about a running test. *verbose* is set by 232 :mod:`test.regrtest`. 233 234 235.. data:: is_jython 236 237 ``True`` if the running interpreter is Jython. 238 239 240.. data:: is_android 241 242 ``True`` if the system is Android. 243 244 245.. data:: unix_shell 246 247 Path for shell if not on Windows; otherwise ``None``. 248 249 250.. data:: LOOPBACK_TIMEOUT 251 252 Timeout in seconds for tests using a network server listening on the network 253 local loopback interface like ``127.0.0.1``. 254 255 The timeout is long enough to prevent test failure: it takes into account 256 that the client and the server can run in different threads or even 257 different processes. 258 259 The timeout should be long enough for :meth:`~socket.socket.connect`, 260 :meth:`~socket.socket.recv` and :meth:`~socket.socket.send` methods of 261 :class:`socket.socket`. 262 263 Its default value is 5 seconds. 264 265 See also :data:`INTERNET_TIMEOUT`. 266 267 268.. data:: INTERNET_TIMEOUT 269 270 Timeout in seconds for network requests going to the internet. 271 272 The timeout is short enough to prevent a test to wait for too long if the 273 internet request is blocked for whatever reason. 274 275 Usually, a timeout using :data:`INTERNET_TIMEOUT` should not mark a test as 276 failed, but skip the test instead: see 277 :func:`~test.support.socket_helper.transient_internet`. 278 279 Its default value is 1 minute. 280 281 See also :data:`LOOPBACK_TIMEOUT`. 282 283 284.. data:: SHORT_TIMEOUT 285 286 Timeout in seconds to mark a test as failed if the test takes "too long". 287 288 The timeout value depends on the regrtest ``--timeout`` command line option. 289 290 If a test using :data:`SHORT_TIMEOUT` starts to fail randomly on slow 291 buildbots, use :data:`LONG_TIMEOUT` instead. 292 293 Its default value is 30 seconds. 294 295 296.. data:: LONG_TIMEOUT 297 298 Timeout in seconds to detect when a test hangs. 299 300 It is long enough to reduce the risk of test failure on the slowest Python 301 buildbots. It should not be used to mark a test as failed if the test takes 302 "too long". The timeout value depends on the regrtest ``--timeout`` command 303 line option. 304 305 Its default value is 5 minutes. 306 307 See also :data:`LOOPBACK_TIMEOUT`, :data:`INTERNET_TIMEOUT` and 308 :data:`SHORT_TIMEOUT`. 309 310 311.. data:: PGO 312 313 Set when tests can be skipped when they are not useful for PGO. 314 315 316.. data:: PIPE_MAX_SIZE 317 318 A constant that is likely larger than the underlying OS pipe buffer size, 319 to make writes blocking. 320 321 322.. data:: SOCK_MAX_SIZE 323 324 A constant that is likely larger than the underlying OS socket buffer size, 325 to make writes blocking. 326 327 328.. data:: TEST_SUPPORT_DIR 329 330 Set to the top level directory that contains :mod:`test.support`. 331 332 333.. data:: TEST_HOME_DIR 334 335 Set to the top level directory for the test package. 336 337 338.. data:: TEST_DATA_DIR 339 340 Set to the ``data`` directory within the test package. 341 342 343.. data:: MAX_Py_ssize_t 344 345 Set to :data:`sys.maxsize` for big memory tests. 346 347 348.. data:: max_memuse 349 350 Set by :func:`set_memlimit` as the memory limit for big memory tests. 351 Limited by :data:`MAX_Py_ssize_t`. 352 353 354.. data:: real_max_memuse 355 356 Set by :func:`set_memlimit` as the memory limit for big memory tests. Not 357 limited by :data:`MAX_Py_ssize_t`. 358 359 360.. data:: MISSING_C_DOCSTRINGS 361 362 Return ``True`` if running on CPython, not on Windows, and configuration 363 not set with ``WITH_DOC_STRINGS``. 364 365 366.. data:: HAVE_DOCSTRINGS 367 368 Check for presence of docstrings. 369 370 371.. data:: TEST_HTTP_URL 372 373 Define the URL of a dedicated HTTP server for the network tests. 374 375 376.. data:: ALWAYS_EQ 377 378 Object that is equal to anything. Used to test mixed type comparison. 379 380 381.. data:: NEVER_EQ 382 383 Object that is not equal to anything (even to :data:`ALWAYS_EQ`). 384 Used to test mixed type comparison. 385 386 387.. data:: LARGEST 388 389 Object that is greater than anything (except itself). 390 Used to test mixed type comparison. 391 392 393.. data:: SMALLEST 394 395 Object that is less than anything (except itself). 396 Used to test mixed type comparison. 397 398 399The :mod:`test.support` module defines the following functions: 400 401.. function:: is_resource_enabled(resource) 402 403 Return ``True`` if *resource* is enabled and available. The list of 404 available resources is only set when :mod:`test.regrtest` is executing the 405 tests. 406 407 408.. function:: python_is_optimized() 409 410 Return ``True`` if Python was not built with ``-O0`` or ``-Og``. 411 412 413.. function:: with_pymalloc() 414 415 Return :data:`_testcapi.WITH_PYMALLOC`. 416 417 418.. function:: requires(resource, msg=None) 419 420 Raise :exc:`ResourceDenied` if *resource* is not available. *msg* is the 421 argument to :exc:`ResourceDenied` if it is raised. Always returns 422 ``True`` if called by a function whose ``__name__`` is ``'__main__'``. 423 Used when tests are executed by :mod:`test.regrtest`. 424 425 426.. function:: system_must_validate_cert(f) 427 428 Raise :exc:`unittest.SkipTest` on TLS certification validation failures. 429 430 431.. function:: sortdict(dict) 432 433 Return a repr of *dict* with keys sorted. 434 435 436.. function:: findfile(filename, subdir=None) 437 438 Return the path to the file named *filename*. If no match is found 439 *filename* is returned. This does not equal a failure since it could be the 440 path to the file. 441 442 Setting *subdir* indicates a relative path to use to find the file 443 rather than looking directly in the path directories. 444 445 446.. function:: match_test(test) 447 448 Match *test* to patterns set in :func:`set_match_tests`. 449 450 451.. function:: set_match_tests(patterns) 452 453 Define match test with regular expression *patterns*. 454 455 456.. function:: run_unittest(*classes) 457 458 Execute :class:`unittest.TestCase` subclasses passed to the function. The 459 function scans the classes for methods starting with the prefix ``test_`` 460 and executes the tests individually. 461 462 It is also legal to pass strings as parameters; these should be keys in 463 ``sys.modules``. Each associated module will be scanned by 464 ``unittest.TestLoader.loadTestsFromModule()``. This is usually seen in the 465 following :func:`test_main` function:: 466 467 def test_main(): 468 support.run_unittest(__name__) 469 470 This will run all tests defined in the named module. 471 472 473.. function:: run_doctest(module, verbosity=None, optionflags=0) 474 475 Run :func:`doctest.testmod` on the given *module*. Return 476 ``(failure_count, test_count)``. 477 478 If *verbosity* is ``None``, :func:`doctest.testmod` is run with verbosity 479 set to :data:`verbose`. Otherwise, it is run with verbosity set to 480 ``None``. *optionflags* is passed as ``optionflags`` to 481 :func:`doctest.testmod`. 482 483 484.. function:: setswitchinterval(interval) 485 486 Set the :func:`sys.setswitchinterval` to the given *interval*. Defines 487 a minimum interval for Android systems to prevent the system from hanging. 488 489 490.. function:: check_impl_detail(**guards) 491 492 Use this check to guard CPython's implementation-specific tests or to 493 run them only on the implementations guarded by the arguments:: 494 495 check_impl_detail() # Only on CPython (default). 496 check_impl_detail(jython=True) # Only on Jython. 497 check_impl_detail(cpython=False) # Everywhere except CPython. 498 499 500.. function:: set_memlimit(limit) 501 502 Set the values for :data:`max_memuse` and :data:`real_max_memuse` for big 503 memory tests. 504 505 506.. function:: record_original_stdout(stdout) 507 508 Store the value from *stdout*. It is meant to hold the stdout at the 509 time the regrtest began. 510 511 512.. function:: get_original_stdout 513 514 Return the original stdout set by :func:`record_original_stdout` or 515 ``sys.stdout`` if it's not set. 516 517 518.. function:: args_from_interpreter_flags() 519 520 Return a list of command line arguments reproducing the current settings 521 in ``sys.flags`` and ``sys.warnoptions``. 522 523 524.. function:: optim_args_from_interpreter_flags() 525 526 Return a list of command line arguments reproducing the current 527 optimization settings in ``sys.flags``. 528 529 530.. function:: captured_stdin() 531 captured_stdout() 532 captured_stderr() 533 534 A context managers that temporarily replaces the named stream with 535 :class:`io.StringIO` object. 536 537 Example use with output streams:: 538 539 with captured_stdout() as stdout, captured_stderr() as stderr: 540 print("hello") 541 print("error", file=sys.stderr) 542 assert stdout.getvalue() == "hello\n" 543 assert stderr.getvalue() == "error\n" 544 545 Example use with input stream:: 546 547 with captured_stdin() as stdin: 548 stdin.write('hello\n') 549 stdin.seek(0) 550 # call test code that consumes from sys.stdin 551 captured = input() 552 self.assertEqual(captured, "hello") 553 554 555.. function:: disable_faulthandler() 556 557 A context manager that replaces ``sys.stderr`` with ``sys.__stderr__``. 558 559 560.. function:: gc_collect() 561 562 Force as many objects as possible to be collected. This is needed because 563 timely deallocation is not guaranteed by the garbage collector. This means 564 that ``__del__`` methods may be called later than expected and weakrefs 565 may remain alive for longer than expected. 566 567 568.. function:: disable_gc() 569 570 A context manager that disables the garbage collector upon entry and 571 reenables it upon exit. 572 573 574.. function:: swap_attr(obj, attr, new_val) 575 576 Context manager to swap out an attribute with a new object. 577 578 Usage:: 579 580 with swap_attr(obj, "attr", 5): 581 ... 582 583 This will set ``obj.attr`` to 5 for the duration of the ``with`` block, 584 restoring the old value at the end of the block. If ``attr`` doesn't 585 exist on ``obj``, it will be created and then deleted at the end of the 586 block. 587 588 The old value (or ``None`` if it doesn't exist) will be assigned to the 589 target of the "as" clause, if there is one. 590 591 592.. function:: swap_item(obj, attr, new_val) 593 594 Context manager to swap out an item with a new object. 595 596 Usage:: 597 598 with swap_item(obj, "item", 5): 599 ... 600 601 This will set ``obj["item"]`` to 5 for the duration of the ``with`` block, 602 restoring the old value at the end of the block. If ``item`` doesn't 603 exist on ``obj``, it will be created and then deleted at the end of the 604 block. 605 606 The old value (or ``None`` if it doesn't exist) will be assigned to the 607 target of the "as" clause, if there is one. 608 609 610.. function:: print_warning(msg) 611 612 Print a warning into :data:`sys.__stderr__`. Format the message as: 613 ``f"Warning -- {msg}"``. If *msg* is made of multiple lines, add 614 ``"Warning -- "`` prefix to each line. 615 616 .. versionadded:: 3.9 617 618 619.. function:: wait_process(pid, *, exitcode, timeout=None) 620 621 Wait until process *pid* completes and check that the process exit code is 622 *exitcode*. 623 624 Raise an :exc:`AssertionError` if the process exit code is not equal to 625 *exitcode*. 626 627 If the process runs longer than *timeout* seconds (:data:`SHORT_TIMEOUT` by 628 default), kill the process and raise an :exc:`AssertionError`. The timeout 629 feature is not available on Windows. 630 631 .. versionadded:: 3.9 632 633 634.. function:: calcobjsize(fmt) 635 636 Return :func:`struct.calcsize` for ``nP{fmt}0n`` or, if ``gettotalrefcount`` 637 exists, ``2PnP{fmt}0P``. 638 639 640.. function:: calcvobjsize(fmt) 641 642 Return :func:`struct.calcsize` for ``nPn{fmt}0n`` or, if ``gettotalrefcount`` 643 exists, ``2PnPn{fmt}0P``. 644 645 646.. function:: checksizeof(test, o, size) 647 648 For testcase *test*, assert that the ``sys.getsizeof`` for *o* plus the GC 649 header size equals *size*. 650 651 652.. decorator:: anticipate_failure(condition) 653 654 A decorator to conditionally mark tests with 655 :func:`unittest.expectedFailure`. Any use of this decorator should 656 have an associated comment identifying the relevant tracker issue. 657 658 659.. decorator:: run_with_locale(catstr, *locales) 660 661 A decorator for running a function in a different locale, correctly 662 resetting it after it has finished. *catstr* is the locale category as 663 a string (for example ``"LC_ALL"``). The *locales* passed will be tried 664 sequentially, and the first valid locale will be used. 665 666 667.. decorator:: run_with_tz(tz) 668 669 A decorator for running a function in a specific timezone, correctly 670 resetting it after it has finished. 671 672 673.. decorator:: requires_freebsd_version(*min_version) 674 675 Decorator for the minimum version when running test on FreeBSD. If the 676 FreeBSD version is less than the minimum, raise :exc:`unittest.SkipTest`. 677 678 679.. decorator:: requires_linux_version(*min_version) 680 681 Decorator for the minimum version when running test on Linux. If the 682 Linux version is less than the minimum, raise :exc:`unittest.SkipTest`. 683 684 685.. decorator:: requires_mac_version(*min_version) 686 687 Decorator for the minimum version when running test on macOS. If the 688 macOS version is less than the minimum, raise :exc:`unittest.SkipTest`. 689 690 691.. decorator:: requires_IEEE_754 692 693 Decorator for skipping tests on non-IEEE 754 platforms. 694 695 696.. decorator:: requires_zlib 697 698 Decorator for skipping tests if :mod:`zlib` doesn't exist. 699 700 701.. decorator:: requires_gzip 702 703 Decorator for skipping tests if :mod:`gzip` doesn't exist. 704 705 706.. decorator:: requires_bz2 707 708 Decorator for skipping tests if :mod:`bz2` doesn't exist. 709 710 711.. decorator:: requires_lzma 712 713 Decorator for skipping tests if :mod:`lzma` doesn't exist. 714 715 716.. decorator:: requires_resource(resource) 717 718 Decorator for skipping tests if *resource* is not available. 719 720 721.. decorator:: requires_docstrings 722 723 Decorator for only running the test if :data:`HAVE_DOCSTRINGS`. 724 725 726.. decorator:: cpython_only(test) 727 728 Decorator for tests only applicable to CPython. 729 730 731.. decorator:: impl_detail(msg=None, **guards) 732 733 Decorator for invoking :func:`check_impl_detail` on *guards*. If that 734 returns ``False``, then uses *msg* as the reason for skipping the test. 735 736 737.. decorator:: no_tracing(func) 738 739 Decorator to temporarily turn off tracing for the duration of the test. 740 741 742.. decorator:: refcount_test(test) 743 744 Decorator for tests which involve reference counting. The decorator does 745 not run the test if it is not run by CPython. Any trace function is unset 746 for the duration of the test to prevent unexpected refcounts caused by 747 the trace function. 748 749 750.. decorator:: bigmemtest(size, memuse, dry_run=True) 751 752 Decorator for bigmem tests. 753 754 *size* is a requested size for the test (in arbitrary, test-interpreted 755 units.) *memuse* is the number of bytes per unit for the test, or a good 756 estimate of it. For example, a test that needs two byte buffers, of 4 GiB 757 each, could be decorated with ``@bigmemtest(size=_4G, memuse=2)``. 758 759 The *size* argument is normally passed to the decorated test method as an 760 extra argument. If *dry_run* is ``True``, the value passed to the test 761 method may be less than the requested value. If *dry_run* is ``False``, it 762 means the test doesn't support dummy runs when ``-M`` is not specified. 763 764 765.. decorator:: bigaddrspacetest(f) 766 767 Decorator for tests that fill the address space. *f* is the function to 768 wrap. 769 770 771.. function:: check_syntax_error(testcase, statement, errtext='', *, lineno=None, offset=None) 772 773 Test for syntax errors in *statement* by attempting to compile *statement*. 774 *testcase* is the :mod:`unittest` instance for the test. *errtext* is the 775 regular expression which should match the string representation of the 776 raised :exc:`SyntaxError`. If *lineno* is not ``None``, compares to 777 the line of the exception. If *offset* is not ``None``, compares to 778 the offset of the exception. 779 780 781.. function:: open_urlresource(url, *args, **kw) 782 783 Open *url*. If open fails, raises :exc:`TestFailed`. 784 785 786.. function:: reap_children() 787 788 Use this at the end of ``test_main`` whenever sub-processes are started. 789 This will help ensure that no extra children (zombies) stick around to 790 hog resources and create problems when looking for refleaks. 791 792 793.. function:: get_attribute(obj, name) 794 795 Get an attribute, raising :exc:`unittest.SkipTest` if :exc:`AttributeError` 796 is raised. 797 798 799.. function:: catch_unraisable_exception() 800 801 Context manager catching unraisable exception using 802 :func:`sys.unraisablehook`. 803 804 Storing the exception value (``cm.unraisable.exc_value``) creates a 805 reference cycle. The reference cycle is broken explicitly when the context 806 manager exits. 807 808 Storing the object (``cm.unraisable.object``) can resurrect it if it is set 809 to an object which is being finalized. Exiting the context manager clears 810 the stored object. 811 812 Usage:: 813 814 with support.catch_unraisable_exception() as cm: 815 # code creating an "unraisable exception" 816 ... 817 818 # check the unraisable exception: use cm.unraisable 819 ... 820 821 # cm.unraisable attribute no longer exists at this point 822 # (to break a reference cycle) 823 824 .. versionadded:: 3.8 825 826 827.. function:: load_package_tests(pkg_dir, loader, standard_tests, pattern) 828 829 Generic implementation of the :mod:`unittest` ``load_tests`` protocol for 830 use in test packages. *pkg_dir* is the root directory of the package; 831 *loader*, *standard_tests*, and *pattern* are the arguments expected by 832 ``load_tests``. In simple cases, the test package's ``__init__.py`` 833 can be the following:: 834 835 import os 836 from test.support import load_package_tests 837 838 def load_tests(*args): 839 return load_package_tests(os.path.dirname(__file__), *args) 840 841 842.. function:: detect_api_mismatch(ref_api, other_api, *, ignore=()) 843 844 Returns the set of attributes, functions or methods of *ref_api* not 845 found on *other_api*, except for a defined list of items to be 846 ignored in this check specified in *ignore*. 847 848 By default this skips private attributes beginning with '_' but 849 includes all magic methods, i.e. those starting and ending in '__'. 850 851 .. versionadded:: 3.5 852 853 854.. function:: patch(test_instance, object_to_patch, attr_name, new_value) 855 856 Override *object_to_patch.attr_name* with *new_value*. Also add 857 cleanup procedure to *test_instance* to restore *object_to_patch* for 858 *attr_name*. The *attr_name* should be a valid attribute for 859 *object_to_patch*. 860 861 862.. function:: run_in_subinterp(code) 863 864 Run *code* in subinterpreter. Raise :exc:`unittest.SkipTest` if 865 :mod:`tracemalloc` is enabled. 866 867 868.. function:: check_free_after_iterating(test, iter, cls, args=()) 869 870 Assert that *iter* is deallocated after iterating. 871 872 873.. function:: missing_compiler_executable(cmd_names=[]) 874 875 Check for the existence of the compiler executables whose names are listed 876 in *cmd_names* or all the compiler executables when *cmd_names* is empty 877 and return the first missing executable or ``None`` when none is found 878 missing. 879 880 881.. function:: check__all__(test_case, module, name_of_module=None, extra=(), not_exported=()) 882 883 Assert that the ``__all__`` variable of *module* contains all public names. 884 885 The module's public names (its API) are detected automatically 886 based on whether they match the public name convention and were defined in 887 *module*. 888 889 The *name_of_module* argument can specify (as a string or tuple thereof) what 890 module(s) an API could be defined in order to be detected as a public 891 API. One case for this is when *module* imports part of its public API from 892 other modules, possibly a C backend (like ``csv`` and its ``_csv``). 893 894 The *extra* argument can be a set of names that wouldn't otherwise be automatically 895 detected as "public", like objects without a proper ``__module__`` 896 attribute. If provided, it will be added to the automatically detected ones. 897 898 The *not_exported* argument can be a set of names that must not be treated 899 as part of the public API even though their names indicate otherwise. 900 901 Example use:: 902 903 import bar 904 import foo 905 import unittest 906 from test import support 907 908 class MiscTestCase(unittest.TestCase): 909 def test__all__(self): 910 support.check__all__(self, foo) 911 912 class OtherTestCase(unittest.TestCase): 913 def test__all__(self): 914 extra = {'BAR_CONST', 'FOO_CONST'} 915 not_exported = {'baz'} # Undocumented name. 916 # bar imports part of its API from _bar. 917 support.check__all__(self, bar, ('bar', '_bar'), 918 extra=extra, not_exported=not_exported) 919 920 .. versionadded:: 3.6 921 922.. function:: skip_if_broken_multiprocessing_synchronize() 923 924 Skip tests if the :mod:`multiprocessing.synchronize` module is missing, if 925 there is no available semaphore implementation, or if creating a lock raises 926 an :exc:`OSError`. 927 928 .. versionadded:: 3.10 929 930 931.. function:: check_disallow_instantiation(test_case, tp, *args, **kwds) 932 933 Assert that type *tp* cannot be instantiated using *args* and *kwds*. 934 935 .. versionadded:: 3.10 936 937 938.. function:: adjust_int_max_str_digits(max_digits) 939 940 This function returns a context manager that will change the global 941 :func:`sys.set_int_max_str_digits` setting for the duration of the 942 context to allow execution of test code that needs a different limit 943 on the number of digits when converting between an integer and string. 944 945 .. versionadded:: 3.10.7 946 947 948The :mod:`test.support` module defines the following classes: 949 950 951.. class:: SuppressCrashReport() 952 953 A context manager used to try to prevent crash dialog popups on tests that 954 are expected to crash a subprocess. 955 956 On Windows, it disables Windows Error Reporting dialogs using 957 `SetErrorMode <https://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx>`_. 958 959 On UNIX, :func:`resource.setrlimit` is used to set 960 :attr:`resource.RLIMIT_CORE`'s soft limit to 0 to prevent coredump file 961 creation. 962 963 On both platforms, the old value is restored by :meth:`__exit__`. 964 965 966.. class:: SaveSignals() 967 968 Class to save and restore signal handlers registered by the Python signal 969 handler. 970 971 972.. class:: Matcher() 973 974 .. method:: matches(self, d, **kwargs) 975 976 Try to match a single dict with the supplied arguments. 977 978 979 .. method:: match_value(self, k, dv, v) 980 981 Try to match a single stored value (*dv*) with a supplied value (*v*). 982 983 984.. class:: BasicTestRunner() 985 986 .. method:: run(test) 987 988 Run *test* and return the result. 989 990 991:mod:`test.support.socket_helper` --- Utilities for socket tests 992================================================================ 993 994.. module:: test.support.socket_helper 995 :synopsis: Support for socket tests. 996 997 998The :mod:`test.support.socket_helper` module provides support for socket tests. 999 1000.. versionadded:: 3.9 1001 1002 1003.. data:: IPV6_ENABLED 1004 1005 Set to ``True`` if IPv6 is enabled on this host, ``False`` otherwise. 1006 1007 1008.. function:: find_unused_port(family=socket.AF_INET, socktype=socket.SOCK_STREAM) 1009 1010 Returns an unused port that should be suitable for binding. This is 1011 achieved by creating a temporary socket with the same family and type as 1012 the ``sock`` parameter (default is :const:`~socket.AF_INET`, 1013 :const:`~socket.SOCK_STREAM`), 1014 and binding it to the specified host address (defaults to ``0.0.0.0``) 1015 with the port set to 0, eliciting an unused ephemeral port from the OS. 1016 The temporary socket is then closed and deleted, and the ephemeral port is 1017 returned. 1018 1019 Either this method or :func:`bind_port` should be used for any tests 1020 where a server socket needs to be bound to a particular port for the 1021 duration of the test. 1022 Which one to use depends on whether the calling code is creating a Python 1023 socket, or if an unused port needs to be provided in a constructor 1024 or passed to an external program (i.e. the ``-accept`` argument to 1025 openssl's s_server mode). Always prefer :func:`bind_port` over 1026 :func:`find_unused_port` where possible. Using a hard coded port is 1027 discouraged since it can make multiple instances of the test impossible to 1028 run simultaneously, which is a problem for buildbots. 1029 1030 1031.. function:: bind_port(sock, host=HOST) 1032 1033 Bind the socket to a free port and return the port number. Relies on 1034 ephemeral ports in order to ensure we are using an unbound port. This is 1035 important as many tests may be running simultaneously, especially in a 1036 buildbot environment. This method raises an exception if the 1037 ``sock.family`` is :const:`~socket.AF_INET` and ``sock.type`` is 1038 :const:`~socket.SOCK_STREAM`, and the socket has 1039 :const:`~socket.SO_REUSEADDR` or :const:`~socket.SO_REUSEPORT` set on it. 1040 Tests should never set these socket options for TCP/IP sockets. 1041 The only case for setting these options is testing multicasting via 1042 multiple UDP sockets. 1043 1044 Additionally, if the :const:`~socket.SO_EXCLUSIVEADDRUSE` socket option is 1045 available (i.e. on Windows), it will be set on the socket. This will 1046 prevent anyone else from binding to our host/port for the duration of the 1047 test. 1048 1049 1050.. function:: bind_unix_socket(sock, addr) 1051 1052 Bind a unix socket, raising :exc:`unittest.SkipTest` if 1053 :exc:`PermissionError` is raised. 1054 1055 1056.. decorator:: skip_unless_bind_unix_socket 1057 1058 A decorator for running tests that require a functional ``bind()`` for Unix 1059 sockets. 1060 1061 1062.. function:: transient_internet(resource_name, *, timeout=30.0, errnos=()) 1063 1064 A context manager that raises :exc:`~test.support.ResourceDenied` when 1065 various issues with the internet connection manifest themselves as 1066 exceptions. 1067 1068 1069:mod:`test.support.script_helper` --- Utilities for the Python execution tests 1070============================================================================== 1071 1072.. module:: test.support.script_helper 1073 :synopsis: Support for Python's script execution tests. 1074 1075 1076The :mod:`test.support.script_helper` module provides support for Python's 1077script execution tests. 1078 1079.. function:: interpreter_requires_environment() 1080 1081 Return ``True`` if ``sys.executable interpreter`` requires environment 1082 variables in order to be able to run at all. 1083 1084 This is designed to be used with ``@unittest.skipIf()`` to annotate tests 1085 that need to use an ``assert_python*()`` function to launch an isolated 1086 mode (``-I``) or no environment mode (``-E``) sub-interpreter process. 1087 1088 A normal build & test does not run into this situation but it can happen 1089 when trying to run the standard library test suite from an interpreter that 1090 doesn't have an obvious home with Python's current home finding logic. 1091 1092 Setting :envvar:`PYTHONHOME` is one way to get most of the testsuite to run 1093 in that situation. :envvar:`PYTHONPATH` or :envvar:`PYTHONUSERSITE` are 1094 other common environment variables that might impact whether or not the 1095 interpreter can start. 1096 1097 1098.. function:: run_python_until_end(*args, **env_vars) 1099 1100 Set up the environment based on *env_vars* for running the interpreter 1101 in a subprocess. The values can include ``__isolated``, ``__cleanenv``, 1102 ``__cwd``, and ``TERM``. 1103 1104 .. versionchanged:: 3.9 1105 The function no longer strips whitespaces from *stderr*. 1106 1107 1108.. function:: assert_python_ok(*args, **env_vars) 1109 1110 Assert that running the interpreter with *args* and optional environment 1111 variables *env_vars* succeeds (``rc == 0``) and return a ``(return code, 1112 stdout, stderr)`` tuple. 1113 1114 If the ``__cleanenv`` keyword is set, *env_vars* is used as a fresh 1115 environment. 1116 1117 Python is started in isolated mode (command line option ``-I``), 1118 except if the ``__isolated`` keyword is set to ``False``. 1119 1120 .. versionchanged:: 3.9 1121 The function no longer strips whitespaces from *stderr*. 1122 1123 1124.. function:: assert_python_failure(*args, **env_vars) 1125 1126 Assert that running the interpreter with *args* and optional environment 1127 variables *env_vars* fails (``rc != 0``) and return a ``(return code, 1128 stdout, stderr)`` tuple. 1129 1130 See :func:`assert_python_ok` for more options. 1131 1132 .. versionchanged:: 3.9 1133 The function no longer strips whitespaces from *stderr*. 1134 1135 1136.. function:: spawn_python(*args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, **kw) 1137 1138 Run a Python subprocess with the given arguments. 1139 1140 *kw* is extra keyword args to pass to :func:`subprocess.Popen`. Returns a 1141 :class:`subprocess.Popen` object. 1142 1143 1144.. function:: kill_python(p) 1145 1146 Run the given :class:`subprocess.Popen` process until completion and return 1147 stdout. 1148 1149 1150.. function:: make_script(script_dir, script_basename, source, omit_suffix=False) 1151 1152 Create script containing *source* in path *script_dir* and *script_basename*. 1153 If *omit_suffix* is ``False``, append ``.py`` to the name. Return the full 1154 script path. 1155 1156 1157.. function:: make_zip_script(zip_dir, zip_basename, script_name, name_in_zip=None) 1158 1159 Create zip file at *zip_dir* and *zip_basename* with extension ``zip`` which 1160 contains the files in *script_name*. *name_in_zip* is the archive name. 1161 Return a tuple containing ``(full path, full path of archive name)``. 1162 1163 1164.. function:: make_pkg(pkg_dir, init_source='') 1165 1166 Create a directory named *pkg_dir* containing an ``__init__`` file with 1167 *init_source* as its contents. 1168 1169 1170.. function:: make_zip_pkg(zip_dir, zip_basename, pkg_name, script_basename, \ 1171 source, depth=1, compiled=False) 1172 1173 Create a zip package directory with a path of *zip_dir* and *zip_basename* 1174 containing an empty ``__init__`` file and a file *script_basename* 1175 containing the *source*. If *compiled* is ``True``, both source files will 1176 be compiled and added to the zip package. Return a tuple of the full zip 1177 path and the archive name for the zip file. 1178 1179 1180:mod:`test.support.bytecode_helper` --- Support tools for testing correct bytecode generation 1181============================================================================================= 1182 1183.. module:: test.support.bytecode_helper 1184 :synopsis: Support tools for testing correct bytecode generation. 1185 1186The :mod:`test.support.bytecode_helper` module provides support for testing 1187and inspecting bytecode generation. 1188 1189.. versionadded:: 3.9 1190 1191The module defines the following class: 1192 1193.. class:: BytecodeTestCase(unittest.TestCase) 1194 1195 This class has custom assertion methods for inspecting bytecode. 1196 1197.. method:: BytecodeTestCase.get_disassembly_as_string(co) 1198 1199 Return the disassembly of *co* as string. 1200 1201 1202.. method:: BytecodeTestCase.assertInBytecode(x, opname, argval=_UNSPECIFIED) 1203 1204 Return instr if *opname* is found, otherwise throws :exc:`AssertionError`. 1205 1206 1207.. method:: BytecodeTestCase.assertNotInBytecode(x, opname, argval=_UNSPECIFIED) 1208 1209 Throws :exc:`AssertionError` if *opname* is found. 1210 1211 1212:mod:`test.support.threading_helper` --- Utilities for threading tests 1213====================================================================== 1214 1215.. module:: test.support.threading_helper 1216 :synopsis: Support for threading tests. 1217 1218The :mod:`test.support.threading_helper` module provides support for threading tests. 1219 1220.. versionadded:: 3.10 1221 1222 1223.. function:: join_thread(thread, timeout=None) 1224 1225 Join a *thread* within *timeout*. Raise an :exc:`AssertionError` if thread 1226 is still alive after *timeout* seconds. 1227 1228 1229.. decorator:: reap_threads(func) 1230 1231 Decorator to ensure the threads are cleaned up even if the test fails. 1232 1233 1234.. function:: start_threads(threads, unlock=None) 1235 1236 Context manager to start *threads*. It attempts to join the threads upon 1237 exit. 1238 1239 1240.. function:: threading_cleanup(*original_values) 1241 1242 Cleanup up threads not specified in *original_values*. Designed to emit 1243 a warning if a test leaves running threads in the background. 1244 1245 1246.. function:: threading_setup() 1247 1248 Return current thread count and copy of dangling threads. 1249 1250 1251.. function:: wait_threads_exit(timeout=None) 1252 1253 Context manager to wait until all threads created in the ``with`` statement 1254 exit. 1255 1256 1257.. function:: catch_threading_exception() 1258 1259 Context manager catching :class:`threading.Thread` exception using 1260 :func:`threading.excepthook`. 1261 1262 Attributes set when an exception is caught: 1263 1264 * ``exc_type`` 1265 * ``exc_value`` 1266 * ``exc_traceback`` 1267 * ``thread`` 1268 1269 See :func:`threading.excepthook` documentation. 1270 1271 These attributes are deleted at the context manager exit. 1272 1273 Usage:: 1274 1275 with threading_helper.catch_threading_exception() as cm: 1276 # code spawning a thread which raises an exception 1277 ... 1278 1279 # check the thread exception, use cm attributes: 1280 # exc_type, exc_value, exc_traceback, thread 1281 ... 1282 1283 # exc_type, exc_value, exc_traceback, thread attributes of cm no longer 1284 # exists at this point 1285 # (to avoid reference cycles) 1286 1287 .. versionadded:: 3.8 1288 1289 1290:mod:`test.support.os_helper` --- Utilities for os tests 1291======================================================================== 1292 1293.. module:: test.support.os_helper 1294 :synopsis: Support for os tests. 1295 1296The :mod:`test.support.os_helper` module provides support for os tests. 1297 1298.. versionadded:: 3.10 1299 1300 1301.. data:: FS_NONASCII 1302 1303 A non-ASCII character encodable by :func:`os.fsencode`. 1304 1305 1306.. data:: SAVEDCWD 1307 1308 Set to :func:`os.getcwd`. 1309 1310 1311.. data:: TESTFN 1312 1313 Set to a name that is safe to use as the name of a temporary file. Any 1314 temporary file that is created should be closed and unlinked (removed). 1315 1316 1317.. data:: TESTFN_NONASCII 1318 1319 Set to a filename containing the :data:`FS_NONASCII` character. 1320 1321 1322.. data:: TESTFN_UNENCODABLE 1323 1324 Set to a filename (str type) that should not be able to be encoded by file 1325 system encoding in strict mode. It may be ``None`` if it's not possible to 1326 generate such a filename. 1327 1328 1329.. data:: TESTFN_UNDECODABLE 1330 1331 Set to a filename (bytes type) that should not be able to be decoded by 1332 file system encoding in strict mode. It may be ``None`` if it's not 1333 possible to generate such a filename. 1334 1335 1336.. data:: TESTFN_UNICODE 1337 1338 Set to a non-ASCII name for a temporary file. 1339 1340 1341.. class:: EnvironmentVarGuard() 1342 1343 Class used to temporarily set or unset environment variables. Instances can 1344 be used as a context manager and have a complete dictionary interface for 1345 querying/modifying the underlying ``os.environ``. After exit from the 1346 context manager all changes to environment variables done through this 1347 instance will be rolled back. 1348 1349 .. versionchanged:: 3.1 1350 Added dictionary interface. 1351 1352 1353.. class:: FakePath(path) 1354 1355 Simple :term:`path-like object`. It implements the :meth:`__fspath__` 1356 method which just returns the *path* argument. If *path* is an exception, 1357 it will be raised in :meth:`!__fspath__`. 1358 1359 1360.. method:: EnvironmentVarGuard.set(envvar, value) 1361 1362 Temporarily set the environment variable ``envvar`` to the value of 1363 ``value``. 1364 1365 1366.. method:: EnvironmentVarGuard.unset(envvar) 1367 1368 Temporarily unset the environment variable ``envvar``. 1369 1370 1371.. function:: can_symlink() 1372 1373 Return ``True`` if the OS supports symbolic links, ``False`` 1374 otherwise. 1375 1376 1377.. function:: can_xattr() 1378 1379 Return ``True`` if the OS supports xattr, ``False`` 1380 otherwise. 1381 1382 1383.. function:: change_cwd(path, quiet=False) 1384 1385 A context manager that temporarily changes the current working 1386 directory to *path* and yields the directory. 1387 1388 If *quiet* is ``False``, the context manager raises an exception 1389 on error. Otherwise, it issues only a warning and keeps the current 1390 working directory the same. 1391 1392 1393.. function:: create_empty_file(filename) 1394 1395 Create an empty file with *filename*. If it already exists, truncate it. 1396 1397 1398.. function:: fd_count() 1399 1400 Count the number of open file descriptors. 1401 1402 1403.. function:: fs_is_case_insensitive(directory) 1404 1405 Return ``True`` if the file system for *directory* is case-insensitive. 1406 1407 1408.. function:: make_bad_fd() 1409 1410 Create an invalid file descriptor by opening and closing a temporary file, 1411 and returning its descriptor. 1412 1413 1414.. function:: rmdir(filename) 1415 1416 Call :func:`os.rmdir` on *filename*. On Windows platforms, this is 1417 wrapped with a wait loop that checks for the existence of the file. 1418 1419 1420.. function:: rmtree(path) 1421 1422 Call :func:`shutil.rmtree` on *path* or call :func:`os.lstat` and 1423 :func:`os.rmdir` to remove a path and its contents. On Windows platforms, 1424 this is wrapped with a wait loop that checks for the existence of the files. 1425 1426 1427.. decorator:: skip_unless_symlink 1428 1429 A decorator for running tests that require support for symbolic links. 1430 1431 1432.. decorator:: skip_unless_xattr 1433 1434 A decorator for running tests that require support for xattr. 1435 1436 1437.. function:: temp_cwd(name='tempcwd', quiet=False) 1438 1439 A context manager that temporarily creates a new directory and 1440 changes the current working directory (CWD). 1441 1442 The context manager creates a temporary directory in the current 1443 directory with name *name* before temporarily changing the current 1444 working directory. If *name* is ``None``, the temporary directory is 1445 created using :func:`tempfile.mkdtemp`. 1446 1447 If *quiet* is ``False`` and it is not possible to create or change 1448 the CWD, an error is raised. Otherwise, only a warning is raised 1449 and the original CWD is used. 1450 1451 1452.. function:: temp_dir(path=None, quiet=False) 1453 1454 A context manager that creates a temporary directory at *path* and 1455 yields the directory. 1456 1457 If *path* is ``None``, the temporary directory is created using 1458 :func:`tempfile.mkdtemp`. If *quiet* is ``False``, the context manager 1459 raises an exception on error. Otherwise, if *path* is specified and 1460 cannot be created, only a warning is issued. 1461 1462 1463.. function:: temp_umask(umask) 1464 1465 A context manager that temporarily sets the process umask. 1466 1467 1468.. function:: unlink(filename) 1469 1470 Call :func:`os.unlink` on *filename*. On Windows platforms, this is 1471 wrapped with a wait loop that checks for the existence of the file. 1472 1473 1474:mod:`test.support.import_helper` --- Utilities for import tests 1475================================================================ 1476 1477.. module:: test.support.import_helper 1478 :synopsis: Support for import tests. 1479 1480The :mod:`test.support.import_helper` module provides support for import tests. 1481 1482.. versionadded:: 3.10 1483 1484 1485.. function:: forget(module_name) 1486 1487 Remove the module named *module_name* from ``sys.modules`` and delete any 1488 byte-compiled files of the module. 1489 1490 1491.. function:: import_fresh_module(name, fresh=(), blocked=(), deprecated=False) 1492 1493 This function imports and returns a fresh copy of the named Python module 1494 by removing the named module from ``sys.modules`` before doing the import. 1495 Note that unlike :func:`reload`, the original module is not affected by 1496 this operation. 1497 1498 *fresh* is an iterable of additional module names that are also removed 1499 from the ``sys.modules`` cache before doing the import. 1500 1501 *blocked* is an iterable of module names that are replaced with ``None`` 1502 in the module cache during the import to ensure that attempts to import 1503 them raise :exc:`ImportError`. 1504 1505 The named module and any modules named in the *fresh* and *blocked* 1506 parameters are saved before starting the import and then reinserted into 1507 ``sys.modules`` when the fresh import is complete. 1508 1509 Module and package deprecation messages are suppressed during this import 1510 if *deprecated* is ``True``. 1511 1512 This function will raise :exc:`ImportError` if the named module cannot be 1513 imported. 1514 1515 Example use:: 1516 1517 # Get copies of the warnings module for testing without affecting the 1518 # version being used by the rest of the test suite. One copy uses the 1519 # C implementation, the other is forced to use the pure Python fallback 1520 # implementation 1521 py_warnings = import_fresh_module('warnings', blocked=['_warnings']) 1522 c_warnings = import_fresh_module('warnings', fresh=['_warnings']) 1523 1524 .. versionadded:: 3.1 1525 1526 1527.. function:: import_module(name, deprecated=False, *, required_on()) 1528 1529 This function imports and returns the named module. Unlike a normal 1530 import, this function raises :exc:`unittest.SkipTest` if the module 1531 cannot be imported. 1532 1533 Module and package deprecation messages are suppressed during this import 1534 if *deprecated* is ``True``. If a module is required on a platform but 1535 optional for others, set *required_on* to an iterable of platform prefixes 1536 which will be compared against :data:`sys.platform`. 1537 1538 .. versionadded:: 3.1 1539 1540 1541.. function:: modules_setup() 1542 1543 Return a copy of :data:`sys.modules`. 1544 1545 1546.. function:: modules_cleanup(oldmodules) 1547 1548 Remove modules except for *oldmodules* and ``encodings`` in order to 1549 preserve internal cache. 1550 1551 1552.. function:: unload(name) 1553 1554 Delete *name* from ``sys.modules``. 1555 1556 1557.. function:: make_legacy_pyc(source) 1558 1559 Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and return the file 1560 system path to the legacy pyc file. The *source* value is the file system 1561 path to the source file. It does not need to exist, however the PEP 1562 3147/488 pyc file must exist. 1563 1564 1565.. class:: CleanImport(*module_names) 1566 1567 A context manager to force import to return a new module reference. This 1568 is useful for testing module-level behaviors, such as the emission of a 1569 DeprecationWarning on import. Example usage:: 1570 1571 with CleanImport('foo'): 1572 importlib.import_module('foo') # New reference. 1573 1574 1575.. class:: DirsOnSysPath(*paths) 1576 1577 A context manager to temporarily add directories to sys.path. 1578 1579 This makes a copy of :data:`sys.path`, appends any directories given 1580 as positional arguments, then reverts :data:`sys.path` to the copied 1581 settings when the context ends. 1582 1583 Note that *all* :data:`sys.path` modifications in the body of the 1584 context manager, including replacement of the object, 1585 will be reverted at the end of the block. 1586 1587 1588:mod:`test.support.warnings_helper` --- Utilities for warnings tests 1589==================================================================== 1590 1591.. module:: test.support.warnings_helper 1592 :synopsis: Support for warnings tests. 1593 1594The :mod:`test.support.warnings_helper` module provides support for warnings tests. 1595 1596.. versionadded:: 3.10 1597 1598 1599.. function:: check_no_resource_warning(testcase) 1600 1601 Context manager to check that no :exc:`ResourceWarning` was raised. You 1602 must remove the object which may emit :exc:`ResourceWarning` before the 1603 end of the context manager. 1604 1605 1606.. function:: check_syntax_warning(testcase, statement, errtext='', *, lineno=1, offset=None) 1607 1608 Test for syntax warning in *statement* by attempting to compile *statement*. 1609 Test also that the :exc:`SyntaxWarning` is emitted only once, and that it 1610 will be converted to a :exc:`SyntaxError` when turned into error. 1611 *testcase* is the :mod:`unittest` instance for the test. *errtext* is the 1612 regular expression which should match the string representation of the 1613 emitted :exc:`SyntaxWarning` and raised :exc:`SyntaxError`. If *lineno* 1614 is not ``None``, compares to the line of the warning and exception. 1615 If *offset* is not ``None``, compares to the offset of the exception. 1616 1617 .. versionadded:: 3.8 1618 1619 1620.. function:: check_warnings(*filters, quiet=True) 1621 1622 A convenience wrapper for :func:`warnings.catch_warnings()` that makes it 1623 easier to test that a warning was correctly raised. It is approximately 1624 equivalent to calling ``warnings.catch_warnings(record=True)`` with 1625 :meth:`warnings.simplefilter` set to ``always`` and with the option to 1626 automatically validate the results that are recorded. 1627 1628 ``check_warnings`` accepts 2-tuples of the form ``("message regexp", 1629 WarningCategory)`` as positional arguments. If one or more *filters* are 1630 provided, or if the optional keyword argument *quiet* is ``False``, 1631 it checks to make sure the warnings are as expected: each specified filter 1632 must match at least one of the warnings raised by the enclosed code or the 1633 test fails, and if any warnings are raised that do not match any of the 1634 specified filters the test fails. To disable the first of these checks, 1635 set *quiet* to ``True``. 1636 1637 If no arguments are specified, it defaults to:: 1638 1639 check_warnings(("", Warning), quiet=True) 1640 1641 In this case all warnings are caught and no errors are raised. 1642 1643 On entry to the context manager, a :class:`WarningRecorder` instance is 1644 returned. The underlying warnings list from 1645 :func:`~warnings.catch_warnings` is available via the recorder object's 1646 :attr:`warnings` attribute. As a convenience, the attributes of the object 1647 representing the most recent warning can also be accessed directly through 1648 the recorder object (see example below). If no warning has been raised, 1649 then any of the attributes that would otherwise be expected on an object 1650 representing a warning will return ``None``. 1651 1652 The recorder object also has a :meth:`reset` method, which clears the 1653 warnings list. 1654 1655 The context manager is designed to be used like this:: 1656 1657 with check_warnings(("assertion is always true", SyntaxWarning), 1658 ("", UserWarning)): 1659 exec('assert(False, "Hey!")') 1660 warnings.warn(UserWarning("Hide me!")) 1661 1662 In this case if either warning was not raised, or some other warning was 1663 raised, :func:`check_warnings` would raise an error. 1664 1665 When a test needs to look more deeply into the warnings, rather than 1666 just checking whether or not they occurred, code like this can be used:: 1667 1668 with check_warnings(quiet=True) as w: 1669 warnings.warn("foo") 1670 assert str(w.args[0]) == "foo" 1671 warnings.warn("bar") 1672 assert str(w.args[0]) == "bar" 1673 assert str(w.warnings[0].args[0]) == "foo" 1674 assert str(w.warnings[1].args[0]) == "bar" 1675 w.reset() 1676 assert len(w.warnings) == 0 1677 1678 1679 Here all warnings will be caught, and the test code tests the captured 1680 warnings directly. 1681 1682 .. versionchanged:: 3.2 1683 New optional arguments *filters* and *quiet*. 1684 1685 1686.. class:: WarningsRecorder() 1687 1688 Class used to record warnings for unit tests. See documentation of 1689 :func:`check_warnings` above for more details. 1690