TestCase (TestHelpers 1.0-SNAPSHOT API)

java.lang.Object
- eu.simuline.testhelpers.TestCase

```
class TestCase
extends Object
```
Represents a test which may be a singular case or a suite during its lifetime from being scheduled to having runned successfully or not. In this respect, the testcase goes beyond a Description. It is a wrapper around a Description desc but includes also the phase given by the quality qual. If the test is a suite, the sub-tests are stored in children. Each test has an index idxTest which identifies the test.
Singular tests may be either Quality.Scheduled, Quality.Started or finished in some sense. If finished, the test may be Quality.Success or it has been interrupted by an exception wrapped in a failure. Also a timestamp time is provided which indicates the running time of a singular test if it has been started and finished.
This class provides a single non-private constructor transforming a description of a test which may be singular or a suite into a hierarchy of TestCases.
The methods are either
- getter methods and their convenience methods like getDesc(), isTest(), testCount(), getChildren(), getIdx(), getQuality(), hasFailed(), getThrown() and getTime().
- The special method fullSuccess() indicating whether this testcase including all testcases succeeded.
- methods triggering phase transitions like setScheduledRec(), setQualStartedIgnored(Quality), setFailure(Failure), setAssumptionFailure(Failure) and setFinished() tied to events given by RunNotifier.
Version:

1.0

Author:

Ernst Reissner

See Also:

Created: Wed Jun 12 16:41:14 2006

Field Summary

Fields
Modifier and Type	Field and Description
`private List<TestCase>`	`children` The list of children if this is a suite according to `isTest()` or `null` if this is a (singular) test.
`private Description`	`desc` The description of this testcase.
`private Failure`	`failure` The failure if any; otherwise `null`.
`private int`	`idxTest` The index of this testcase if this is a (singular) test; otherwise `-1`.
`private Quality`	`qual` The phase of this testcase.
`private long`	`time` If this testcase is a single testcase which has been finished, this is the span of time required to run this test.
`(package private) static long`	`TIME_SCHEDULED`
`private static long`	`TIME_SUITE`

Constructor Summary

Constructors
Modifier	Constructor and Description
`(package private)`	`TestCase(Description desc)` Creates a new testcase based on the description `desc` with indices `0...n-1`, where `n` is the testcout of `desc`.
`private`	`TestCase(Description desc, int idxTest)` Creates a new testcase based on the description `desc` with indices `idxTest...idxTest+n-1`, where `n` is the testcout of `desc`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`(package private) boolean`	`fullSuccess()` Returns whether this test including all sub-tests succeeded.
`(package private) List<TestCase>`	`getChildren()` Returns the list of children given by `children`.
`(package private) Description`	`getDesc()` Returns the description of this testcase given by `desc`.
`(package private) int`	`getIdx()` Returns the index of this testcase as described in `idxTest`.
`(package private) Quality`	`getQuality()` Returns the phase of this testcase as described in `qual`.
`(package private) Throwable`	`getThrown()` Returns `null` if no failure occurred.
`(package private) long`	`getTime()` If this testcase is a single testcase which has been finished, this is the span of time required to run this test.
`(package private) boolean`	`hasFailed()` Returns whether `getThrown()` returns non-`null`.
`(package private) boolean`	`isTest()` Returns whether this testcase is a (singular) test.
`(package private) void`	`setAssumptionFailure(Failure failure)` Triggers a transition of the current phase if the assumption failure `failure` occurs.
`(package private) void`	`setFailure(Failure failure)` Triggers a transition of the current phase if the non-assumption failure `failure` occurs.
`(package private) void`	`setFinished()` Triggers a transition of the current phase given by finishing the run of a singular testcase if possible as specified by `Quality.setFinished()`.
`(package private) void`	`setQualStartedIgnored(Quality qual)` Triggers a transition of the current phase to `qual` if possible; otherwise throws an exception.
`(package private) void`	`setScheduledRec()` Recursively triggers a transition of the current phase to `Quality.Scheduled`: If this is a test, just set `qual` to `Quality.Scheduled` if possible updating `failure` and `time`.
`(package private) int`	`testCount()` Returns the number of singular test in this testcase.
`String`	`toString()` Returns the string representation of `desc` for suites and a representation including `qual` for singular tests.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - desc
```
private final Description desc
```
    The description of this testcase. This may be singular or not.
  - children
