mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-27 13:45:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Explain the motivation for the unittest functions, and beef up the

Browse source 
example.  Squash repeated argument descriptions.  Minor rewordings.
This commit is contained in:
Tim Peters 2004-09-25 03:02:23 +00:00
parent 48983fc484
commit 8c0a2cf938
1 changed files with 49 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

100
Doc/lib/libdoctest.tex
View file

@ -860,7 +860,7 @@ sections \ref{doctest-simple-testmod} and
passed). passed).
Optional argument \var{optionflags} or's together option flags. See Optional argument \var{optionflags} or's together option flags. See
see section~\ref{doctest-options}. section~\ref{doctest-options}.
Optional argument \var{raise_on_error} defaults to false. If true, Optional argument \var{raise_on_error} defaults to false. If true,
an exception is raised upon the first failure or unexpected exception an exception is raised upon the first failure or unexpected exception
@ -927,34 +927,46 @@ sections \ref{doctest-simple-testmod} and
\subsection{Unittest API\label{doctest-unittest-api}} \subsection{Unittest API\label{doctest-unittest-api}}
Doctest provides several functions that can be used to create As your collection of doctest'ed modules grows, you'll want a way to run
\module{unittest} test suites from doctest examples. These test all their doctests systematically. Prior to Python 2.4, \module{doctest}
suites can then be run using \module{unittest} test runners: 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
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:
\begin{verbatim} \begin{verbatim}
import unittest import unittest
import doctest import doctest
import my_module_with_doctests import my_module_with_doctests, and_another
suite = doctest.DocTestSuite(my_module_with_doctests) suite = unittest.TestSuite()
runner = unittest.TextTestRunner() for mod in my_module_with_doctests, and_another:
runner.run(suite) suite.addTest(doctest.DocTestSuite(mod))
runner = unittest.TextTestRunner()
runner.run(suite)
\end{verbatim} \end{verbatim}
\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}.
The returned \class{TestSuite} is to be run by the unittest The returned \class{unittest.TestSuite} is to be run by the unittest
framework and runs the interactive examples in each file. If an framework and runs the interactive examples in each file. If an
example in any file fails, then the synthesized unit test fails, and example in any file fails, then the synthesized unit test fails, and
a \exception{failureException} exception is raised showing the a \exception{failureException} exception is raised showing the
name of the file containing the test and a (sometimes approximate) name of the file containing the test and a (sometimes approximate)
line number. line number.
A number of options may be provided as keyword arguments: Pass one or more paths (as strings) to text files to be examined.
The optional argument \var{module_relative} specifies how Options may be provided as keyword arguments:
Optional argument \var{module_relative} specifies how
the the filenames in \var{paths} should be interpreted: the the filenames in \var{paths} should be interpreted:
\begin{itemize} \begin{itemize}
@ -972,33 +984,33 @@ suites can then be run using \module{unittest} test runners:
current working directory. current working directory.
\end{itemize} \end{itemize}
The optional argument \var{package} is a Python package or the name Optional argument \var{package} is a Python package or the name
of a Python package whose directory should be used as the base of a Python package whose directory should be used as the base
directory for module-relative filenames. If no package is directory for module-relative filenames. If no package is
specified, then the calling module's directory is used as the base specified, then the calling module's directory is used as the base
directory for module-relative filenames. It is an error to specify directory for module-relative filenames. It is an error to specify
\var{package} if \var{module_relative} is \code{False}. \var{package} if \var{module_relative} is \code{False}.
The optional argument \var{setUp} specifies a set-up function for Optional argument \var{setUp} specifies a set-up function for
the test suite. This is called before running the tests in each the test suite. This is called before running the tests in each
file. The \var{setUp} function will be passed a \class{DocTest} file. The \var{setUp} function will be passed a \class{DocTest}
object. The setUp function can access the test globals as the object. The setUp function can access the test globals as the
\var{globs} attribute of the test passed. \var{globs} attribute of the test passed.
The optional argument \var{tearDown} specifies a tear-down function Optional argument \var{tearDown} specifies a tear-down function
for the test suite. This is called after running the tests in each for the test suite. This is called after running the tests in each
file. The \var{tearDown} function will be passed a \class{DocTest} file. The \var{tearDown} function will be passed a \class{DocTest}
object. The setUp function can access the test globals as the object. The setUp function can access the test globals as the
\var{globs} attribute of the test passed. \var{globs} attribute of the test passed.
The optional argument \var{globs} is a dictionary containing the Optional argument \var{globs} is a dictionary containing the
initial global variables for the tests. A new copy of this initial global variables for the tests. A new copy of this
dictionary is created for each test. By default, \var{globs} is dictionary is created for each test. By default, \var{globs} is
empty. a new empty dictionary.
The optional argument \var{optionflags} specifies the default Optional argument \var{optionflags} specifies the default
doctest options for the tests. It is created by or-ing together doctest options for the tests, created by or-ing together
individual option flags. individual option flags. See section~\ref{doctest-options}.
\versionadded{2.4} \versionadded{2.4}
\end{funcdesc} \end{funcdesc}
@ -1010,58 +1022,44 @@ suites can then be run using \module{unittest} test runners:
Convert doctest tests for a module to a Convert doctest tests for a module to a
\class{\refmodule{unittest}.TestSuite}. \class{\refmodule{unittest}.TestSuite}.
The returned \class{TestSuite} is to be run by the unittest framework The returned \class{unittest.TestSuite} is to be run by the unittest
and runs each doctest in the module. If any of the doctests fail, framework and runs each doctest in the module. If any of the doctests
then the synthesized unit test fails, and a \exception{failureException} fail, then the synthesized unit test fails, and a
exception is raised showing the name of the file containing the test and a \exception{failureException} exception is raised showing the name of the
(sometimes approximate) line number. file containing the test and a (sometimes approximate) line number.
The optional argument \var{module} provides the module to be tested. It Optional argument \var{module} provides the module to be tested. It
can be a module object or a (possibly dotted) module name. If not can be a module object or a (possibly dotted) module name. If not
specified, the module calling this function is used. specified, the module calling this function is used.
The optional argument \var{globs} is a dictionary containing the Optional argument \var{globs} is a dictionary containing the
initial global variables for the tests. A new copy of this initial global variables for the tests. A new copy of this
dictionary is created for each test. By default, \var{globs} is dictionary is created for each test. By default, \var{globs} is
empty. a new empty dictionary.
The optional argument \var{extraglobs} specifies an extra set of Optional argument \var{extraglobs} specifies an extra set of
global variables, which is merged into \var{globs}. By default, no global variables, which is merged into \var{globs}. By default, no
extra globals are used. extra globals are used.
The optional argument \var{test_finder} is the \class{DocTestFinder} Optional argument \var{test_finder} is the \class{DocTestFinder}
object (or a drop-in replacement) that is used to extract doctests object (or a drop-in replacement) that is used to extract doctests
from the module. from the module.
The optional argument \var{setUp} specifies a set-up function for Optional arguments \var{setUp}, \var{tearDown}, and \var{optionflags}
the test suite. This is called before running the tests in each are the same as for function \function{DocFileSuite()} above.
file. The \var{setUp} function will be passed a \class{DocTest}
object. The setUp function can access the test globals as the
\var{globs} attribute of the test passed.
The optional argument \var{tearDown} specifies a tear-down function
for the test suite. This is called after running the tests in each
file. The \var{tearDown} function will be passed a \class{DocTest}
object. The setUp function can access the test globals as the
\var{globs} attribute of the test passed.
The optional argument \var{optionflags} specifies the default
doctest options for the tests. It is created by or-ing together
individual option flags.
\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]{2.4} \var{optionflags} were added; this function now uses the same search
\versionchanged[This function now uses the same search technique as technique as \function{testmod()}]{2.4}
\function{testmod()}.]{2.4}
\end{funcdesc} \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
to use. It is fairly flexible, and should meet most user's needs; to use. It is fairly flexible, and should meet most users' needs;
however, if you require more fine grained control over testing, or however, if you require more fine-grained control over testing, or
wish to extend doctest's capabilities, then you should use the wish to extend doctest's capabilities, then you should use the
advanced API. advanced API.