mirror of
https://github.com/python/cpython
synced 2024-10-07 14:09:34 +00:00
Document set_unittest_reportflags().
This commit is contained in:
parent
9d02a7cfa0
commit
6a0a64b7ad
|
@ -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,
|
way to combine doctests from multiple modules. \class{Tester} was feeble,
|
||||||
and in practice most serious Python testing frameworks build on the
|
and in practice most serious Python testing frameworks build on the
|
||||||
\module{unittest} module, which supplies many flexible ways to combine
|
\module{unittest} module, which supplies many flexible ways to combine
|
||||||
tests from multiple sources. So, in Python 2.4, module{doctest}'s
|
tests from multiple sources. So, in Python 2.4, \module{doctest}'s
|
||||||
\class{Tester} class is deprecated, and \module{doctest} provides several
|
\class{Tester} class is deprecated, and \module{doctest} provides two
|
||||||
functions that can be used to create \module{unittest} test suites from
|
functions that can be used to create \module{unittest} test suites from
|
||||||
modules and text files containing doctests. These test suites can then be
|
modules and text files containing doctests. These test suites can then be
|
||||||
run using \module{unittest} test runners:
|
run using \module{unittest} test runners:
|
||||||
|
@ -951,6 +951,9 @@ runner = unittest.TextTestRunner()
|
||||||
runner.run(suite)
|
runner.run(suite)
|
||||||
\end{verbatim}
|
\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}
|
\begin{funcdesc}{DocFileSuite}{*paths, **kw}
|
||||||
Convert doctest tests from one or more text files to a
|
Convert doctest tests from one or more text files to a
|
||||||
\class{\refmodule{unittest}.TestSuite}.
|
\class{\refmodule{unittest}.TestSuite}.
|
||||||
|
@ -1011,6 +1014,8 @@ runner.run(suite)
|
||||||
Optional argument \var{optionflags} specifies the default
|
Optional argument \var{optionflags} specifies the default
|
||||||
doctest options for the tests, created by or-ing together
|
doctest options for the tests, created by or-ing together
|
||||||
individual option flags. See section~\ref{doctest-options}.
|
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}
|
\versionadded{2.4}
|
||||||
\end{funcdesc}
|
\end{funcdesc}
|
||||||
|
@ -1049,12 +1054,64 @@ runner.run(suite)
|
||||||
are the same as for function \function{DocFileSuite()} above.
|
are the same as for function \function{DocFileSuite()} above.
|
||||||
|
|
||||||
\versionadded{2.3}
|
\versionadded{2.3}
|
||||||
|
|
||||||
\versionchanged[The parameters \var{globs}, \var{extraglobs},
|
\versionchanged[The parameters \var{globs}, \var{extraglobs},
|
||||||
\var{test_finder}, \var{setUp}, \var{tearDown}, and
|
\var{test_finder}, \var{setUp}, \var{tearDown}, and
|
||||||
\var{optionflags} were added; this function now uses the same search
|
\var{optionflags} were added; this function now uses the same search
|
||||||
technique as \function{testmod()}]{2.4}
|
technique as \function{testmod()}]{2.4}
|
||||||
\end{funcdesc}
|
\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}}
|
\subsection{Advanced API\label{doctest-advanced-api}}
|
||||||
|
|
||||||
The basic API is a simple wrapper that's intended to make doctest easy
|
The basic API is a simple wrapper that's intended to make doctest easy
|
||||||
|
|
Loading…
Reference in a new issue