```
private final List<TestCase> children
```
    The list of children if this is a suite according to isTest() or null if this is a (singular) test.
  - idxTest
```
private final int idxTest
```
    The index of this testcase if this is a (singular) test; otherwise -1. Each testcase is part of a tree hierarchy in which the singular tests have indices 0...n-1 if there are n singular test.
  - qual
```
private Quality qual
```
    The phase of this testcase. The phase is null iff this testcase is a suite. Otherwise, If this test is singular and newly created, the quality is Quality.Scheduled. State transitions are reigned by Quality.
  - failure
```
private Failure failure
```
    The failure if any; otherwise null. This is null iff
    - this is a test suite according to isTest() and thus qual is null.
    - this is a singular test (thus the phase qual is non-null) and a failure is associated with the phase according to Quality.hasFailure().
  - TIME_SUITE
```
private static final long TIME_SUITE
```
    See Also:
    
    Constant Field Values
  - TIME_SCHEDULED
```
static final long TIME_SCHEDULED
```
    See Also:
    
    Constant Field Values
  - time
```
private long time
```
    If this testcase is a single testcase which has been finished, this is the span of time required to run this test. For single ignored tests, this is 0 and in the other cases, the value is negative. If this testcase is a suite, the result is TIME_SUITE; otherwise if scheduled it is TIME_SCHEDULED, both negative.
    
    See Also:
    
    Quality.setTime(long)
- Constructor Detail
  - TestCase
```
TestCase(Description desc)
```
    Creates a new testcase based on the description desc with indices 0...n-1, where n is the testcout of desc. This testcase is the root of a hierarchy of tests which consists of a single test if desc is singular.
    All singular tests have quality Quality.Scheduled.
    
    Parameters:
    
    desc - a description of this testcase. This may be singular or a test suite.
  - TestCase
```
private TestCase(Description desc,
                 int idxTest)
```
    Creates a new testcase based on the description desc with indices idxTest...idxTest+n-1, where n is the testcout of desc. This testcase is the root of a hierarchy of tests which consists of a single test if desc is singular.
    All singular tests have quality Quality.Scheduled.
    
    Parameters:
    
    desc - a description of this testcase. This may be singular or a test suite.
    
    idxTest - the minimal index of the (singular) tests to be created. To create the root of
- Method Detail
  - getDesc
```
Description getDesc()
```
    Returns the description of this testcase given by desc. This may be singular or not.
    
    Returns:
    
    desc.
  - isTest
```
boolean isTest()
```
    Returns whether this testcase is a (singular) test. Otherwise it is a testsuite. This is a frequently used convenience method.
    
    Returns:
    
    this testcase is a (singular) test.
    
    See Also:
    
    Description.isTest()
  - testCount
```
int testCount()
```
    Returns the number of singular test in this testcase. This is 1 iff this is a singular test according to isTest(). This is a convenience method used once.
    
    Returns:
    
    the number of singular test in this testcase.
    
    See Also:
    
    Description.testCount()
  - getChildren
```
List<TestCase> getChildren()
```
    Returns the list of children given by children.
    Returns:
    null if this is a test suite according to isTest().
    the list of children of this suite otherwise.
  - getIdx
```
int getIdx()
```
    Returns the index of this testcase as described in idxTest.
    Returns:
    -1 if this is a test suite according to isTest().
    a number 0...n-1 if this is one of n singular tests.
  - getQuality
```
Quality getQuality()
```
    Returns the phase of this testcase as described in qual.
    Returns:
    null if this is a test suite according to isTest().
    a non-null value otherwise.
  - hasFailed
```
boolean hasFailed()
```
    Returns whether getThrown() returns non-null. For singular tests, returns the same value as Quality.hasFailure() applied to qual. This is a convenience method.
    
    Returns:
    
    whether getThrown() returns non-null.
    
    See Also:
    
    getThrown()
  - getThrown
```
Throwable getThrown()
```
    Returns null if no failure occurred. It returns non-null iff qual is Quality.Error, Quality.Failure or Quality.Invalidated. In particular, it returns null if qual is null.
    
    Returns:
    
    the throwable defined by failure if this is non-null, otherwise the throwable defined by Failure.getException().
    
    See Also:
    
    Failure.getException()
  - getTime
