org.suiterunner
Interface Reporter

public interface Reporter

Interface implemented by classes whose instances collect the results of a running suite of tests and presents those results in some way to the user.

Classes that implement Reporter (reporter classes) receive test results via eleven report methods. Each report method is invoked to pass a particular kind of report to the reporter. The report methods are:

• runStarting
• testStarting
• testSucceeded
• testFailed
• suiteStarting
• suiteCompleted
• suiteAborted
• infoProvided
• runStopped
• runAborted
• runCompleted

Reporter classes will receive all reports generated by a running suite of tests, but may be designed or configured to ignore some of them. For example, you could define a reporter class whose suiteStarting method does nothing. Such a class would always ignore suiteStarting reports. Alternatively, you could define a reporter class that either presents suiteStarting reports to the user, or ignores them, depending on the reporter's configuration.

For each report method there exists a configuration character. You can use these eleven configuration characters to configure reporters. The configuration characters appear in command line parameters of the Runner application, in recipe files, and in the configuration Set passed to reporter's setConfiguration method. The configuration characters are:

• Y - present runStarting method invocations
• Z - present testStarting method invocations
• T - present testSucceeded method invocations
• F - present testFailed method invocations
• U - present suiteStarting method invocations
• P - present suiteCompleted method invocations
• B - present suiteAborted method invocations
• I - present infoProvided method invocations
• S - present runStopped method invocations
• A - present runAborted method invocations
• R - present runCompleted method invocations

Reporters can be configured via their setConfiguration method, which takes a Set parameter that contains configuration characters, represented as instances of the wrapper type java.lang.Character. By invoking setConfiguration, a client suggests to the reporter that it present any reports whose configuration characters appear in the passed Set, and ignore any reports whose configuration characters do not appear in the Set.

Classes that implement Reporter define what it means to "present" and "ignore" configuration characters in their setConfiguration method. For example, a reporter may be unconfigurable and do nothing in response to an invocation of its setConfiguration method. Or, a reporter may be partly configurable, such that it allow some kinds of reports to be configured via the setConfiguration method, but not others. Such a reporter might be designed, for example, so that testFailed method invocations can never be configured to be ignored, but that testStarting method invocations may be configured to be either ignored or presented.

For convenience, interface Reporter defines all configuration characters as java.lang.Character constants. For example, Reporter.PRESENT_TEST_FAILED has the value new Character('F').

Each class that implements Reporter has a default configuration that it may assume on construction and must assume when its setConfiguration method is invoked with an empty configuration Set.

The term test as used in the testStarting, testSucceeded, and testFailed method names is defined abstractly to enable a wide range of test implementations. Class Suite invokes testStarting to indicate it is about to invoke one of its test methods, testSucceeded to indicate a test method returned normally, and testFailed to indicate a test method completed abruptly with an exception. Although the execution of a Suite's test methods will likely be a common event reported via the testStarting, testSucceeded, and testFailed methods, because of the abstract definition of "test" used by this interface, these methods are not limited to this use. Information about any conceptual test may be reported via the testStarting, testSucceeded, and testFailed methods.

Likewise, the term suite as used in the suiteStarting, suiteAborted, and suiteCompleted method names is defined abstractly to enable a wide range of suite implementations. Class Runner invokes suiteStarting to indicate it is about to invoke execute on a Suite, suiteCompleted to indicate a Suite's execute method returned normally, and suiteAborted to indicate a Suite's execute method completed abruptly with an exception. Similarly, class Suite invokes suiteStarting to indicate it is about to invoke execute on a sub-Suite, suiteCompleted to indicate a sub-Suite's execute method returned normally, and suiteAborted to indicate a sub-Suite's execute method completed abruptly with an exception. Although the execution of a Suite's execute method will likely be a common event reported via the suiteStarting, suiteAborted, and suiteCompleted methods, because of the abstract definition of "suite" used by this interface, these methods are not limited to this use. Information about any conceptual suite may be reported via the suiteStarting, suiteAborted, and suiteCompleted methods.

Author:

Bill Venners

Field Summary

