Debian Codegraph @

Doc/library/test.rst

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