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