[Python-checkins] python/dist/src/Doc/lib libtest.tex,1.3,1.4
fdrake at users.sourceforge.net
fdrake at users.sourceforge.net
Sat Sep 6 11:51:18 EDT 2003
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv17696/lib
Modified Files:
libtest.tex
Log Message:
- reorganize sections
- correct section level error (module references are always \section)
- many markup revisions, including some minor rewordings
Index: libtest.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libtest.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** libtest.tex 6 Sep 2003 04:39:54 -0000 1.3
--- libtest.tex 6 Sep 2003 17:51:16 -0000 1.4
***************
*** 3,26 ****
\declaremodule{standard}{test}
-
\sectionauthor{Brett Cannon}{brett at python.org}
! \modulesynopsis{Regression tests package containing the testing suite for
! Python.}
!
!
! The \module{test} package contains all regression tests for Python as well as
! the modules \module{test_support} and \module{regrtest.py}.
! \module{test_support} is used to enhance your tests while \module{regrtest.py}
! drives the testing suite.
Each module in the \module{test} package whose name starts with
! \code{'test_'} is a testing suite for a specific module or feature.
! All new tests should be written using the \module{unittest} module; using
! \module{unittest} is not required but makes the tests more flexible and
! maintenance of the tests easier.
! Some older tests are written to use \module{doctest} and a ``traditional''
! testing style; these styles of tests will not be covered.
\begin{seealso}
--- 3,23 ----
\declaremodule{standard}{test}
\sectionauthor{Brett Cannon}{brett at python.org}
+ \modulesynopsis{Regression tests package containing the testing suite
+ for Python.}
! The \module{test} package contains all regression tests for Python as
! well as the modules \module{test.test_support} and
! \module{test.regrtest}. \module{test.test_support} is used to enhance
! your tests while \module{test.regrtest} drives the testing suite.
Each module in the \module{test} package whose name starts with
! \samp{test_} is a testing suite for a specific module or feature.
! All new tests should be written using the \refmodule{unittest} module;
! using \refmodule{unittest} is not required but makes the tests more
! flexible and maintenance of the tests easier. Some older tests are
! written to use \refmodule{doctest} and a ``traditional'' testing
! style; these styles of tests will not be covered.
\begin{seealso}
***************
*** 30,125 ****
- \subsection{\module{test.test_support} --- Utility functions for tests}
- \declaremodule[test.testsupport]{standard}{test.test_support}
-
- The \module{test.test_support} module contains functions for assisting
- with writing regression tests.
-
- The \module{test.test_support} module defines the following exceptions:
-
- \begin{excdesc}{TestFailed}
- Exception to be raised when a test fails.
- \end{excdesc}
-
- \begin{excdesc}{TestSkipped}
- Subclass of \exception{TestFailed}.
- Raised when a test is skipped.
- This occurs when a needed resource (such as a network connection) is not
- available at the time of testing.
- \end{excdesc}
-
- \begin{excdesc}{ResourceDenied}
- Subclass of \exception{TestSkipped}.
- Raised when a resource (such as a network connection) is not available.
- Raised by the \function{requires} function.
- \end{excdesc}
-
-
- The \module{test_support} module defines the following constants:
-
- \begin{datadesc}{verbose}
- \constant{True} when verbose output is enabled.
- Should be checked when more detailed information is desired about a running
- test.
- \var{verbose} is set by \module{regrtest.py}.
- \end{datadesc}
-
- \begin{datadesc}{have_unicode}
- \constant{True} when Unicode support is available.
- \end{datadesc}
-
- \begin{datadesc}{is_jython}
- \constant{True} if the running interpreter is Jython.
- \end{datadesc}
-
- \begin{datadesc}{TESTFN}
- Set to the path that a temporary file may be created at.
- Any temporary that is created should be closed and unlinked (removed).
- \end{datadesc}
-
-
- The \module{test_support} module defines the following functions:
-
- \begin{funcdesc}{forget}{module_name}
- Removes the module named \var{module_name} from \module{sys.modules} and deletes
- any byte-compiled files of the module.
- \end{funcdesc}
-
- \begin{funcdesc}{is_resource_enabled}{resource}
- Returns \constant{True} if \var{resource} is enabled and available.
- The list of available resources is only set when \module{regrtest.py} is
- executing the tests.
- \end{funcdesc}
-
- \begin{funcdesc}{requires}{resource\optional{, msg}}
- Raises \exception{ResourceDenied} if \var{resource} is not available.
- \var{msg} is the argument to \exception{ResourceDenied} if it is raised.
- Always returns true if called by a function whose \var{__name__} is
- \code{"__main__"}.
- Used when tests are executed by \module{regrtest.py}.
- \end{funcdesc}
-
- \begin{funcdesc}{findfile}{filename}
- Return the path to the file named \var{filename}.
- If no match is found \var{filename} is returned.
- This does not equal a failure since it could be the path to the file.
- \end{funcdesc}
-
- \begin{funcdesc}{run_unittest}{*classes}
- Execute \class{unittest.TestCase} subclasses passed to the function.
- The function scans the classes for methods starting with the name
- \code{"test_"} and executes the tests individually.
- This is the preferred way to execute tests.
- \end{funcdesc}
-
- \begin{funcdesc}{run_suite}{suite\optional{, testclass=None}}
- Execute the \class{unittest.TestSuite} instance, \var{suite}.
- The optional argument \var{testclass} accepts one of the test classes in the
- suite so as to print out more detailed information on where the testing suite
- originated from.
- \end{funcdesc}
-
-
-
\subsection{Writing Unit Tests for the \module{test} package%
\label{writing-tests}}
--- 27,30 ----
***************
*** 127,131 ****
It is preferred that tests for the \module{test} package use the
\refmodule{unittest} module and follow a few guidelines.
! One is to have the name of all the test methods start with \code{"test_"} as
well as the module's name.
This is needed so that the methods are recognized by the test driver as
--- 32,36 ----
It is preferred that tests for the \module{test} package use the
\refmodule{unittest} module and follow a few guidelines.
! One is to have the name of all the test methods start with \samp{test_} as
well as the module's name.
This is needed so that the methods are recognized by the test driver as
***************
*** 133,137 ****
Also, no documentation string for the method should be included.
A comment (such as
! \code{\# Tests function returns only True or False}) should be used to provide
documentation for test methods.
This is done because documentation strings get printed out if they exist and
--- 38,42 ----
Also, no documentation string for the method should be included.
A comment (such as
! \samp{\# Tests function returns only True or False}) should be used to provide
documentation for test methods.
This is done because documentation strings get printed out if they exist and
***************
*** 179,184 ****
\end{verbatim}
! This boilerplate code allows the testing suite to be run by \module{regrtest.py}
! as well as on its own as a script.
The goal for regression testing is to try to break code.
--- 84,89 ----
\end{verbatim}
! This boilerplate code allows the testing suite to be run by
! \module{test.regrtest} as well as on its own as a script.
The goal for regression testing is to try to break code.
***************
*** 209,214 ****
anomalous behavior from side-effects of importing a module.
\item Try to maximize code reuse.
! On occasion tests will vary by something as small as what type of input
! they take.
Minimize code duplication by subclassing a basic test class with a class
that specifies the input:
--- 114,119 ----
anomalous behavior from side-effects of importing a module.
\item Try to maximize code reuse.
! On occasion, tests will vary by something as small as what type
! of input is used.
Minimize code duplication by subclassing a basic test class with a class
that specifies the input:
***************
*** 233,276 ****
\begin{seealso}
! \seetitle{Test Driven Development}{A book by Kent Beck on writing tests before
! code}
\end{seealso}
! \subsection{Running tests Using \module{regrtest.py} \label{regrtest}}
!
! \module{regrtest.py} is the script used to drive Python's regression test
! suite.
Running the script by itself automatically starts running all
regression tests in the \module{test} package.
It does this by finding all modules in the package whose name starts with
! \code{test_}, importing them, and executing the function \function{test_main}
! if present.
The names of tests to execute may also be passed to the script.
! Specifying a single regression test (\code{python regrtest.py test_spam.py})
! will minimize output and only print whether the test passed or failed and thus
! minimize output.
! Running \module{regrtest.py} directly allows what resources are
available for tests to use to be set.
! You do this by using the \code{-u} command-line option.
! Run \code{python regrtest.py -uall} to turn on all resources;
! specifying \code{all} as an option for \code{-u} enables all possible
! resources.
If all but one resource is desired (a more common case), a
comma-separated list of resources that are not desired may be listed after
! \code{all}.
! The command \code{python regrtest.py -uall,-audio,-largefile} will run
! \module{regrtest.py} with all resources except the audio and largefile
! resources.
For a list of all resources and more command-line options, run
! \code{python regrtest.py -h}.
Some other ways to execute the regression tests depend on what platform the
tests are being executed on.
! On \UNIX{}, you can run \code{make test} at the top-level directory
! where Python was built.
! On Windows, executing \code{rt.bat} from your PCBuild directory will run all
regression tests.
--- 138,274 ----
\begin{seealso}
! \seetitle{Test Driven Development}
! {A book by Kent Beck on writing tests before code.}
\end{seealso}
+ \subsection{Running tests Using \module{test.regrtest} \label{regrtest}}
! \module{test.regrtest} can be used as a script to drive Python's
! regression test suite.
Running the script by itself automatically starts running all
regression tests in the \module{test} package.
It does this by finding all modules in the package whose name starts with
! \samp{test_}, importing them, and executing the function
! \function{test_main()} if present.
The names of tests to execute may also be passed to the script.
! Specifying a single regression test (\program{python regrtest.py}
! \programopt{test_spam.py}) will minimize output and only print whether
! the test passed or failed and thus minimize output.
! Running \module{test.regrtest} directly allows what resources are
available for tests to use to be set.
! You do this by using the \programopt{-u} command-line option.
! Run \program{python regrtest.py} \programopt{-uall} to turn on all
! resources; specifying \programopt{all} as an option for
! \programopt{-u} enables all possible resources.
If all but one resource is desired (a more common case), a
comma-separated list of resources that are not desired may be listed after
! \programopt{all}.
! The command \program{python regrtest.py}
! \programopt{-uall,-audio,-largefile} will run \module{test.regrtest}
! with all resources except the \programopt{audio} and
! \programopt{largefile} resources.
For a list of all resources and more command-line options, run
! \program{python regrtest.py} \programopt{-h}.
Some other ways to execute the regression tests depend on what platform the
tests are being executed on.
! On \UNIX{}, you can run \program{make} \programopt{test} at the
! top-level directory where Python was built.
! On Windows, executing \program{rt.bat} from your \file{PCBuild}
! directory will run all regression tests.
!
!
! \section{\module{test.test_support} ---
! Utility functions for tests}
!
! \declaremodule[test.testsupport]{standard}{test.test_support}
! \modulesynopsis{Support for Python regression tests.}
!
! The \module{test.test_support} module provides support for Python's
regression tests.
+ This module defines the following exceptions:
+
+ \begin{excdesc}{TestFailed}
+ Exception to be raised when a test fails.
+ \end{excdesc}
+
+ \begin{excdesc}{TestSkipped}
+ Subclass of \exception{TestFailed}.
+ Raised when a test is skipped.
+ This occurs when a needed resource (such as a network connection) is not
+ available at the time of testing.
+ \end{excdesc}
+
+ \begin{excdesc}{ResourceDenied}
+ Subclass of \exception{TestSkipped}.
+ Raised when a resource (such as a network connection) is not available.
+ Raised by the \function{requires()} function.
+ \end{excdesc}
+
+
+ The \module{test.test_support} module defines the following constants:
+
+ \begin{datadesc}{verbose}
+ \constant{True} when verbose output is enabled.
+ Should be checked when more detailed information is desired about a running
+ test.
+ \var{verbose} is set by \module{test.regrtest}.
+ \end{datadesc}
+
+ \begin{datadesc}{have_unicode}
+ \constant{True} when Unicode support is available.
+ \end{datadesc}
+
+ \begin{datadesc}{is_jython}
+ \constant{True} if the running interpreter is Jython.
+ \end{datadesc}
+
+ \begin{datadesc}{TESTFN}
+ Set to the path that a temporary file may be created at.
+ Any temporary that is created should be closed and unlinked (removed).
+ \end{datadesc}
+
+
+ The \module{test.test_support} module defines the following functions:
+
+ \begin{funcdesc}{forget}{module_name}
+ Removes the module named \var{module_name} from \code{sys.modules} and deletes
+ any byte-compiled files of the module.
+ \end{funcdesc}
+
+ \begin{funcdesc}{is_resource_enabled}{resource}
+ Returns \constant{True} if \var{resource} is enabled and available.
+ The list of available resources is only set when \module{test.regrtest}
+ is executing the tests.
+ \end{funcdesc}
+
+ \begin{funcdesc}{requires}{resource\optional{, msg}}
+ Raises \exception{ResourceDenied} if \var{resource} is not available.
+ \var{msg} is the argument to \exception{ResourceDenied} if it is raised.
+ Always returns true if called by a function whose \code{__name__} is
+ \code{'__main__'}.
+ Used when tests are executed by \module{test.regrtest}.
+ \end{funcdesc}
+
+ \begin{funcdesc}{findfile}{filename}
+ Return the path to the file named \var{filename}.
+ If no match is found \var{filename} is returned.
+ This does not equal a failure since it could be the path to the file.
+ \end{funcdesc}
+
+ \begin{funcdesc}{run_unittest}{*classes}
+ Execute \class{unittest.TestCase} subclasses passed to the function.
+ The function scans the classes for methods starting with the prefix
+ \samp{test_} and executes the tests individually.
+ This is the preferred way to execute tests.
+ \end{funcdesc}
+
+ \begin{funcdesc}{run_suite}{suite\optional{, testclass}}
+ Execute the \class{unittest.TestSuite} instance \var{suite}.
+ The optional argument \var{testclass} accepts one of the test classes in the
+ suite so as to print out more detailed information on where the testing suite
+ originated from.
+ \end{funcdesc}
More information about the Python-checkins
mailing list