|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 Character s. |
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 |
public static final java.lang.Character PRESENT_RUN_STARTING
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.public static final java.lang.Character PRESENT_TEST_STARTING
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.public static final java.lang.Character PRESENT_TEST_FAILED
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.public static final java.lang.Character PRESENT_TEST_SUCCEEDED
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.public static final java.lang.Character PRESENT_SUITE_STARTING
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.public static final java.lang.Character PRESENT_SUITE_ABORTED
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.public static final java.lang.Character PRESENT_SUITE_COMPLETED
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.public static final java.lang.Character PRESENT_INFO_PROVIDED
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.public static final java.lang.Character PRESENT_RUN_STOPPED
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.public static final java.lang.Character PRESENT_RUN_ABORTED
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.public static final java.lang.Character PRESENT_RUN_COMPLETED
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 |
public void runStarting(int testCount)
Class Runner
invokes runStarting
to report
that the first execute
method of a run's starting Suite
s
is about to be invoked.
testCount
- the number of tests expected during this runjava.lang.IllegalArgumentException
- if expectedTestsCount
is less than zero.public void testStarting(Report report)
Class Suite
uses testStarting
to report
that a test method of a Suite
is about to be invoked.
report
- a Report
that encapsulates the test starting event to report.NullPointerException
- if report
reference is null
public void testSucceeded(Report report)
Class Suite
uses testSucceeded
to report
that a test method of a Suite
returned normally
(without throwing an Exception
).
report
- a Report
that encapsulates the test succeeded event to report.NullPointerException
- if report
reference is null
public void testFailed(Report report)
Class Suite
uses testFailed
to report
that a test method of a Suite
completed abruptly with an Exception
.
report
- a Report
that encapsulates the test failed event to report.NullPointerException
- if report
reference is null
public void suiteStarting(Report report)
Classes Suite
and Runner
use suiteStarting
to report
that the execute
method of a Suite
is about to be invoked.
report
- a Report
that encapsulates the suite starting event to report.NullPointerException
- if report
reference is null
public void suiteCompleted(Report report)
Classes Suite
and Runner
use suiteCompleted
to report
that the execute
method of a Suite
has returned normally (without throwing a RuntimeException
).
report
- a Report
that encapsulates the suite completed event to report.NullPointerException
- if report
reference is null
public void suiteAborted(Report report)
Classes Suite
and Runner
use suiteAborted
to report
that the execute
method of a Suite
has completed abruptly with a RuntimeException
.
report
- a Report
that encapsulates the suite aborted event to report.NullPointerException
- if report
reference is null
public void infoProvided(Report report)
Reporter
method.report
- a Report
that encapsulates the event to report.NullPointerException
- if report
reference is null
public void runStopped()
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 Suite
s returns.
public void runAborted(Report report)
Class Runner
invokes runAborted
if the
execute
method of any of the run's starting Suite
s completes
abruptly with a Throwable
.
report
- a Report
that encapsulates the run aborted event to report.NullPointerException
- if report
reference is null
public void runCompleted()
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 Suite
s 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 Suite
s returns.
public void dispose()
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.public void setConfiguration(java.util.Set configs)
Reporter
with a specified Set
of
configuration Character
s. For convenience, the valid configuration
Character
s 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.)
configs
- set of configuration Character
objects that indicate the new
configuration for this Reporter
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.
|
||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |