Lines Matching refs:doctest
3 :mod:`doctest` --- Test interactive Python examples
6 .. module:: doctest
14 **Source code:** :source:`Lib/doctest.py`
18 The :mod:`doctest` module searches for pieces of text that look like interactive
20 exactly as shown. There are several common ways to use doctest:
87 import doctest
88 doctest.testmod()
90 If you run :file:`example.py` directly from the command line, :mod:`doctest`
99 ``-v`` to the script, and :mod:`doctest` prints a detailed log of what
135 That's all you need to know to start making productive use of :mod:`doctest`!
147 The simplest way to start using doctest (but not necessarily the way you'll
151 import doctest
152 doctest.testmod()
154 :mod:`doctest` then examines docstrings in module :mod:`M`.
179 instruct the Python interpreter to run the doctest module directly from the
182 python -m doctest -v example.py
188 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
196 Another simple application of doctest is testing interactive examples in a text
199 import doctest
200 doctest.testfile("example.txt")
225 Running ``doctest.testfile("example.txt")`` then finds the error in this
242 See section :ref:`doctest-basic-api` for a description of the optional arguments
250 instruct the Python interpreter to run the doctest module directly from the
253 python -m doctest -v example.txt
255 Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
258 For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
266 This section examines in detail how doctest works: which docstrings it looks at,
269 This is the information that you need to know to write doctest examples; for
270 information about actually running doctest on these examples, see the following
295 searched by doctest.
304 but doctest isn't trying to do an exact emulation of any specific Python shell.
336 blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
342 output includes hard tabs, the only way the doctest can pass is if the
343 :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
365 can double each backslash in the doctest version (and not use a raw string)::
388 By default, each time :mod:`doctest` finds a docstring to test, it uses a
408 numbers), this is one case where doctest works hard to be flexible in what it
418 That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
429 are ignored by doctest. The traceback stack is typically omitted, or copied
458 rewritten example, the use of ``...`` is independent of doctest's
478 * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified,
483 :exc:`SyntaxError`\ s. But doctest uses the traceback header line to
500 and detail, they are not checked by doctest. For example, the following test
517 A number of option flags control various aspects of doctest's behavior.
520 The names can also be used in :ref:`doctest directives <doctest-directives>`,
521 and may be passed to the doctest command line interface via the ``-o`` option.
527 doctest decides whether actual output matches an example's expected output:
579 It will also ignore the module name used in Python 3 doctest reports. Hence
595 from Python 2.3 is also the only clear way to write a doctest that doesn't
597 earlier (those releases do not support :ref:`doctest directives
598 <doctest-directives>` and ignore them as irrelevant comments). For example::
617 where doctest examples serve as both documentation and test cases, and an
655 When specified, display the first failing example in each doctest, but suppress
656 output for all remaining examples. This will prevent doctest from reporting
671 The doctest command line accepts the option ``-f`` as a shorthand for ``-o
683 useful unless you intend to extend :mod:`doctest` internals via subclassing:
707 <doctest-options>` for an individual example. Doctest directives are
710 .. productionlist:: doctest
711 directive: "#" "doctest:" `directive_options`
721 An example's doctest directives modify doctest's behavior for that single
726 >>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
735 >>> print(list(range(20))) # doctest: +ELLIPSIS
741 >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
747 >>> print(list(range(20))) # doctest: +ELLIPSIS
748 ... # doctest: +NORMALIZE_WHITESPACE
756 ... # doctest: +ELLIPSIS
771 :mod:`doctest` is serious about requiring exact matches in expected output. If
804 >>> C() #doctest: +ELLIPSIS
819 contrive doctest examples to produce numbers of that form::
834 doctest that should be sufficient for most basic uses. For a less formal
835 introduction to these two functions, see sections :ref:`doctest-simple-testmod`
836 and :ref:`doctest-simple-testfile`.
871 examples. A new shallow copy of this dict is created for the doctest, so its
880 doctest can be written for a base class, using a generic name for the class,
894 See section :ref:`doctest-options`.
932 compatibility hack, so that code still using :meth:`doctest.master.summarize` in
967 As your collection of doctest'ed modules grows, you'll want a way to run all
968 their doctests systematically. :mod:`doctest` provides two functions that can
974 import doctest
978 tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
987 Convert doctest tests from one or more text files to a
1036 Optional argument *optionflags* specifies the default doctest options for the
1038 :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1054 Convert doctest tests for a module to a :class:`unittest.TestSuite`.
1057 and runs each doctest in the module. If any of the doctests fail, then the
1087 of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
1093 :class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
1098 :mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
1099 use directly, by passing option flags to :mod:`doctest` functions. However, if
1102 :mod:`doctest` reporting options (perhaps, e.g., specified by command line
1104 :mod:`doctest` test runners.
1106 For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
1112 Set the :mod:`doctest` reporting flags to use.
1115 section :ref:`doctest-options`. Only "reporting flags" can be used.
1121 typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
1124 run the doctest. If any reporting flags were specified when the
1125 :class:`DocTestCase` instance was constructed, :mod:`doctest`'s
1137 The basic API is a simple wrapper that's intended to make doctest easy to use.
1139 require more fine-grained control over testing, or wish to extend doctest's
1143 the interactive examples extracted from doctest cases:
1152 doctest examples:
1164 * :class:`OutputChecker`: Compares the actual output from a doctest example with
1180 .. _doctest-doctest:
1188 A collection of doctest examples that should be run in a single namespace. The
1351 obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1381 Extract all doctest examples from the given string, and collect them into a
1391 Extract all doctest examples from the given string, and return them as a list
1417 option flags; see section :ref:`doctest-options` for more information. If the
1431 outputs to the actual outputs of doctest examples.
1441 For more information, see section :ref:`doctest-options`.
1528 A class used to check the whether the actual output from a doctest example
1543 :ref:`doctest-options` for more information about option flags.
1558 Doctest provides several mechanisms for debugging doctest examples:
1571 * You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
1588 >>> import a, doctest
1589 >>> doctest.testmod(a)
1591 > <doctest a[1]>(3)g()->None
1602 > <doctest a[0]>(2)f()->None
1612 > <doctest a[2]>(1)?()->None
1627 Argument *s* is a string containing doctest examples. The string is converted
1628 to a Python script, where doctest examples in *s* are converted to regular code,
1632 import doctest
1633 print(doctest.script_from_examples(r"""
1659 Convert the doctest for an object to a script.
1668 import a, doctest
1669 print(doctest.testsource(a, "a.f"))
1701 doctest examples is specified directly, via the *src* argument.
1713 doctest!) for more details:
1726 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1733 An exception raised by :class:`DocTestRunner` to signal that a doctest example's
1757 An exception raised by :class:`DocTestRunner` to signal that a doctest
1785 As mentioned in the introduction, :mod:`doctest` has grown to have three primary
1803 by and things change. I'm still amazed at how often one of my :mod:`doctest`
1811 code-based testing, but few programmers do. Many have found that using doctest
1813 doctest makes writing prose a little easier than writing code, while writing
1815 the natural attitude when writing a doctest-based test is that you want to
1830 doctest.
1841 the failing doctest while you debug the problem. Here is a minimal example of
1845 import doctest
1846 flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
1853 doctest.run_docstring_examples(obj, globals(), name=name,
1856 fail, total = doctest.testmod(optionflags=flags)