Launcher
API is the main entry point for client code that
wishes to discover and execute tests using one or more
test engines.
Implementations of this interface are responsible for determining
the set of test engines to delegate to at runtime and for ensuring that
each test engine has an
ID that is unique
among the registered test engines. For example, the default implementation
returned by LauncherFactory.create()
dynamically discovers test engines via Java's ServiceLoader
mechanism.
Test discovery and execution require a LauncherDiscoveryRequest
that is passed to all registered engines. Each engine decides which tests it
can discover and execute according to the supplied request.
Prior to executing tests, clients of this interface should
register one or more
TestExecutionListener
instances in order to get feedback about the
progress and results of test execution. Listeners will be notified of events
in the order in which they were registered. The default implementation
returned by LauncherFactory.create()
dynamically discovers test execution listeners via Java's
ServiceLoader
mechanism.
- Since:
- 1.0
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptiondiscover
(LauncherDiscoveryRequest launcherDiscoveryRequest) Discover tests and build aTestPlan
according to the suppliedLauncherDiscoveryRequest
by querying all registered engines and collecting their results.void
execute
(LauncherDiscoveryRequest launcherDiscoveryRequest, TestExecutionListener... listeners) Execute aTestPlan
which is built according to the suppliedLauncherDiscoveryRequest
by querying all registered engines and collecting their results, and notify registered listeners about the progress and results of the execution.void
execute
(TestPlan testPlan, TestExecutionListener... listeners) Execute the suppliedTestPlan
and notify registered listeners about the progress and results of the execution.void
registerLauncherDiscoveryListeners
(LauncherDiscoveryListener... listeners) Register one or more listeners for test discovery.void
registerTestExecutionListeners
(TestExecutionListener... listeners) Register one or more listeners for test execution.
-
Method Details
-
registerLauncherDiscoveryListeners
@API(status=STABLE, since="1.10") void registerLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners) Register one or more listeners for test discovery.- Parameters:
listeners
- the listeners to be notified of test discovery events; nevernull
or empty
-
registerTestExecutionListeners
Register one or more listeners for test execution.- Parameters:
listeners
- the listeners to be notified of test execution events; nevernull
or empty
-
discover
Discover tests and build aTestPlan
according to the suppliedLauncherDiscoveryRequest
by querying all registered engines and collecting their results.- Parameters:
launcherDiscoveryRequest
- the launcher discovery request; nevernull
- Returns:
- an unmodifiable
TestPlan
that contains all resolved identifiers from all registered engines - API Note:
- This method may be called to generate a preview of the test
tree. The resulting
TestPlan
is unmodifiable and may be passed toexecute(TestPlan, TestExecutionListener...)
for execution at most once.
-
execute
Execute aTestPlan
which is built according to the suppliedLauncherDiscoveryRequest
by querying all registered engines and collecting their results, and notify registered listeners about the progress and results of the execution.Supplied test execution listeners are registered in addition to already registered listeners but only for the supplied launcher discovery request.
- Parameters:
launcherDiscoveryRequest
- the launcher discovery request; nevernull
listeners
- additional test execution listeners; nevernull
- API Note:
- Calling this method will cause test discovery to be executed for
all registered engines. If the same
LauncherDiscoveryRequest
was previously passed todiscover(LauncherDiscoveryRequest)
, you should instead callexecute(TestPlan, TestExecutionListener...)
and pass the already acquiredTestPlan
to avoid the potential performance degradation (e.g., classpath scanning) of running test discovery twice.
-
execute
@API(status=STABLE, since="1.4") void execute(TestPlan testPlan, TestExecutionListener... listeners) Execute the suppliedTestPlan
and notify registered listeners about the progress and results of the execution.Supplied test execution listeners are registered in addition to already registered listeners but only for the execution of the supplied test plan.
- Parameters:
testPlan
- the test plan to execute; nevernull
listeners
- additional test execution listeners; nevernull
- Since:
- 1.4
- API Note:
- The supplied
TestPlan
must not have been executed previously.
-