23.3.7 TestResult Objects

##
23.3.7 TestResult Objects

A `TestResult` object stores the results of a set of tests. The `TestCase` and `TestSuite` classes ensure that results are properly recorded; test authors do not need to worry about recording the outcome of tests.

Testing frameworks built on top of `unittest` may want access to the `TestResult` object generated by running a set of tests for reporting purposes; a `TestResult` instance is returned by the `TestRunner.run()` method for this purpose.

`TestResult` instances have the following attributes that will be of interest when inspecting the results of running a set of tests:

`errors`
  A list containing 2-tuples of `TestCase` instances and strings holding formatted tracebacks. Each tuple represents a test which raised an unexpected exception. Changed in version 2.2: Contains formatted tracebacks instead of `sys.exc_info()` results.

`failures`
  A list containing 2-tuples of `TestCase` instances and strings holding formatted tracebacks. Each tuple represents a test where a failure was explicitly signalled using the `TestCase.fail*()` or `TestCase.assert*()` methods. Changed in version 2.2: Contains formatted tracebacks instead of `sys.exc_info()` results.

`testsRun`
  The total number of tests run so far.

`wasSuccessful`( | )

  Returns `True` if all tests run so far have passed, otherwise returns `False`.

`stop`( | )

  This method can be called to signal that the set of tests being run should be aborted by setting the `TestResult`'s `shouldStop` attribute to `True`. `TestRunner` objects should respect this flag and return without running any additional tests.

  For example, this feature is used by the `TextTestRunner` class to stop the test framework when the user signals an interrupt from the keyboard. Interactive tools which provide `TestRunner` implementations can use this in a similar manner.

The following methods of the `TestResult` class are used to maintain the internal data structures, and may be extended in subclasses to support additional reporting requirements. This is particularly useful in building tools which support interactive reporting while tests are being run.

`startTest`( | test)

  Called when the test case test is about to be run.

  The default implementation simply increments the instance's `testsRun` counter.

`stopTest`( | test)

  Called after the test case test has been executed, regardless of the outcome.

  The default implementation does nothing.

`addError`( | test, err)

  Called when the test case test raises an unexpected exception err is a tuple of the form returned by `sys.exc_info()`: `(type, value, traceback)`.

  The default implementation appends `(test, err)` to the instance's `errors` attribute.

`addFailure`( | test, err)

  Called when the test case test signals a failure. err is a tuple of the form returned by `sys.exc_info()`: `(type, value, traceback)`.

  The default implementation appends `(test, err)` to the instance's `failures` attribute.

`addSuccess`( | test)

  Called when the test case test succeeds.

  The default implementation does nothing.