Interface Launcher

@API(status=STABLE,
     since="1.0")
public interface Launcher

The 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:

• LauncherDiscoveryRequest
• TestPlan
• TestExecutionListener
• LauncherFactory
• TestEngine

Method Summary

Modifier and Type	Method	Description
TestPlan	discover(LauncherDiscoveryRequest launcherDiscoveryRequest)	Discover tests and build a TestPlan according to the supplied LauncherDiscoveryRequest by querying all registered engines and collecting their results.
default void	execute(LauncherDiscoveryRequest launcherDiscoveryRequest, TestExecutionListener... listeners)	Deprecated. Please use execute(LauncherExecutionRequest) instead.
void	execute(LauncherExecutionRequest launcherExecutionRequest)	Execute tests according to the supplied LauncherExecutionRequest registered listeners about the progress and results of the execution.
default void	execute(TestPlan testPlan, TestExecutionListener... listeners)	Deprecated. Please use execute(LauncherExecutionRequest) instead.
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; never null or empty

registerTestExecutionListeners

void registerTestExecutionListeners(TestExecutionListener... listeners)

Register one or more listeners for test execution.

Parameters:

listeners - the listeners to be notified of test execution events; never null or empty

discover

TestPlan discover(LauncherDiscoveryRequest launcherDiscoveryRequest)

Discover tests and build a TestPlan according to the supplied LauncherDiscoveryRequest by querying all registered engines and collecting their results.

Parameters:

launcherDiscoveryRequest - the launcher discovery request; never null

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 to execute(TestPlan, TestExecutionListener...) for execution at most once.

execute

@Deprecated
@API(status=DEPRECATED,
     since="6.0")
default void execute(LauncherDiscoveryRequest launcherDiscoveryRequest,
 TestExecutionListener... listeners)

Deprecated.

Please use execute(LauncherExecutionRequest) instead.

Execute a TestPlan which is built according to the supplied LauncherDiscoveryRequest 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; never null

listeners - additional test execution listeners; never null

API Note:

Calling this method will cause test discovery to be executed for all registered engines. If the same LauncherDiscoveryRequest was previously passed to discover(LauncherDiscoveryRequest), you should instead call execute(TestPlan, TestExecutionListener...) and pass the already acquired TestPlan to avoid the potential performance degradation (e.g., classpath scanning) of running test discovery twice.

execute

@Deprecated
@API(status=DEPRECATED,
     since="6.0")
default void execute(TestPlan testPlan,
 TestExecutionListener... listeners)

Deprecated.

Please use execute(LauncherExecutionRequest) instead.

Execute the supplied TestPlan 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; never null

listeners - additional test execution listeners; never null

Since:

1.4

API Note:

The supplied TestPlan must not have been executed previously.

execute

@API(status=MAINTAINED,
     since="6.0")
void execute(LauncherExecutionRequest launcherExecutionRequest)

Execute tests according to the supplied LauncherExecutionRequest registered listeners about the progress and results of the execution.

Test execution listeners supplied as part of the request are registered in addition to already registered listeners but only for the supplied execution request.

Parameters:

launcherExecutionRequest - the launcher execution request; never null

Since:

6.0

API Note:

If the execution request contains a TestPlan rather than a LauncherDiscoveryRequest, it must not have been executed previously.

If the execution request contains a LauncherDiscoveryRequest, calling this method will cause test discovery to be executed for all registered engines. If the same LauncherDiscoveryRequest was previously passed to discover(LauncherDiscoveryRequest), you should instead provide the resulting TestPlan as part of the supplied execution request to avoid the potential performance degradation (e.g., classpath scanning) of running test discovery twice.