Lines Matching full: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
481 * Doctest can't guess whether your expected output came from an exception
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 The names can also be used in :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:
709 Doctest directives may be used to modify the :ref:`option flags
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
1050 will be passed a :class:`DocTest` object. The setUp function can access the
1055 function will be passed a :class:`DocTest` object. The setUp function can
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
1166 run the doctest. If any reporting flags were specified when the
1167 :class:`DocTestCase` instance was constructed, :mod:`doctest`'s
1181 The basic API is a simple wrapper that's intended to make doctest easy to use.
1183 require more fine-grained control over testing, or wish to extend doctest's
1187 the interactive examples extracted from doctest cases:
1192 * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
1196 doctest examples:
1199 :class:`DocTestParser` to create a :class:`DocTest` from every docstring that
1202 * :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such
1205 * :class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and uses
1208 * :class:`OutputChecker`: Compares the actual output from a doctest example with
1216 |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results
1224 .. _doctest-doctest:
1226 DocTest Objects
1230 .. class:: DocTest(examples, globs, name, filename, lineno, docstring)
1232 A collection of doctest examples that should be run in a single namespace. The
1237 :class:`DocTest` defines the following attributes. They are initialized by
1257 A string name identifying the :class:`DocTest`. Typically, this is the name
1263 The name of the file that this :class:`DocTest` was extracted from; or
1264 ``None`` if the filename is unknown, or if the :class:`DocTest` was not
1270 The line number within :attr:`filename` where this :class:`DocTest` begins, or
1352 A processing class used to extract the :class:`DocTest`\ s that are relevant to
1354 :class:`DocTest`\ s can currently be extracted from the following object types:
1377 Return a list of the :class:`DocTest`\ s that are defined by *obj*'s
1381 used to construct names for the returned :class:`DocTest`\ s. If *name* is
1399 obscure, of use mostly in testing doctest itself: if *module* is ``False``, or
1404 The globals for each :class:`DocTest` is formed by combining *globs* and
1406 shallow copy of the globals dictionary is created for each :class:`DocTest`.
1421 them to create a :class:`DocTest` object.
1430 Extract all doctest examples from the given string, and collect them into a
1431 :class:`DocTest` object.
1434 :class:`DocTest` object. See the documentation for :class:`DocTest` for more
1440 Extract all doctest examples from the given string, and return them as a list
1462 :class:`DocTest`.
1466 option flags; see section :ref:`doctest-options` for more information. If the
1480 outputs to the actual outputs of doctest examples.
1490 For more information, see section :ref:`doctest-options`.
1544 Run the examples in *test* (a :class:`DocTest` object), and display the
1582 A class used to check the whether the actual output from a doctest example
1599 :ref:`doctest-options` for more information about option flags.
1614 Doctest provides several mechanisms for debugging doctest examples:
1627 * You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll
1644 >>> import a, doctest
1645 >>> doctest.testmod(a)
1647 > <doctest a[1]>(3)g()->None
1658 > <doctest a[0]>(2)f()->None
1668 > <doctest a[2]>(1)?()->None
1685 Argument *s* is a string containing doctest examples. The string is converted
1686 to a Python script, where doctest examples in *s* are converted to regular code,
1690 import doctest
1691 print doctest.script_from_examples(r"""
1719 Convert the doctest for an object to a script.
1728 import a, doctest
1729 print doctest.testsource(a, "a.f")
1768 doctest examples is specified directly, via the *src* argument.
1781 doctest!) for more details:
1794 documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`.
1801 An exception raised by :class:`DocTestRunner` to signal that a doctest example's
1810 The :class:`DocTest` object that was being run when the example failed.
1825 An exception raised by :class:`DocTestRunner` to signal that a doctest
1834 The :class:`DocTest` object that was being run when the example failed.
1853 As mentioned in the introduction, :mod:`doctest` has grown to have three primary
1871 by and things change. I'm still amazed at how often one of my :mod:`doctest`
1874 Doctest also makes an excellent tool for regression testing, especially if you
1879 code-based testing, but few programmers do. Many have found that using doctest
1881 doctest makes writing prose a little easier than writing code, while writing
1883 the natural attitude when writing a doctest-based test is that you want to
1898 doctest.
1909 the failing doctest while you debug the problem. Here is a minimal example of
1913 import doctest
1914 flags = doctest.REPORT_NDIFF|doctest.REPORT_ONLY_FIRST_FAILURE
1921 doctest.run_docstring_examples(obj, globals(), name=name,
1924 fail, total = doctest.testmod(optionflags=flags)