summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
authorTim Peters <tim.peters@gmail.com>2004-09-26 02:12:40 (GMT)
committerTim Peters <tim.peters@gmail.com>2004-09-26 02:12:40 (GMT)
commit6a0a64b7adff64fe060bebe543796880cdea9148 (patch)
tree0c681e25787d28f2da0d2f75aeb2a34522b42476 /Doc/lib
parent9d02a7cfa097492f94d8383ad5c22a4ac684b95a (diff)
downloadcpython-6a0a64b7adff64fe060bebe543796880cdea9148.zip
cpython-6a0a64b7adff64fe060bebe543796880cdea9148.tar.gz
cpython-6a0a64b7adff64fe060bebe543796880cdea9148.tar.bz2
Document set_unittest_reportflags().
Diffstat (limited to 'Doc/lib')
-rw-r--r--Doc/lib/libdoctest.tex61
1 files changed, 59 insertions, 2 deletions
diff --git a/Doc/lib/libdoctest.tex b/Doc/lib/libdoctest.tex
index 072e983..2a838da 100644
--- a/Doc/lib/libdoctest.tex
+++ b/Doc/lib/libdoctest.tex
@@ -933,8 +933,8 @@ had a barely documented \class{Tester} class that supplied a rudimentary
way to combine doctests from multiple modules. \class{Tester} was feeble,
and in practice most serious Python testing frameworks build on the
\module{unittest} module, which supplies many flexible ways to combine
-tests from multiple sources. So, in Python 2.4, module{doctest}'s
-\class{Tester} class is deprecated, and \module{doctest} provides several
+tests from multiple sources. So, in Python 2.4, \module{doctest}'s
+\class{Tester} class is deprecated, and \module{doctest} provides two
functions that can be used to create \module{unittest} test suites from
modules and text files containing doctests. These test suites can then be
run using \module{unittest} test runners:
@@ -951,6 +951,9 @@ runner = unittest.TextTestRunner()
runner.run(suite)
\end{verbatim}
+There are two main functions for creating \class{unittest.TestSuite}
+instances from text files and modules with doctests:
+
\begin{funcdesc}{DocFileSuite}{*paths, **kw}
Convert doctest tests from one or more text files to a
\class{\refmodule{unittest}.TestSuite}.
@@ -1011,6 +1014,8 @@ runner.run(suite)
Optional argument \var{optionflags} specifies the default
doctest options for the tests, created by or-ing together
individual option flags. See section~\ref{doctest-options}.
+ See function \function{set_unittest_reportflags()} below for
+ a better way to set reporting options.
\versionadded{2.4}
\end{funcdesc}
@@ -1049,12 +1054,64 @@ runner.run(suite)
are the same as for function \function{DocFileSuite()} above.
\versionadded{2.3}
+
\versionchanged[The parameters \var{globs}, \var{extraglobs},
\var{test_finder}, \var{setUp}, \var{tearDown}, and
\var{optionflags} were added; this function now uses the same search
technique as \function{testmod()}]{2.4}
\end{funcdesc}
+Under the covers, \function{DocTestSuite()} creates a
+\class{unittest.TestSuite} out of \class{doctest.DocTestCase} instances,
+and \class{DocTestCase} is a subclass of \class{unittest.TestCase}.
+\class{DocTestCase} isn't documented here (it's an internal detail), but
+studying its code can answer questions about the exact details of
+\module{unittest} integration.
+
+Similarly, \function{DocFileSuite()} creates a \class{unittest.TestSuite}
+out of \class{doctest.DocFileCase} instances, and \class{DocFileCase}
+is a subclass of \class{DocTestCase}.
+
+So both ways of creating a \class{unittest.TestSuite} run instances of
+\class{DocTestCase}. This is important for a subtle reason: when you
+run \module{doctest} functions yourself, you can control the
+\module{doctest} options in use directly, by passing option flags to
+\module{doctest} functions. However, if you're writing a \module{unittest}
+framework, \module{unittest} ultimately controls when and how tests
+get run. The framework author typically wants to control \module{doctest}
+reporting options (perhaps, e.g., specified by command line options),
+but there's no way to pass options through \module{unittest} to
+\module{doctest} test runners.
+
+For this reason, \module{doctest} also supports a notion of
+\module{doctest} reporting flags specific to \module{unittest} support,
+via this function:
+
+\begin{funcdesc}{set_unittest_reportflags}{flags}
+ Set the \module{doctest} reporting flags to use.
+
+ Argument \var{flags} or's together option flags. See
+ section~\ref{doctest-options}. Only "reporting flags" can be used.
+
+ This is a module-global setting, and affects all future doctests run
+ by module \module{unittest}: the \method{runTest()} method of
+ \class{DocTestCase} looks at the option flags specified for the test
+ case when the \class{DocTestCase} instance was constructed. If no
+ reporting flags were specified (which is the typical and expected case),
+ \module{doctest}'s \module{unittest} reporting flags are or'ed into the
+ option flags, and the option flags so augmented are passed to the
+ \class{DocTestRunner} instance created to run the doctest. If any
+ reporting flags were specified when the \class{DocTestCase} instance
+ was constructed, \module{doctest}'s \module{unittest} reporting flags
+ are ignored.
+
+ The value of the \module{unittest} reporting flags in effect before the
+ function was called is returned by the function.
+
+ \versionadded{2.4}
+\end{funcdesc}
+
+
\subsection{Advanced API\label{doctest-advanced-api}}
The basic API is a simple wrapper that's intended to make doctest easy