Lines Matching +full:runner +full:- +full:before +full:- +full:script
1 :mod:`doctest` --- Test interactive Python examples
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
140 .. _doctest-simple-testmod:
143 ---------------------------------------------
154 Running the module as a script causes the examples in the docstrings to get
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 ----------------------------------------------
200 That short script executes and verifies any interactive Python examples
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:
292 .. _doctest-finding-examples:
297 In most cases a copy-and-paste of an interactive console session works fine,
324 ``'>>> '`` or all-whitespace line.
328 * Expected output cannot contain an all-whitespace line, since such a line is
333 * All hard tab characters are expanded to spaces, using 8-column tab stops.
337 :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
377 .. _doctest-execution-context:
386 freely use any names defined at top-level in :mod:`M`, and names defined earlier
394 .. _doctest-exceptions:
429 multi-line detail::
467 the first line of the example, *or* start with a non-alphanumeric character.
478 distinguish exceptions from non-exceptions. So in the rare case where you need
493 Since the lines showing the position of the error come before the exception type
504 .. _option-flags-and-directives:
505 .. _doctest-options:
513 The names can also be used in :ref:`doctest directives <doctest-directives>`,
514 and may be passed to the doctest command line interface via the ``-o`` option.
517 The ``-o`` command line option.
573 It will also ignore any fully qualified name included before the
578 .. code-block:: pycon
621 When specified, failures that involve multi-line expected and actual outputs are
627 When specified, failures that involve multi-line expected and actual outputs
658 The doctest command line accepts the option ``-f`` as a shorthand for ``-o
687 single: - (minus); in doctests
688 .. _doctest-directives:
694 <doctest-options>` for an individual example. Doctest directives are
701 on_or_off: "+" | "-"
704 Whitespace is not allowed between the ``+`` or ``-`` and the directive option
709 example. Use ``+`` to enable the named behavior, or ``-`` to disable it.
714 :no-trim-doctest-flags:
721 two blanks before the single-digit list elements, and because the actual output
726 :no-trim-doctest-flags:
735 :no-trim-doctest-flags:
744 :no-trim-doctest-flags:
755 :no-trim-doctest-flags:
765 disabling an option via ``-`` in a directive can be useful.
768 .. _doctest-warnings:
808 :no-trim-doctest-flags:
813 Floating-point numbers are also subject to small output variations across
834 .. _doctest-basic-api:
837 ---------
841 introduction to these two functions, see sections :ref:`doctest-simple-testmod`
842 and :ref:`doctest-simple-testfile`.
857 OS-independent module-relative path. By default, this path is relative to the
859 is relative to that package. To ensure OS-independence, *filename* should use
863 * If *module_relative* is ``False``, then *filename* specifies an OS-specific
871 whose directory should be used as the base directory for a module-relative
873 used as the base directory for module-relative filenames. It is an error to
891 failures if false; by default, or if ``None``, it's true if and only if ``'-v'``
900 See section :ref:`doctest-options`.
904 allows failures to be post-mortem debugged. Default behavior is to continue
968 .. _doctest-unittest-api:
971 ------------
1010 *paths* specifies an OS-independent module-relative path. By default, this
1013 OS-independence, each filename should use ``/`` characters to separate path
1018 an OS-specific path. The path may be absolute or relative; relative paths
1023 module-relative filenames in *paths*. If no package is specified, then the
1024 calling module's directory is used as the base directory for module-relative
1028 Optional argument *setUp* specifies a set-up function for the test suite.
1029 This is called before running the tests in each file. The *setUp* function
1033 Optional argument *tearDown* specifies a tear-down function for the test
1043 tests, created by or-ing together individual option flags. See section
1044 :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1080 drop-in replacement) that is used to extract doctests from the module.
1121 section :ref:`doctest-options`. Only "reporting flags" can be used.
1123 This is a module-global setting, and affects all future doctests run by module
1134 The value of the :mod:`unittest` reporting flags in effect before the function
1138 .. _doctest-advanced-api:
1141 ------------
1145 require more fine-grained control over testing, or wish to extend doctest's
1177 +------+ +---------+
1178 |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
1179 +------+ | ^ +---------+ | ^ (printed)
1183 +---------+
1186 .. _doctest-doctest:
1232 ``None`` if the line number is unavailable. This line number is zero-based
1242 .. _doctest-example:
1286 begins. This line number is zero-based with respect to the beginning of the
1304 .. _doctest-doctestfinder:
1321 drop-in replacement) that is used to extract doctests from docstrings.
1359 to belong to the (non-existent) module, so all contained objects will
1370 .. _doctest-doctestparser:
1398 of :class:`Example` objects. Line numbers are 0-based. The optional argument
1406 :class:`Example`\ s are 0-based. The optional argument *name* is a name
1410 .. _doctest-doctestrunner:
1423 option flags; see section :ref:`doctest-options` for more information. If the
1427 The test runner's display output can be controlled in two ways. First, an output
1436 object (or drop-in replacement) that should be used to compare the expected
1443 iff the command-line switch ``-v`` is used.
1446 runner compares expected output to actual output, and how it displays failures.
1447 For more information, see section :ref:`doctest-options`.
1455 Report that the test runner is about to process the given example. This method
1510 the set of future-import flags that apply to *globs*.
1526 .. _doctest-outputchecker:
1547 they are identical; but depending on what option flags the test runner is
1548 using, several non-exact match types are also possible. See section
1549 :ref:`doctest-options` for more information about option flags.
1559 .. _doctest-debugging:
1562 ---------
1571 that example. This information can be used to perform post-mortem debugging on
1596 --Return--
1597 > <doctest a[1]>(3)g()->None
1598 -> import pdb; pdb.set_trace()
1602 3 -> import pdb; pdb.set_trace()
1607 --Return--
1608 > <doctest a[0]>(2)f()->None
1609 -> g(x*2)
1612 2 -> g(x*2)
1617 --Return--
1618 > <doctest a[2]>(1)?()->None
1619 -> f(3)
1631 Convert text with examples to a script.
1634 to a Python script, where doctest examples in *s* are converted to regular code,
1635 and everything else is converted to Python comments. The generated script is
1660 script.
1665 Convert the doctest for an object to a script.
1670 containing the object's docstring converted to a Python script, as described for
1672 contains a top-level function :func:`f`, then ::
1677 prints a script version of function :func:`f`'s docstring, with doctests
1686 :func:`testsource` above. The synthesized Python script for the named object's
1693 Optional argument *pm* controls whether post-mortem debugging is used. If *pm*
1694 has a true value, the script file is run directly, and the debugger gets
1695 involved only if the script terminates via raising an unhandled exception. If
1696 it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`,
1698 specified, or is false, the script is run under the debugger from the start, via
1732 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1786 .. _doctest-soapbox:
1789 -------
1805 this that needs to be learned---it may not be natural at first. Examples should
1817 code-based testing, but few programmers do. Many have found that using doctest
1821 the natural attitude when writing a doctest-based test is that you want to
1846 runner. When a test fails, you can arrange for your test runner to re-run only
1848 such a test runner::
1869 Trying to guess where one ends and the other begins is too error-prone, and that