Lines Matching +full:module +full:- +full:path +full:- +full:tests
1 :mod:`test` --- Regression tests package for Python
4 .. module:: test
5 :synopsis: Regression tests package containing the testing suite for Python.
16 --------------
18 The :mod:`test` package contains all regression tests for Python as well as the
20 :mod:`test.support` is used to enhance your tests while
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
32 Module :mod:`unittest`
33 Writing PyUnit regression tests.
35 Module :mod:`doctest`
36 Tests embedded in documentation strings.
39 .. _writing-tests:
41 Writing Unit Tests for the :mod:`test` package
42 ----------------------------------------------
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
50 comment (such as ``# Tests function returns only True or False``) should be used
65 ... code to execute in preparation for tests ...
68 ... code to execute to clean up after tests ...
90 ``python -m unittest`` CLI.
99 * Whitebox testing (examining the code being tested when the tests are being
115 * Make sure to clean up after your tests (such as close and remove all temporary
122 minimizes external dependencies of tests and also minimizes possible anomalous
123 behavior from side-effects of importing a module.
125 * Try to maximize code reuse. On occasion, tests will vary by something as small
146 :class:`unittest.TestCase` are run as tests. The :class:`Mixin` class in the example above
154 A book by Kent Beck on writing tests before code.
159 Running tests using the command-line interface
160 ----------------------------------------------
163 test suite, thanks to the :option:`-m` option: :program:`python -m test`. Under
164 the hood, it uses :mod:`test.regrtest`; the call :program:`python -m
166 script by itself automatically starts running all regression tests in the
169 :func:`test_main` if present or loading the tests via
171 names of tests to execute may also be passed to the script. Specifying a single
172 regression test (:program:`python -m test test_spam`) will minimize output and
176 tests to use to be set. You do this by using the ``-u`` command-line
177 option. Specifying ``all`` as the value for the ``-u`` option enables all
178 possible resources: :program:`python -m test -uall`.
180 comma-separated list of resources that are not desired may be listed after
181 ``all``. The command :program:`python -m test -uall,-audio,-largefile`
183 ``largefile`` resources. For a list of all resources and more command-line
184 options, run :program:`python -m test -h`.
186 Some other ways to execute the regression tests depend on what platform the
187 tests are being executed on. On Unix, you can run :program:`make test` at the
188 top-level directory where Python was built. On Windows,
190 regression tests.
193 :mod:`test.support` --- Utilities for the Python test suite
196 .. module:: test.support
200 The :mod:`test.support` module provides support for Python's regression
205 :mod:`test.support` is not a public module. It is documented here to help
206 Python developers write tests. The API of this module is subject to change
210 This module defines the following exceptions:
215 :mod:`unittest`\ -based tests and :class:`unittest.TestCase`'s assertion
226 The :mod:`test.support` module defines the following constants:
247 Path for shell if not on Windows; otherwise ``None``.
252 Timeout in seconds for tests using a network server listening on the network
288 The timeout value depends on the regrtest ``--timeout`` command line option.
302 "too long". The timeout value depends on the regrtest ``--timeout`` command
313 Set when tests can be skipped when they are not useful for PGO.
345 Set to :data:`sys.maxsize` for big memory tests.
350 Set by :func:`set_memlimit` as the memory limit for big memory tests.
356 Set by :func:`set_memlimit` as the memory limit for big memory tests. Not
364 See the :option:`configure --without-doc-strings <--without-doc-strings>` option.
372 …See the :option:`python -OO <-O>` option, which strips docstrings of functions implemented in Pyth…
379 Define the URL of a dedicated HTTP server for the network tests.
405 The :mod:`test.support` module defines the following functions:
411 tests.
416 Return ``True`` if Python was not built with ``-O0`` or ``-Og``.
429 Used when tests are executed by :mod:`test.regrtest`.
439 Return the path to the file named *filename*. If no match is found
441 path to the file.
443 Setting *subdir* indicates a relative path to use to find the file
444 rather than looking directly in the path directories.
454 Define match patterns on test filenames and test method names for filtering tests.
461 and executes the tests individually.
464 ``sys.modules``. Each associated module will be scanned by
471 This will run all tests defined in the named module.
474 .. function:: run_doctest(module, verbosity=None, optionflags=0)
476 Run :func:`doctest.testmod` on the given *module*. Return
493 Use this check to guard CPython's implementation-specific tests or to
506 memory tests.
625 ``f"Warning -- {msg}"``. If *msg* is made of multiple lines, add
626 ``"Warning -- "`` prefix to each line.
666 A decorator to conditionally mark tests with
710 Decorator for skipping tests on non-IEEE 754 platforms.
715 Decorator for skipping tests if :mod:`zlib` doesn't exist.
720 Decorator for skipping tests if :mod:`gzip` doesn't exist.
725 Decorator for skipping tests if :mod:`bz2` doesn't exist.
730 Decorator for skipping tests if :mod:`lzma` doesn't exist.
735 Decorator for skipping tests if *resource* is not available.
745 Decorator for tests only applicable to CPython.
761 Decorator for tests which involve reference counting. The decorator does
769 Decorator for bigmem tests.
771 *size* is a requested size for the test (in arbitrary, test-interpreted
779 means the test doesn't support dummy runs when ``-M`` is not specified.
784 Decorator for tests that fill the address space.
804 Use this at the end of ``test_main`` whenever sub-processes are started.
855 return load_package_tests(os.path.dirname(__file__), *args)
897 .. function:: check__all__(test_case, module, name_of_module=None, extra=(), not_exported=())
899 Assert that the ``__all__`` variable of *module* contains all public names.
901 The module's public names (its API) are detected automatically
903 *module*.
906 module(s) an API could be defined in order to be detected as a public
907 API. One case for this is when *module* imports part of its public API from
940 Skip tests if the :mod:`multiprocessing.synchronize` module is missing, if
964 The :mod:`test.support` module defines the following classes:
969 A context manager used to try to prevent crash dialog popups on tests that
973 `SetErrorMode <https://msdn.microsoft.com/en-us/library/windows/desktop/ms680621.aspx>`_.
1017 :mod:`test.support.socket_helper` --- Utilities for socket tests
1020 .. module:: test.support.socket_helper
1021 :synopsis: Support for socket tests.
1024 The :mod:`test.support.socket_helper` module provides support for socket tests.
1045 Either this method or :func:`bind_port` should be used for any tests
1050 or passed to an external program (i.e. the ``-accept`` argument to
1061 important as many tests may be running simultaneously, especially in a
1066 Tests should never set these socket options for TCP/IP sockets.
1084 A decorator for running tests that require a functional ``bind()`` for Unix
1095 :mod:`test.support.script_helper` --- Utilities for the Python execution tests
1098 .. module:: test.support.script_helper
1099 :synopsis: Support for Python's script execution tests.
1102 The :mod:`test.support.script_helper` module provides support for Python's
1103 script execution tests.
1110 This is designed to be used with ``@unittest.skipIf()`` to annotate tests
1112 mode (``-I``) or no environment mode (``-E``) sub-interpreter process.
1140 If the *__cleanenv* keyword-only parameter is set, *env_vars* is used as a fresh
1143 Python is started in isolated mode (command line option ``-I``),
1144 except if the *__isolated* keyword-only parameter is set to ``False``.
1178 Create script containing *source* in path *script_dir* and *script_basename*.
1180 script path.
1187 Return a tuple containing ``(full path, full path of archive name)``.
1199 Create a zip package directory with a path of *zip_dir* and *zip_basename*
1203 path and the archive name for the zip file.
1206 :mod:`test.support.bytecode_helper` --- Support tools for testing correct bytecode generation
1209 .. module:: test.support.bytecode_helper
1212 The :mod:`test.support.bytecode_helper` module provides support for testing
1217 The module defines the following class:
1238 :mod:`test.support.threading_helper` --- Utilities for threading tests
1241 .. module:: test.support.threading_helper
1242 :synopsis: Support for threading tests.
1244 The :mod:`test.support.threading_helper` module provides support for threading tests.
1318 :mod:`test.support.os_helper` --- Utilities for os tests
1321 .. module:: test.support.os_helper
1322 :synopsis: Support for os tests.
1324 The :mod:`test.support.os_helper` module provides support for os tests.
1331 A non-ASCII character encodable by :func:`os.fsencode`.
1349 with the default filesystem encoding. This allows tests that require a
1350 non-ASCII filename to be easily skipped on platforms where they can't work.
1369 Set to a non-ASCII name for a temporary file.
1384 .. class:: FakePath(path)
1386 Simple :term:`path-like object`. It implements the :meth:`__fspath__`
1387 method which just returns the *path* argument. If *path* is an exception,
1414 .. function:: change_cwd(path, quiet=False)
1417 directory to *path* and yields the directory.
1436 Return ``True`` if the file system for *directory* is case-insensitive.
1453 .. function:: rmtree(path)
1455 Call :func:`shutil.rmtree` on *path* or call :func:`os.lstat` and
1456 :func:`os.rmdir` to remove a path and its contents. As with :func:`rmdir`,
1463 A decorator for running tests that require support for symbolic links.
1468 A decorator for running tests that require support for xattr.
1486 .. function:: temp_dir(path=None, quiet=False)
1488 A context manager that creates a temporary directory at *path* and
1491 If *path* is ``None``, the temporary directory is created using
1493 raises an exception on error. Otherwise, if *path* is specified and
1509 :mod:`test.support.import_helper` --- Utilities for import tests
1512 .. module:: test.support.import_helper
1513 :synopsis: Support for import tests.
1515 The :mod:`test.support.import_helper` module provides support for import tests.
1522 Remove the module named *module_name* from ``sys.modules`` and delete any
1523 byte-compiled files of the module.
1528 This function imports and returns a fresh copy of the named Python module
1529 by removing the named module from ``sys.modules`` before doing the import.
1530 Note that unlike :func:`reload`, the original module is not affected by
1533 *fresh* is an iterable of additional module names that are also removed
1536 *blocked* is an iterable of module names that are replaced with ``None``
1537 in the module cache during the import to ensure that attempts to import
1540 The named module and any modules named in the *fresh* and *blocked*
1544 Module and package deprecation messages are suppressed during this import
1547 This function will raise :exc:`ImportError` if the named module cannot be
1552 # Get copies of the warnings module for testing without affecting the
1564 This function imports and returns the named module. Unlike a normal
1565 import, this function raises :exc:`unittest.SkipTest` if the module
1568 Module and package deprecation messages are suppressed during this import
1569 if *deprecated* is ``True``. If a module is required on a platform but
1595 system path to the legacy pyc file. The *source* value is the file system
1596 path to the source file. It does not need to exist, however the PEP
1602 A context manager to force import to return a new module reference. This
1603 is useful for testing module-level behaviors, such as the emission of a
1612 A context manager to temporarily add directories to :data:`sys.path`.
1614 This makes a copy of :data:`sys.path`, appends any directories given
1615 as positional arguments, then reverts :data:`sys.path` to the copied
1618 Note that *all* :data:`sys.path` modifications in the body of the
1623 :mod:`test.support.warnings_helper` --- Utilities for warnings tests
1626 .. module:: test.support.warnings_helper
1627 :synopsis: Support for warnings tests.
1629 The :mod:`test.support.warnings_helper` module provides support for warnings tests.
1678 ``check_warnings`` accepts 2-tuples of the form ``("message regexp",
1729 Here all warnings will be caught, and the test code tests the captured
1738 Class used to record warnings for unit tests. See documentation of