```
long getTime()
```
    If this testcase is a single testcase which has been finished, this is the span of time required to run this test. For single ignored tests, this is 0 and in the other cases, the value is negative. If this testcase is a suite, the result is -3.
    
    Returns:
    
    time
    
    See Also:
    
    Quality.setTime(long)
  - fullSuccess
```
boolean fullSuccess()
```
    Returns whether this test including all sub-tests succeeded.
    
    Returns:
    
    whether this test including all sub-tests succeeded.
  - setScheduledRec
```
void setScheduledRec()
```
    Recursively triggers a transition of the current phase to Quality.Scheduled: If this is a test, just set qual to Quality.Scheduled if possible updating failure and time. If this is a suite, go recursively into the children.
    
    Throws:
    
    IllegalStateException - if it is not allowed to set the phase to Quality.Scheduled according to Quality.setScheduled().
  - setQualStartedIgnored
```
void setQualStartedIgnored(Quality qual)
```
    Triggers a transition of the current phase to qual if possible; otherwise throws an exception.
    Parameters:
    
    qual - either Quality.Started or Quality.Ignored.
    
    Throws:
    IllegalStateException -
    
    if qual is neither Quality.Started nor Quality.Ignored and in particular if it is null .
    if qual does not allow the transition to qual.
    NullPointerException - if this is a test suite and thus qual is null.
  - setFailure
```
void setFailure(Failure failure)
```
    Triggers a transition of the current phase if the non-assumption failure failure occurs. This presupposes that this is a singular test and that the current phase is Quality.Started. The new phase is either Quality.Failure or Quality.Error depending on whether the thrown throwable is an AssertionError (should be AssertionFailedError).
    
    Parameters:
    
    failure - a failure representing either a proper failure or an error but not an assumption failure.
    
    Throws:
    
    IllegalStateException - if failure represents an AssumptionViolatedException via Failure.getException().
    
    IllegalStateException - if failure does not represent an AssumptionViolatedException, this is a singular test and qual does not allow the transition given by a failure failure, i.e. qual is not Quality.Started.
    
    NullPointerException - if failure does not represent an AssumptionViolatedException and this is a test suite and thus qual is null.
    
    See Also:
    
    setAssumptionFailure(Failure), Quality.setFailure(Throwable)
  - setAssumptionFailure
```
void setAssumptionFailure(Failure failure)
```
    Triggers a transition of the current phase if the assumption failure failure occurs. This presupposes that this is a singular test and that the current phase is Quality.Started. The new phase is Quality.Invalidated.
    
    Parameters:
    
    failure - a failure representing a failed assumption.
    
    Throws:
    
    IllegalStateException - if failure does not represent an AssumptionViolatedException via Failure.getException().
    
    IllegalStateException - if failure represents an AssumptionViolatedException, this is a singlar test and qual does not allow the transition to Quality.Invalidated.
    
    NullPointerException - if failure represents an AssumptionViolatedException and this is a test suite and thus qual is null.
    
    See Also:
    
    setFailure(Failure)
  - setFinished
```
void setFinished()
```
    Triggers a transition of the current phase given by finishing the run of a singular testcase if possible as specified by Quality.setFinished(). The new phase is
    - remains unchanged for phases Quality.Failure, Quality.Invalidated and Quality.Error
    - Quality.Success for current phase Quality.Started.
    Note that this sets time to the time required to run this testcase.
    Throws:
    
    IllegalStateException - if this is a singular test and qual does not allow the transition by finishing a test case. This is the case for states Quality.Scheduled, Quality.Success and Quality.Ignored.
    
    NullPointerException - if this is a test suite and thus qual is null.
    
    See Also:
    
    setFailure(Failure)
  - toString
```
public String toString()
```
    Returns the string representation of desc for suites and a representation including qual for singular tests.
    
    Overrides:
    
    toString in class Object

Class TestCase

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

desc

children

idxTest

qual

failure

TIME_SUITE

TIME_SCHEDULED

time

Constructor Detail

TestCase

TestCase

Method Detail

getDesc

isTest

testCount

getChildren

getIdx

getQuality

hasFailed

getThrown

getTime

fullSuccess

setScheduledRec

setQualStartedIgnored

setFailure

setAssumptionFailure

setFinished

toString