com.artima.testkit
Interface Reporter

public interface Reporter

Interface implemented by objects that collect test results as the tests execute and report those results.

The term test as used in the testStarting and testCompleted method names is defined vaguely to enable a wide range of test implementations. Class Suite invokes testStarting to indicate it is about to invoke one if its test methods. Class Suite invokes testCompleted to indicate one of its test methods has completed. Although the execution of a Suite's test methods will likely be a common event reported via the testStarting and testCompleted methods, because of the vague definition of "test" used by this interface, the testStarting and testCompleted methods are not limited to this use. Any conceptual test can be reported via the testStarting and testCompleted methods.

Method Summary

void	close() 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.
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.

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.

close

public void close()

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. Classes that implement Reporter are free to interpret the meaning of the passed Config 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 Config 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 com.artima.testkit.Config