static java.lang.Character	PRESENT_INFO_PROVIDED Configuration Character that indicates infoProvided method invocations should be presented to the user.
static java.lang.Character	PRESENT_RUN_ABORTED Configuration Character that indicates runAborted method invocations should be presented to the user.
static java.lang.Character	PRESENT_RUN_COMPLETED Configuration Character that indicates runCompleted method invocations should be presented to the user.
static java.lang.Character	PRESENT_RUN_STARTING Configuration Character that indicates runStarting method invocations should be presented to the user.
static java.lang.Character	PRESENT_RUN_STOPPED Configuration Character that indicates runComleted method invocations should be presented to the user.
static java.lang.Character	PRESENT_SUITE_ABORTED Configuration Character that indicates suiteAborted method invocations should be presented to the user.
static java.lang.Character	PRESENT_SUITE_COMPLETED Configuration Character that indicates suiteCompleted method invocations should be presented to the user.
static java.lang.Character	PRESENT_SUITE_STARTING Configuration Character that indicates suiteStarting method invocations should be presented to the user.
static java.lang.Character	PRESENT_TEST_FAILED Configuration Character that indicates testFailed method invocations should be presented to the user.
static java.lang.Character	PRESENT_TEST_STARTING Configuration Character that indicates testStarting method invocations should be presented to the user.
static java.lang.Character	PRESENT_TEST_SUCCEEDED Configuration Character that indicates testSucceeded method invocations should be presented to the user.

Method Summary

void	dispose() Release any non-memory finite resources, such as file handles, held by this Reporter.
void	infoProvided(Report report) Provides information that is not appropriate to report via any other Reporter method.
void	runAborted(Report report) Indicates a runner encountered an error while attempting to run a suite of tests.
void	runCompleted() Indicates a runner has completed running a suite of tests.
void	runStarting(int testCount) Indicates a runner is about run a suite of tests.
void	runStopped() Indicates a runner has stopped running a suite of tests prior to completion, likely because of a stop request.
void	setConfiguration(java.util.Set configs) Configures this Reporter with a specified Set of configuration Characters.
void	suiteAborted(Report report) Indicates the execution of a suite of tests has aborted, likely because of an error, prior to completion.
void	suiteCompleted(Report report) Indicates a suite of tests has completed executing.
void	suiteStarting(Report report) Indicates a suite of tests is about to start executing.
void	testFailed(Report report) Indicates a suite (or other entity) has completed running a test that failed.
void	testStarting(Report report) Indicates a suite (or other entity) is about to start a test.
void	testSucceeded(Report report) Indicates a suite (or other entity) has completed running a test that succeeded.

Field Detail

PRESENT_RUN_STARTING

public static final java.lang.Character PRESENT_RUN_STARTING

Configuration Character that indicates runStarting method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_TEST_STARTING

public static final java.lang.Character PRESENT_TEST_STARTING

Configuration Character that indicates testStarting method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_TEST_FAILED

public static final java.lang.Character PRESENT_TEST_FAILED

Configuration Character that indicates testFailed method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_TEST_SUCCEEDED

public static final java.lang.Character PRESENT_TEST_SUCCEEDED

Configuration Character that indicates testSucceeded method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_SUITE_STARTING

public static final java.lang.Character PRESENT_SUITE_STARTING

Configuration Character that indicates suiteStarting method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_SUITE_ABORTED

public static final java.lang.Character PRESENT_SUITE_ABORTED

Configuration Character that indicates suiteAborted method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_SUITE_COMPLETED

public static final java.lang.Character PRESENT_SUITE_COMPLETED

Configuration Character that indicates suiteCompleted method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_INFO_PROVIDED

public static final java.lang.Character PRESENT_INFO_PROVIDED

Configuration Character that indicates infoProvided method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_RUN_STOPPED

public static final java.lang.Character PRESENT_RUN_STOPPED

Configuration Character that indicates runComleted method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_RUN_ABORTED

public static final java.lang.Character PRESENT_RUN_ABORTED

Configuration Character that indicates runAborted method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

PRESENT_RUN_COMPLETED

public static final java.lang.Character PRESENT_RUN_COMPLETED

Configuration Character that indicates runCompleted method invocations should be presented to the user. This Character may appear in the configs Set passed to the setConfiguration method of classes that implement this interface.

Method Detail

runStarting

public void runStarting(int testCount)

Indicates a runner is about run a suite of tests.

Class Runner invokes runStarting to report that the first execute method of a run's starting Suites is about to be invoked.

Parameters:

testCount - the number of tests expected during this run

Throws:

java.lang.IllegalArgumentException - if expectedTestsCount is less than zero.

testStarting

public void testStarting(Report report)

Indicates a suite (or other entity) is about to start a test.

Class Suite uses testStarting to report that a test method of a Suite is about to be invoked.

Parameters:

report - a Report that encapsulates the test starting event to report.

Throws:

NullPointerException - if report reference is null

testSucceeded

public void testSucceeded(Report report)

