twisted/trial/itrial.py

   1 # Copyright (c) Twisted Matrix Laboratories.
   2 # See LICENSE for details.
   3
   4 """
   5 Interfaces for Trial.
   6
   7 Maintainer: Jonathan Lange
   8 """
   9
  10 import zope.interface as zi
  11 from zope.interface import Attribute
  12
  13
  14 class ITestCase(zi.Interface):
  15     """
  16     The interface that a test case must implement in order to be used in Trial.
  17     """
  18
  19     failureException = zi.Attribute(
  20         "The exception class that is raised by failed assertions")
  21
  22
  23     def __call__(result):
  24         """
  25         Run the test. Should always do exactly the same thing as run().
  26         """
  27
  28
  29     def countTestCases():
  30         """
  31         Return the number of tests in this test case. Usually 1.
  32         """
  33
  34
  35     def id():
  36         """
  37         Return a unique identifier for the test, usually the fully-qualified
  38         Python name.
  39         """
  40
  41
  42     def run(result):
  43         """
  44         Run the test, storing the results in C{result}.
  45
  46         @param result: A L{TestResult}.
  47         """
  48
  49
  50     def shortDescription():
  51         """
  52         Return a short description of the test.
  53         """
  54
  55
  56
  57 class IReporter(zi.Interface):
  58     """
  59     I report results from a run of a test suite.
  60     """
  61
  62     stream = zi.Attribute(
  63         "Deprecated in Twisted 8.0. "
  64         "The io-stream that this reporter will write to")
  65     tbformat = zi.Attribute("Either 'default', 'brief', or 'verbose'")
  66     args = zi.Attribute(
  67         "Additional string argument passed from the command line")
  68     shouldStop = zi.Attribute(
  69         """
  70         A boolean indicating that this reporter would like the test run to stop.
  71         """)
  72     separator = Attribute(
  73         "Deprecated in Twisted 8.0. "
  74         "A value which will occasionally be passed to the L{write} method.")
  75     testsRun = Attribute(
  76         """
  77         The number of tests that seem to have been run according to this
  78         reporter.
  79         """)
  80
  81
  82     def startTest(method):
  83         """
  84         Report the beginning of a run of a single test method.
  85
  86         @param method: an object that is adaptable to ITestMethod
  87         """
  88
  89
  90     def stopTest(method):
  91         """
  92         Report the status of a single test method
  93
  94         @param method: an object that is adaptable to ITestMethod
  95         """
  96
  97
  98     def startSuite(name):
  99         """
 100         Deprecated in Twisted 8.0.
 101
 102         Suites which wish to appear in reporter output should call this
 103         before running their tests.
 104         """
 105
 106
 107     def endSuite(name):
 108         """
 109         Deprecated in Twisted 8.0.
 110
 111         Called at the end of a suite, if and only if that suite has called
 112         C{startSuite}.
 113         """
 114
 115
 116     def cleanupErrors(errs):
 117         """
 118         Deprecated in Twisted 8.0.
 119
 120         Called when the reactor has been left in a 'dirty' state
 121
 122         @param errs: a list of L{twisted.python.failure.Failure}s
 123         """
 124
 125
 126     def upDownError(userMeth, warn=True, printStatus=True):
 127         """
 128         Deprecated in Twisted 8.0.
 129
 130         Called when an error occurs in a setUp* or tearDown* method
 131
 132         @param warn: indicates whether or not the reporter should emit a
 133                      warning about the error
 134         @type warn: Boolean
 135         @param printStatus: indicates whether or not the reporter should
 136                             print the name of the method and the status
 137                             message appropriate for the type of error
 138         @type printStatus: Boolean
 139         """
 140
 141
 142     def addSuccess(test):
 143         """
 144         Record that test passed.
 145         """
 146
 147
 148     def addError(test, error):
 149         """
 150         Record that a test has raised an unexpected exception.
 151
 152         @param test: The test that has raised an error.
 153         @param error: The error that the test raised. It will either be a
 154             three-tuple in the style of C{sys.exc_info()} or a
 155             L{Failure<twisted.python.failure.Failure>} object.
 156         """
 157
 158
 159     def addFailure(test, failure):
 160         """
 161         Record that a test has failed with the given failure.
 162
 163         @param test: The test that has failed.
 164         @param failure: The failure that the test failed with. It will
 165             either be a three-tuple in the style of C{sys.exc_info()}
 166             or a L{Failure<twisted.python.failure.Failure>} object.
 167         """
 168
 169
 170     def addExpectedFailure(test, failure, todo):
 171         """
 172         Record that the given test failed, and was expected to do so.
 173
 174         @type test: L{pyunit.TestCase}
 175         @param test: The test which this is about.
 176         @type error: L{failure.Failure}
 177         @param error: The error which this test failed with.
 178         @type todo: L{unittest.Todo}
 179         @param todo: The reason for the test's TODO status.
 180         """
 181
 182
 183     def addUnexpectedSuccess(test, todo):
 184         """
 185         Record that the given test failed, and was expected to do so.
 186
 187         @type test: L{pyunit.TestCase}
 188         @param test: The test which this is about.
 189         @type todo: L{unittest.Todo}
 190         @param todo: The reason for the test's TODO status.
 191         """
 192
 193
 194     def addSkip(test, reason):
 195         """
 196         Record that a test has been skipped for the given reason.
 197
 198         @param test: The test that has been skipped.
 199         @param reason: An object that the test case has specified as the reason
 200             for skipping the test.
 201         """
 202
 203
 204     def printSummary():
 205         """
 206         Deprecated in Twisted 8.0, use L{done} instead.
 207
 208         Present a summary of the test results.
 209         """
 210
 211
 212     def printErrors():
 213         """
 214         Deprecated in Twisted 8.0, use L{done} instead.
 215
 216         Present the errors that have occured during the test run. This method
 217         will be called after all tests have been run.
 218         """
 219
 220
 221     def write(string):
 222         """
 223         Deprecated in Twisted 8.0, use L{done} instead.
 224
 225         Display a string to the user, without appending a new line.
 226         """
 227
 228
 229     def writeln(string):
 230         """
 231         Deprecated in Twisted 8.0, use L{done} instead.
 232
 233         Display a string to the user, appending a new line.
 234         """
 235
 236     def wasSuccessful():
 237         """
 238         Return a boolean indicating whether all test results that were reported
 239         to this reporter were successful or not.
 240         """
 241
 242
 243     def done():
 244         """
 245         Called when the test run is complete.
 246
 247         This gives the result object an opportunity to display a summary of
 248         information to the user. Once you have called C{done} on an
 249         L{IReporter} object, you should assume that the L{IReporter} object is
 250         no longer usable.
 251         """