Lines Matching refs:doctest
1 :mod:`doctest` --- Test interactive Python examples
4 .. module:: doctest
12 **Source code:** :source:`Lib/doctest.py`
16 The :mod:`doctest` module searches for pieces of text that look like interactive
18 exactly as shown. There are several common ways to use doctest:
85 import doctest
86 doctest.testmod()
88 If you run :file:`example.py` directly from the command line, :mod:`doctest`
97 ``-v`` to the script, and :mod:`doctest` prints a detailed log of what
133 That's all you need to know to start making productive use of :mod:`doctest`!
145 The simplest way to start using doctest (but not necessarily the way you'll
149 import doctest
150 doctest.testmod()
152 :mod:`doctest` then examines docstrings in module :mod:`M`.
177 instruct the Python interpreter to run the doctest module directly from the
180 python -m doctest -v example.py
186 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
194 Another simple application of doctest is testing interactive examples in a text
197 import doctest
198 doctest.testfile("example.txt")
223 Running ``doctest.testfile("example.txt")`` then finds the error in this
240 See section :ref:`doctest-basic-api` for a description of the optional arguments
248 instruct the Python interpreter to run the doctest module directly from the
251 python -m doctest -v example.txt
253 Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
256 For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
264 This section examines in detail how doctest works: which docstrings it looks at,
267 This is the information that you need to know to write doctest examples; for
268 information about actually running doctest on these examples, see the following
293 searched by doctest.
302 but doctest isn't trying to do an exact emulation of any specific Python shell.
334 blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
340 output includes hard tabs, the only way the doctest can pass is if the
341 :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
363 can double each backslash in the doctest version (and not use a raw string)::
386 By default, each time :mod:`doctest` finds a docstring to test, it uses a
406 numbers), this is one case where doctest works hard to be flexible in what it
416 That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
427 are ignored by doctest. The traceback stack is typically omitted, or copied
456 rewritten example, the use of ``...`` is independent of doctest's
476 * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified,
481 :exc:`SyntaxError`\ s. But doctest uses the traceback header line to
498 and detail, they are not checked by doctest. For example, the following test
515 A number of option flags control various aspects of doctest's behavior.
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.
525 doctest decides whether actual output matches an example's expected output:
577 It will also ignore the module name used in Python 3 doctest reports. Hence
593 from Python 2.3 is also the only clear way to write a doctest that doesn't
595 earlier (those releases do not support :ref:`doctest directives
596 <doctest-directives>` and ignore them as irrelevant comments). For example::
615 where doctest examples serve as both documentation and test cases, and an
653 When specified, display the first failing example in each doctest, but suppress
654 output for all remaining examples. This will prevent doctest from reporting
669 The doctest command line accepts the option ``-f`` as a shorthand for ``-o
681 useful unless you intend to extend :mod:`doctest` internals via subclassing:
705 <doctest-options>` for an individual example. Doctest directives are
708 .. productionlist:: doctest
709 directive: "#" "doctest:" `directive_options`
719 An example's doctest directives modify doctest's behavior for that single
724 >>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
733 >>> print(list(range(20))) # doctest: +ELLIPSIS
739 >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
745 >>> print(list(range(20))) # doctest: +ELLIPSIS
746 ... # doctest: +NORMALIZE_WHITESPACE
754 ... # doctest: +ELLIPSIS
769 :mod:`doctest` is serious about requiring exact matches in expected output. If
806 >>> C() #doctest: +ELLIPSIS
821 contrive doctest examples to produce numbers of that form::
836 doctest that should be sufficient for most basic uses. For a less formal
837 introduction to these two functions, see sections :ref:`doctest-simple-testmod`
838 and :ref:`doctest-simple-testfile`.
873 examples. A new shallow copy of this dict is created for the doctest, so its
882 doctest can be written for a base class, using a generic name for the class,
896 See section :ref:`doctest-options`.
934 compatibility hack, so that code still using :meth:`doctest.master.summarize` in
969 As your collection of doctest'ed modules grows, you'll want a way to run all
970 their doctests systematically. :mod:`doctest` provides two functions that can
976 import doctest
980 tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
989 Convert doctest tests from one or more text files to a
1038 Optional argument *optionflags* specifies the default doctest options for the
1040 :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1056 Convert doctest tests for a module to a :class:`unittest.TestSuite`.
1059 and runs each doctest in the module. If any of the doctests fail, then the
1089 of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
1095 :class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
1100 :mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
1101 use directly, by passing option flags to :mod:`doctest` functions. However, if
1104 :mod:`doctest` reporting options (perhaps, e.g., specified by command line
1106 :mod:`doctest` test runners.
1108 For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
1114 Set the :mod:`doctest` reporting flags to use.
1117 section :ref:`doctest-options`. Only "reporting flags" can be used.
1123 typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
1126 run the doctest. If any reporting flags were specified when the
1127 :class:`DocTestCase` instance was constructed, :mod:`doctest`'s
1139 The basic API is a simple wrapper that's intended to make doctest easy to use.
1141 require more fine-grained control over testing, or wish to extend doctest's
1145 the interactive examples extracted from doctest cases:
1154 doctest examples:
1166 * :class:`OutputChecker`: Compares the actual output from a doctest example with
1182 .. _doctest-doctest:
1190 A collection of doctest examples that should be run in a single namespace. The
1353 obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1383 Extract all doctest examples from the given string, and collect them into a
1393 Extract all doctest examples from the given string, and return them as a list
1419 option flags; see section :ref:`doctest-options` for more information. If the
1433 outputs to the actual outputs of doctest examples.
1443 For more information, see section :ref:`doctest-options`.
1530 A class used to check the whether the actual output from a doctest example
1545 :ref:`doctest-options` for more information about option flags.
1560 Doctest provides several mechanisms for debugging doctest examples:
1573 * You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
1590 >>> import a, doctest
1591 >>> doctest.testmod(a)
1593 > <doctest a[1]>(3)g()->None
1604 > <doctest a[0]>(2)f()->None
1614 > <doctest a[2]>(1)?()->None
1629 Argument *s* is a string containing doctest examples. The string is converted
1630 to a Python script, where doctest examples in *s* are converted to regular code,
1634 import doctest
1635 print(doctest.script_from_examples(r"""
1661 Convert the doctest for an object to a script.
1670 import a, doctest
1671 print(doctest.testsource(a, "a.f"))
1703 doctest examples is specified directly, via the *src* argument.
1715 doctest!) for more details:
1728 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1735 An exception raised by :class:`DocTestRunner` to signal that a doctest example's
1759 An exception raised by :class:`DocTestRunner` to signal that a doctest
1787 As mentioned in the introduction, :mod:`doctest` has grown to have three primary
1805 by and things change. I'm still amazed at how often one of my :mod:`doctest`
1813 code-based testing, but few programmers do. Many have found that using doctest
1815 doctest makes writing prose a little easier than writing code, while writing
1817 the natural attitude when writing a doctest-based test is that you want to
1832 doctest.
1843 the failing doctest while you debug the problem. Here is a minimal example of
1847 import doctest
1848 flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
1855 doctest.run_docstring_examples(obj, globals(), name=name,
1858 fail, total = doctest.testmod(optionflags=flags)