Each TestCase instance represents a single test, but each
concrete subclass may be used to define multiple tests -- the
concrete class represents a single test fixture. The fixture is
created and cleaned up for each test case.
TestCase instances provide three groups of methods: one group
used to run the test, another used by the test implementation to
check conditions and report failures, and some inquiry methods
allowing information about the test itself to be gathered.
Methods in the first group (running the test) are:
setUp(
)
Method called to prepare the test fixture. This is called
immediately before calling the test method; any exception raised by
this method will be considered an error rather than a test failure.
The default implementation does nothing.
tearDown(
)
Method called immediately after the test method has been called and
the result recorded. This is called even if the test method raised
an exception, so the implementation in subclasses may need to be
particularly careful about checking internal state. Any exception
raised by this method will be considered an error rather than a test
failure. This method will only be called if the setUp()
succeeds, regardless of the outcome of the test method.
The default implementation does nothing.
run(
[result])
Run the test, collecting the result into the test result object
passed as result. If result is omitted or None,
a temporary result object is created (by calling the
defaultTestCase() method) and used; this result object is not
returned to run()'s caller.
The same effect may be had by simply calling the TestCase
instance.
debug(
)
Run the test without collecting the result. This allows exceptions
raised by the test to be propagated to the caller, and can be used
to support running tests under a debugger.
The test code can use any of the following methods to check for and
report failures.
assert_(
expr[, msg])
failUnless(
expr[, msg])
Signal a test failure if expr is false; the explanation for
the error will be msg if given, otherwise it will be
None.
assertEqual(
first, second[, msg])
failUnlessEqual(
first, second[, msg])
Test that first and second are equal. If the values do
not compare equal, the test will fail with the explanation given by
msg, or None. Note that using failUnlessEqual()
improves upon doing the comparison as the first parameter to
failUnless(): the default value for msg can be
computed to include representations of both first and
second.
assertNotEqual(
first, second[, msg])
failIfEqual(
first, second[, msg])
Test that first and second are not equal. If the values
do compare equal, the test will fail with the explanation given by
msg, or None. Note that using failIfEqual()
improves upon doing the comparison as the first parameter to
failUnless() is that the default value for msg can be
computed to include representations of both first and
second.
assertAlmostEqual(
first, second[,
places[, msg]])
failUnlessAlmostEqual(
first, second[,
places[, msg]])
Test that first and second are approximately equal
by computing the difference, rounding to the given number of places,
and comparing to zero. Note that comparing a given number of decimal places
is not the same as comparing a given number of significant digits.
If the values do not compare equal, the test will fail with the explanation
given by msg, or None.
assertNotAlmostEqual(
first, second[,
places[, msg]])
failIfAlmostEqual(
first, second[,
places[, msg]])
Test that first and second are not approximately equal
by computing the difference, rounding to the given number of places,
and comparing to zero. Note that comparing a given number of decimal places
is not the same as comparing a given number of significant digits.
If the values do not compare equal, the test will fail with the explanation
given by msg, or None.
assertRaises(
exception, callable, ...)
failUnlessRaises(
exception, callable, ...)
Test that an exception is raised when callable is called with
any positional or keyword arguments that are also passed to
assertRaises(). The test passes if exception is
raised, is an error if another exception is raised, or fails if no
exception is raised. To catch any of a group of exceptions, a tuple
containing the exception classes may be passed as exception.
failIf(
expr[, msg])
The inverse of the failUnless() method is the
failIf() method. This signals a test failure if expr
is true, with msg or None for the error message.
fail(
[msg])
Signals a test failure unconditionally, with msg or
None for the error message.
failureException
This class attribute gives the exception raised by the
test() method. If a test framework needs to use a
specialized exception, possibly to carry additional information, it
must subclass this exception in order to ``play fair'' with the
framework. The initial value of this attribute is
AssertionError.
Testing frameworks can use the following methods to collect
information on the test:
countTestCases(
)
Return the number of tests represented by this test object. For
TestCase instances, this will always be 1.
defaultTestResult(
)
Return an instance of the test result class that should be used
for this test case class (if no other result instance is provided
to the run() method).
For TestCase instances, this will always be an instance of
TestResult; subclasses of TestCase should
override this as necessary.
id(
)
Return a string identifying the specific test case. This is usually
the full name of the test method, including the module and class
name.
shortDescription(
)
Returns a one-line description of the test, or None if no
description has been provided. The default implementation of this
method returns the first line of the test method's docstring, if
available, or None.
