Lines Matching refs:doctest
3 :mod:`doctest` --- Test interactive Python examples
6 .. module:: doctest
14 The :mod:`doctest` module searches for pieces of text that look like interactive
16 exactly as shown. There are several common ways to use doctest:
90 import doctest
91 doctest.testmod()
93 If you run :file:`example.py` directly from the command line, :mod:`doctest`
102 ``-v`` to the script, and :mod:`doctest` prints a detailed log of what
143 That's all you need to know to start making productive use of :mod:`doctest`!
155 The simplest way to start using doctest (but not necessarily the way you'll
159 import doctest
160 doctest.testmod()
162 :mod:`doctest` then examines docstrings in module :mod:`M`.
187 :func:`testmod`. You can instruct the Python interpreter to run the doctest
191 python -m doctest -v example.py
197 For more information on :func:`testmod`, see section :ref:`doctest-basic-api`.
205 Another simple application of doctest is testing interactive examples in a text
208 import doctest
209 doctest.testfile("example.txt")
234 Running ``doctest.testfile("example.txt")`` then finds the error in this
251 See section :ref:`doctest-basic-api` for a description of the optional arguments
259 :func:`testfile`. You can instruct the Python interpreter to run the doctest
263 python -m doctest -v example.txt
265 Because the file name does not end with :file:`.py`, :mod:`doctest` infers that
268 For more information on :func:`testfile`, see section :ref:`doctest-basic-api`.
276 This section examines in detail how doctest works: which docstrings it looks at,
279 This is the information that you need to know to write doctest examples; for
280 information about actually running doctest on these examples, see the following
313 but doctest isn't trying to do an exact emulation of any specific Python shell.
341 blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
351 output includes hard tabs, the only way the doctest can pass is if the
352 :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
378 can double each backslash in the doctest version (and not use a raw string)::
401 By default, each time :mod:`doctest` finds a docstring to test, it uses a
421 numbers), this is one case where doctest works hard to be flexible in what it
431 That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
442 are ignored by doctest. The traceback stack is typically omitted, or copied
474 rewritten example, the use of ``...`` is independent of doctest's
494 * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified,
499 :exc:`SyntaxError`\ s. But doctest uses the traceback header line to
514 and detail, they are not checked by doctest. For example, the following test
531 A number of option flags control various aspects of doctest's behavior.
534 :ref:`doctest directives <doctest-directives>`.
537 doctest decides whether actual output matches an example's expected output:
587 It will also ignore the module name used in Python 3 doctest reports. Hence
603 from Python 2.3 is also the only clear way to write a doctest that doesn't
605 earlier (those releases do not support :ref:`doctest directives
606 <doctest-directives>` and ignore them as irrelevant comments). For example::
625 where doctest examples serve as both documentation and test cases, and an
665 When specified, display the first failing example in each doctest, but suppress
666 output for all remaining examples. This will prevent doctest from reporting
688 unless you intend to extend :mod:`doctest` internals via subclassing:
710 <doctest-options>` for an individual example. Doctest directives are
713 .. productionlist:: doctest
714 directive: "#" "doctest:" `directive_options`
724 An example's doctest directives modify doctest's behavior for that single
729 >>> print range(20) # doctest: +NORMALIZE_WHITESPACE
738 >>> print range(20) # doctest: +ELLIPSIS
744 >>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
750 >>> print range(20) # doctest: +ELLIPSIS
751 ... # doctest: +NORMALIZE_WHITESPACE
759 ... # doctest: +ELLIPSIS
769 Support for doctest directives was added.
777 :mod:`doctest` is serious about requiring exact matches in expected output. If
811 >>> C() #doctest: +ELLIPSIS
826 contrive doctest examples to produce numbers of that form::
841 doctest that should be sufficient for most basic uses. For a less formal
842 introduction to these two functions, see sections :ref:`doctest-simple-testmod`
843 and :ref:`doctest-simple-testfile`.
878 examples. A new shallow copy of this dict is created for the doctest, so its
887 doctest can be written for a base class, using a generic name for the class,
900 :ref:`doctest-options`.
943 compatibility hack, so that code still using :meth:`doctest.master.summarize` in
987 As your collection of doctest'ed modules grows, you'll want a way to run all
988 their doctests systematically. Prior to Python 2.4, :mod:`doctest` had a barely
993 Python 2.4, :mod:`doctest`'s :class:`Tester` class is deprecated, and
994 :mod:`doctest` provides two functions that can be used to create :mod:`unittest`
1000 import doctest
1004 tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
1013 Convert doctest tests from one or more text files to a
1062 Optional argument *optionflags* specifies the default doctest options for the
1064 :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1090 >>> finder = doctest.DocTestFinder(exclude_empty=False)
1091 >>> suite = doctest.DocTestSuite(test_finder=finder)
1096 Convert doctest tests for a module to a :class:`unittest.TestSuite`.
1099 and runs each doctest in the module. If any of the doctests fail, then the
1129 of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
1135 :class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
1140 :mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
1141 use directly, by passing option flags to :mod:`doctest` functions. However, if
1144 :mod:`doctest` reporting options (perhaps, e.g., specified by command line
1146 :mod:`doctest` test runners.
1148 For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
1154 Set the :mod:`doctest` reporting flags to use.
1157 :ref:`doctest-options`. Only "reporting flags" can be used.
1163 typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
1165 :class:`DocTestRunner` instance created to run the doctest. If any reporting
1167 :mod:`doctest`'s :mod:`unittest` reporting flags are ignored.
1180 The basic API is a simple wrapper that's intended to make doctest easy to use.
1182 require more fine-grained control over testing, or wish to extend doctest's
1186 the interactive examples extracted from doctest cases:
1195 doctest examples:
1207 * :class:`OutputChecker`: Compares the actual output from a doctest example with
1223 .. _doctest-doctest:
1231 A collection of doctest examples that should be run in a single namespace. The
1398 obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1429 Extract all doctest examples from the given string, and collect them into a
1439 Extract all doctest examples from the given string, and return them as a list
1465 option flags; see section :ref:`doctest-options` for more information. If the
1479 outputs to the actual outputs of doctest examples.
1489 For more information, see section :ref:`doctest-options`.
1581 A class used to check the whether the actual output from a doctest example
1598 :ref:`doctest-options` for more information about option flags.
1613 Doctest provides several mechanisms for debugging doctest examples:
1626 * You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
1643 >>> import a, doctest
1644 >>> doctest.testmod(a)
1646 > <doctest a[1]>(3)g()->None
1657 > <doctest a[0]>(2)f()->None
1667 > <doctest a[2]>(1)?()->None
1684 Argument *s* is a string containing doctest examples. The string is converted
1685 to a Python script, where doctest examples in *s* are converted to regular code,
1689 import doctest
1690 print doctest.script_from_examples(r"""
1718 Convert the doctest for an object to a script.
1727 import a, doctest
1728 print doctest.testsource(a, "a.f")
1767 doctest examples is specified directly, via the *src* argument.
1780 doctest!) for more details:
1793 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1800 An exception raised by :class:`DocTestRunner` to signal that a doctest example's
1824 An exception raised by :class:`DocTestRunner` to signal that a doctest
1852 As mentioned in the introduction, :mod:`doctest` has grown to have three primary
1870 by and things change. I'm still amazed at how often one of my :mod:`doctest`
1878 code-based testing, but few programmers do. Many have found that using doctest
1880 doctest makes writing prose a little easier than writing code, while writing
1882 the natural attitude when writing a doctest-based test is that you want to
1897 doctest.
1908 the failing doctest while you debug the problem. Here is a minimal example of
1912 import doctest
1913 flags = doctest.REPORT_NDIFF|doctest.REPORT_ONLY_FIRST_FAILURE
1920 doctest.run_docstring_examples(obj, globals(), name=name,
1923 fail, total = doctest.testmod(optionflags=flags)