diff options
author | Tim Peters <tim.peters@gmail.com> | 2004-09-26 02:12:40 (GMT) |
---|---|---|
committer | Tim Peters <tim.peters@gmail.com> | 2004-09-26 02:12:40 (GMT) |
commit | 6a0a64b7adff64fe060bebe543796880cdea9148 (patch) | |
tree | 0c681e25787d28f2da0d2f75aeb2a34522b42476 /Doc/lib | |
parent | 9d02a7cfa097492f94d8383ad5c22a4ac684b95a (diff) | |
download | cpython-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.tex | 61 |
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 |