Lines Matching +full:tests +full:- +full:debian +full:- +full:minimal
1 :mod:`doctest` --- Test interactive Python examples
9 .. sectionauthor:: Moshe Zadka <moshez@debian.org>
14 --------------
20 * To check that a module's docstrings are up-to-date by verifying that all
27 input-output examples. Depending on whether the examples or the expository text
49 >>> factorial(-1)
91 .. code-block:: shell-session
97 ``-v`` to the script, and :mod:`doctest` prints a detailed log of what
100 .. code-block:: shell-session
102 $ python example.py -v
116 .. code-block:: none
125 2 items passed all tests:
126 1 tests in __main__
127 8 tests in __main__.factorial
128 9 tests in 2 items.
140 .. _doctest-simple-testmod:
143 ---------------------------------------------
164 Run it with the ``-v`` switch instead::
166 python M.py -v
173 ``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not
180 python -m doctest -v example.py
186 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
189 .. _doctest-simple-testfile:
192 ----------------------------------------------
205 .. code-block:: none
211 -------------------
240 See section :ref:`doctest-basic-api` for a description of the optional arguments
244 ``-v`` command-line switch or with the optional keyword argument
251 python -m doctest -v example.txt
256 For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
259 .. _doctest-how-it-works:
262 ------------
272 .. _doctest-which-docstrings:
291 .. impl-detail::
296 .. _doctest-finding-examples:
301 In most cases a copy-and-paste of an interactive console session works fine,
328 ``'>>> '`` or all-whitespace line.
332 * Expected output cannot contain an all-whitespace line, since such a line is
337 * All hard tab characters are expanded to spaces, using 8-column tab stops.
341 :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
381 .. _doctest-execution-context:
387 *shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the
390 freely use any names defined at top-level in :mod:`M`, and names defined earlier
398 .. _doctest-exceptions:
433 multi-line detail::
471 the first line of the example, *or* start with a non-alphanumeric character.
482 distinguish exceptions from non-exceptions. So in the rare case where you need
509 .. _option-flags-and-directives:
510 .. _doctest-options:
518 The names can also be used in :ref:`doctest directives <doctest-directives>`,
519 and may be passed to the doctest command line interface via the ``-o`` option.
522 The ``-o`` command line option.
596 <doctest-directives>` and ignore them as irrelevant comments). For example::
632 When specified, failures that involve multi-line expected and actual outputs are
638 When specified, failures that involve multi-line expected and actual outputs
669 The doctest command line accepts the option ``-f`` as a shorthand for ``-o
698 single: - (minus); in doctests
699 .. _doctest-directives:
705 <doctest-options>` for an individual example. Doctest directives are
712 on_or_off: "+" \| "-"
715 Whitespace is not allowed between the ``+`` or ``-`` and the directive option
720 example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
729 two blanks before the single-digit list elements, and because the actual output
761 disabling an option via ``-`` in a directive can be useful.
764 .. _doctest-warnings:
792 the key-value pairs was printed in any particular order.
809 Floating-point numbers are also subject to small output variations across
830 .. _doctest-basic-api:
833 ---------
837 introduction to these two functions, see sections :ref:`doctest-simple-testmod`
838 and :ref:`doctest-simple-testfile`.
853 OS-independent module-relative path. By default, this path is relative to the
855 is relative to that package. To ensure OS-independence, *filename* should use
859 * If *module_relative* is ``False``, then *filename* specifies an OS-specific
867 whose directory should be used as the base directory for a module-relative
869 used as the base directory for module-relative filenames. It is an error to
887 failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
892 is very brief (in fact, empty if all tests passed).
896 See section :ref:`doctest-options`.
900 allows failures to be post-mortem debugged. Default behavior is to continue
904 should be used to extract tests from the files. It defaults to a normal parser
936 tests. The *exclude_empty* argument to the newer :class:`DocTestFinder`
964 .. _doctest-unittest-api:
967 ------------
979 def load_tests(loader, tests, ignore):
980 tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
981 return tests
989 Convert doctest tests from one or more text files to a
1006 *paths* specifies an OS-independent module-relative path. By default, this
1009 OS-independence, each filename should use ``/`` characters to separate path
1014 an OS-specific path. The path may be absolute or relative; relative paths
1019 module-relative filenames in *paths*. If no package is specified, then the
1020 calling module's directory is used as the base directory for module-relative
1024 Optional argument *setUp* specifies a set-up function for the test suite.
1025 This is called before running the tests in each file. The *setUp* function
1029 Optional argument *tearDown* specifies a tear-down function for the test
1030 suite. This is called after running the tests in each file. The *tearDown*
1035 variables for the tests. A new copy of this dictionary is created for each
1039 tests, created by or-ing together individual option flags. See section
1040 :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1044 that should be used to extract tests from the files. It defaults to a normal
1056 Convert doctest tests for a module to a :class:`unittest.TestSuite`.
1069 variables for the tests. A new copy of this dictionary is created for each
1076 drop-in replacement) that is used to extract doctests from the module.
1103 when and how tests get run. The framework author typically wants to control
1117 section :ref:`doctest-options`. Only "reporting flags" can be used.
1119 This is a module-global setting, and affects all future doctests run by module
1134 .. _doctest-advanced-api:
1137 ------------
1141 require more fine-grained control over testing, or wish to extend doctest's
1173 +------+ +---------+
1174 |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
1175 +------+ | ^ +---------+ | ^ (printed)
1179 +---------+
1182 .. _doctest-doctest:
1228 ``None`` if the line number is unavailable. This line number is zero-based
1238 .. _doctest-example:
1282 begins. This line number is zero-based with respect to the beginning of the
1300 .. _doctest-doctestfinder:
1317 drop-in replacement) that is used to extract doctests from docstrings.
1323 :meth:`DocTestFinder.find` will include tests for objects with empty docstrings.
1355 to belong to the (non-existent) module, so all contained objects will
1366 .. _doctest-doctestparser:
1394 of :class:`Example` objects. Line numbers are 0-based. The optional argument
1402 :class:`Example`\ s are 0-based. The optional argument *name* is a name
1406 .. _doctest-doctestrunner:
1419 option flags; see section :ref:`doctest-options` for more information. If the
1432 object (or drop-in replacement) that should be used to compare the expected
1439 iff the command-line switch ``-v`` is used.
1443 For more information, see section :ref:`doctest-options`.
1506 the set of future-import flags that apply to *globs*.
1522 .. _doctest-outputchecker:
1544 using, several non-exact match types are also possible. See section
1545 :ref:`doctest-options` for more information about option flags.
1555 .. _doctest-debugging:
1558 ---------
1567 that example. This information can be used to perform post-mortem debugging on
1592 --Return--
1593 > <doctest a[1]>(3)g()->None
1594 -> import pdb; pdb.set_trace()
1598 3 -> import pdb; pdb.set_trace()
1603 --Return--
1604 > <doctest a[0]>(2)f()->None
1605 -> g(x*2)
1608 2 -> g(x*2)
1613 --Return--
1614 > <doctest a[2]>(1)?()->None
1615 -> f(3)
1668 contains a top-level function :func:`f`, then ::
1689 Optional argument *pm* controls whether post-mortem debugging is used. If *pm*
1692 it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
1728 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1782 .. _doctest-soapbox:
1785 -------
1801 this that needs to be learned---it may not be natural at first. Examples should
1813 code-based testing, but few programmers do. Many have found that using doctest
1814 approaches instead leads to much clearer tests. Perhaps this is simply because
1817 the natural attitude when writing a doctest-based test is that you want to
1827 several options for organizing tests:
1841 When you have placed your tests in a module, the module can itself be the test
1842 runner. When a test fails, you can arrange for your test runner to re-run only
1843 the failing doctest while you debug the problem. Here is a minimal example of
1859 print("{} failures out of {} tests".format(fail, total))
1865 Trying to guess where one ends and the other begins is too error-prone, and that