Lines Matching full: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
298 but doctest isn't trying to do an exact emulation of any specific Python shell.
330 blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line
336 output includes hard tabs, the only way the doctest can pass is if the
337 :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>`
359 can double each backslash in the doctest version (and not use a raw string)::
382 By default, each time :mod:`doctest` finds a docstring to test, it uses a
402 numbers), this is one case where doctest works hard to be flexible in what it
412 That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x):
423 are ignored by doctest. The traceback stack is typically omitted, or copied
452 rewritten example, the use of ``...`` is independent of doctest's
459 * Doctest can't guess whether your expected output came from an exception
472 * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified,
477 :exc:`SyntaxError`\ s. But doctest uses the traceback header line to
494 and detail, they are not checked by doctest. For example, the following test
510 A number of option flags control various aspects of doctest's behavior.
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.
520 doctest decides whether actual output matches an example's expected output:
604 where doctest examples serve as both documentation and test cases, and an
642 When specified, display the first failing example in each doctest, but suppress
643 output for all remaining examples. This will prevent doctest from reporting
658 The doctest command line accepts the option ``-f`` as a shorthand for ``-o
670 useful unless you intend to extend :mod:`doctest` internals via subclassing:
693 Doctest directives may be used to modify the :ref:`option flags
694 <doctest-options>` for an individual example. Doctest directives are
697 .. productionlist:: doctest
698 directive: "#" "doctest:" `directive_options`
708 An example's doctest directives modify doctest's behavior for that single
713 .. doctest::
714 :no-trim-doctest-flags:
716 >>> print(list(range(20))) # doctest: +NORMALIZE_WHITESPACE
725 .. doctest::
726 :no-trim-doctest-flags:
728 >>> print(list(range(20))) # doctest: +ELLIPSIS
734 .. doctest::
735 :no-trim-doctest-flags:
737 >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
743 .. doctest::
744 :no-trim-doctest-flags:
746 >>> print(list(range(20))) # doctest: +ELLIPSIS
747 ... # doctest: +NORMALIZE_WHITESPACE
754 .. doctest::
755 :no-trim-doctest-flags:
758 ... # doctest: +ELLIPSIS
773 :mod:`doctest` is serious about requiring exact matches in expected output. If
797 .. doctest::
799 >>> id(1.0) # certain to fail some of the time # doctest: +SKIP
802 >>> C() # the default repr() for instances embeds an address # doctest: +SKIP
807 .. doctest::
808 :no-trim-doctest-flags:
810 >>> C() # doctest: +ELLIPSIS
825 contrive doctest examples to produce numbers of that form::
840 doctest that should be sufficient for most basic uses. For a less formal
841 introduction to these two functions, see sections :ref:`doctest-simple-testmod`
842 and :ref:`doctest-simple-testfile`.
877 examples. A new shallow copy of this dict is created for the doctest, so its
886 doctest can be written for a base class, using a generic name for the class,
900 See section :ref:`doctest-options`.
938 compatibility hack, so that code still using :meth:`doctest.master.summarize` in
973 As your collection of doctest'ed modules grows, you'll want a way to run all
974 their doctests systematically. :mod:`doctest` provides two functions that can
980 import doctest
984 tests.addTests(doctest.DocTestSuite(my_module_with_doctests))
993 Convert doctest tests from one or more text files to a
1030 will be passed a :class:`DocTest` object. The setUp function can access the
1035 function will be passed a :class:`DocTest` object. The setUp function can
1042 Optional argument *optionflags* specifies the default doctest options for the
1044 :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below
1060 Convert doctest tests for a module to a :class:`unittest.TestSuite`.
1063 and runs each doctest in the module. If any of the doctests fail, then the
1093 of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a
1099 :class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass
1104 :mod:`doctest` functions yourself, you can control the :mod:`doctest` options in
1105 use directly, by passing option flags to :mod:`doctest` functions. However, if
1108 :mod:`doctest` reporting options (perhaps, e.g., specified by command line
1110 :mod:`doctest` test runners.
1112 For this reason, :mod:`doctest` also supports a notion of :mod:`doctest`
1118 Set the :mod:`doctest` reporting flags to use.
1121 section :ref:`doctest-options`. Only "reporting flags" can be used.
1127 typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are
1130 run the doctest. If any reporting flags were specified when the
1131 :class:`DocTestCase` instance was constructed, :mod:`doctest`'s
1143 The basic API is a simple wrapper that's intended to make doctest easy to use.
1145 require more fine-grained control over testing, or wish to extend doctest's
1149 the interactive examples extracted from doctest cases:
1154 * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
1158 doctest examples:
1161 :class:`DocTestParser` to create a :class:`DocTest` from every docstring that
1164 * :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such
1167 * :class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and uses
1170 * :class:`OutputChecker`: Compares the actual output from a doctest example with
1178 |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
1186 .. _doctest-doctest:
1188 DocTest Objects
1192 .. class:: DocTest(examples, globs, name, filename, lineno, docstring)
1194 A collection of doctest examples that should be run in a single namespace. The
1198 :class:`DocTest` defines the following attributes. They are initialized by
1218 A string name identifying the :class:`DocTest`. Typically, this is the name
1224 The name of the file that this :class:`DocTest` was extracted from; or
1225 ``None`` if the filename is unknown, or if the :class:`DocTest` was not
1231 The line number within :attr:`filename` where this :class:`DocTest` begins, or
1312 A processing class used to extract the :class:`DocTest`\ s that are relevant to
1314 :class:`DocTest`\ s can be extracted from modules, classes, functions,
1335 Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
1339 used to construct names for the returned :class:`DocTest`\ s. If *name* is
1357 obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1362 The globals for each :class:`DocTest` is formed by combining *globs* and
1364 shallow copy of the globals dictionary is created for each :class:`DocTest`.
1379 them to create a :class:`DocTest` object.
1387 Extract all doctest examples from the given string, and collect them into a
1388 :class:`DocTest` object.
1391 :class:`DocTest` object. See the documentation for :class:`DocTest` for more
1397 Extract all doctest examples from the given string, and return them as a list
1419 :class:`DocTest`.
1423 option flags; see section :ref:`doctest-options` for more information. If the
1437 outputs to the actual outputs of doctest examples.
1447 For more information, see section :ref:`doctest-options`.
1500 Run the examples in *test* (a :class:`DocTest` object), and display the
1534 A class used to check the whether the actual output from a doctest example
1549 :ref:`doctest-options` for more information about option flags.
1564 Doctest provides several mechanisms for debugging doctest examples:
1577 * You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
1594 >>> import a, doctest
1595 >>> doctest.testmod(a)
1597 > <doctest a[1]>(3)g()->None
1608 > <doctest a[0]>(2)f()->None
1618 > <doctest a[2]>(1)?()->None
1633 Argument *s* is a string containing doctest examples. The string is converted
1634 to a Python script, where doctest examples in *s* are converted to regular code,
1638 import doctest
1639 print(doctest.script_from_examples(r"""
1665 Convert the doctest for an object to a script.
1674 import a, doctest
1675 print(doctest.testsource(a, "a.f"))
1707 doctest examples is specified directly, via the *src* argument.
1719 doctest!) for more details:
1732 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1739 An exception raised by :class:`DocTestRunner` to signal that a doctest example's
1748 The :class:`DocTest` object that was being run when the example failed.
1763 An exception raised by :class:`DocTestRunner` to signal that a doctest
1772 The :class:`DocTest` object that was being run when the example failed.
1791 As mentioned in the introduction, :mod:`doctest` has grown to have three primary
1809 by and things change. I'm still amazed at how often one of my :mod:`doctest`
1812 Doctest also makes an excellent tool for regression testing, especially if you
1817 code-based testing, but few programmers do. Many have found that using doctest
1819 doctest makes writing prose a little easier than writing code, while writing
1821 the natural attitude when writing a doctest-based test is that you want to
1836 doctest.
1847 the failing doctest while you debug the problem. Here is a minimal example of
1851 import doctest
1852 flags = doctest.REPORT_NDIFF|doctest.FAIL_FAST
1859 doctest.run_docstring_examples(obj, globals(), name=name,
1862 fail, total = doctest.testmod(optionflags=flags)