Indicates a suite (or other entity) has completed running a test that succeeded.

Class Suite uses testSucceeded to report that a test method of a Suite returned normally (without throwing an Exception).

Parameters:

report - a Report that encapsulates the test succeeded event to report.

Throws:

NullPointerException - if report reference is null

testFailed

public void testFailed(Report report)

Indicates a suite (or other entity) has completed running a test that failed.

Class Suite uses testFailed to report that a test method of a Suite completed abruptly with an Exception.

Parameters:

report - a Report that encapsulates the test failed event to report.

Throws:

NullPointerException - if report reference is null

suiteStarting

public void suiteStarting(Report report)

Indicates a suite of tests is about to start executing.

Classes Suite and Runner use suiteStarting to report that the execute method of a Suite is about to be invoked.

Parameters:

report - a Report that encapsulates the suite starting event to report.

Throws:

NullPointerException - if report reference is null

suiteCompleted

public void suiteCompleted(Report report)

Indicates a suite of tests has completed executing.

Classes Suite and Runner use suiteCompleted to report that the execute method of a Suite has returned normally (without throwing a RuntimeException).

Parameters:

report - a Report that encapsulates the suite completed event to report.

Throws:

NullPointerException - if report reference is null

suiteAborted

public void suiteAborted(Report report)

Indicates the execution of a suite of tests has aborted, likely because of an error, prior to completion.

Classes Suite and Runner use suiteAborted to report that the execute method of a Suite has completed abruptly with a RuntimeException.

Parameters:

report - a Report that encapsulates the suite aborted event to report.

Throws:

NullPointerException - if report reference is null

infoProvided

public void infoProvided(Report report)

Provides information that is not appropriate to report via any other Reporter method.

Parameters:

report - a Report that encapsulates the event to report.

Throws:

NullPointerException - if report reference is null

runStopped

public void runStopped()

Indicates a runner has stopped running a suite of tests prior to completion, likely because of a stop request.

Class Suite has a static method setStopRequested, which takes a boolean parameter. If false is passed to setStopRequested while a Suite of tests is running, the execute method of all Suite's should promptly return even if they haven't finished running all of their tests.

If a stop is requested via Suite's static setStopRequested method, class Runner invokes runStopped when the execute method of the run's starting Suite returns. If a stop is not requested, class Runner invokes runCompleted when the last execute method of the run's starting Suites returns.

runAborted

public void runAborted(Report report)

Indicates a runner encountered an error while attempting to run a suite of tests.

Class Runner invokes runAborted if the execute method of any of the run's starting Suites completes abruptly with a Throwable.

Parameters:

report - a Report that encapsulates the run aborted event to report.

Throws:

NullPointerException - if report reference is null

runCompleted

public void runCompleted()

Indicates a runner has completed running a suite of tests.

Class Suite has a static method setStopRequested, which takes a boolean parameter. If false is passed to setStopRequested while a Suite of tests is running, the execute method of all Suite's should promptly return even if they haven't finished running all of their tests.

Class Runner invokes runFinished when the last execute method of the run's starting Suites returns, unless a stop is requested. If a stop is requested via Suite's static setStopRequested method, class Runner invokes runStopped when the last execute method of the run's starting Suites returns.

dispose

public void dispose()

Release any non-memory finite resources, such as file handles, held by this Reporter. Clients should call this method when they no longer need the Reporter, before releasing the last reference to the Reporter. After this method is invoked, the Reporter may be defunct, and therefore not usable anymore. If the Reporter holds no resources, it may do nothing when this method is invoked.

setConfiguration

public void setConfiguration(java.util.Set configs)

Configures this Reporter with a specified Set of configuration Characters. For convenience, the valid configuration Characters are defined as constants in interface Reporter, for example, Reporter.PRESENT_TEST_FAILED and Reporter.PRESENT_RUN_COMPLETED. The setConfiguration method must accept any Character objects containing a valid configuration character, not only the particular Character objects defined as constants in Reporter.

Classes that implement Reporter are free to interpret the meaning of the passed configuration Character objects in any way, including ignoring some or all of them. If the specified configs set is zero size, the Reporter will be configured to its default configuration. (A default configuration is defined individually for each individual Reporter implementation class.)

Parameters:

configs - set of configuration Character objects that indicate the new configuration for this Reporter

Throws:

NullPointerException - if configs reference is null

java.lang.IllegalArgumentException - if configs set contains any objects whose class isn't java.lang.Character, or if any java.lang.Character objects contain a non configuration character.