JUnit 6.0.1 · org.junit.platform.launcher.Launcher · APIdia, the JavaDoc alternative

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 org.junit.platform.launcher.core.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 org.junit.platform.launcher.core.LauncherFactory#create dynamically discovers test execution listeners via Java's ServiceLoader mechanism.

Method Summary

Modifier and Type	Method and Description
public TestPlan	Returns: an unmodifiable `TestPlan` that contains all resolved identifiers from all registered engines discover(LauncherDiscoveryRequest the launcher discovery request; never `null` discoveryRequest) Discover tests and build a `TestPlan` according to the supplied `LauncherDiscoveryRequest` by querying all registered engines and collecting their results.
public void	execute(LauncherDiscoveryRequest the launcher discovery request; never `null` discoveryRequest, TestExecutionListener... additional test execution listeners; never `null` listeners) 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.
public void	execute(TestPlan the test plan to execute; never `null` testPlan, TestExecutionListener... additional test execution listeners; never `null` listeners) Execute the supplied `TestPlan` and notify registered listeners about the progress and results of the execution.
public void	execute(LauncherExecutionRequest the launcher execution request; never `null` executionRequest) Execute tests according to the supplied `LauncherExecutionRequest` and notify registered listeners about the progress and results of the execution.
public void	registerLauncherDiscoveryListeners(LauncherDiscoveryListener... the listeners to be notified of test discovery events; never `null` or empty listeners) Register one or more listeners for test discovery.
public void	registerTestExecutionListeners(TestExecutionListener... the listeners to be notified of test execution events; never `null` or empty listeners) Register one or more listeners for test execution.

Method Detail

discover back to summary

discover	back to summary
public TestPlan discover(LauncherDiscoveryRequest discoveryRequest) Discover tests and build a `TestPlan` according to the supplied `LauncherDiscoveryRequest` by querying all registered engines and collecting their results. 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. Parameters discoveryRequest:LauncherDiscoveryRequest the launcher discovery request; never `null` Returns:TestPlan an unmodifiable `TestPlan` that contains all resolved identifiers from all registered engines

public TestPlan discover(LauncherDiscoveryRequest discoveryRequest)

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

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.

Parameters

discoveryRequest:LauncherDiscoveryRequest: the launcher discovery request; never null

Returns:TestPlan

an unmodifiable TestPlan that contains all resolved identifiers from all registered engines

execute back to summary

execute	back to summary
public void execute(LauncherDiscoveryRequest discoveryRequest, TestExecutionListener... listeners) 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. 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. Parameters discoveryRequest:LauncherDiscoveryRequest the launcher discovery request; never `null` listeners:TestExecutionListener[] additional test execution listeners; never `null` See Also `execute(TestPlan, TestExecutionListener...)`, `execute(LauncherExecutionRequest)`

public void execute(LauncherDiscoveryRequest discoveryRequest, TestExecutionListener... listeners)

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.

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.

Parameters

discoveryRequest:LauncherDiscoveryRequest: the launcher discovery request; never null
listeners:TestExecutionListener[]: additional test execution listeners; never null

execute back to summary

execute	back to summary
public void execute(TestPlan testPlan, TestExecutionListener... listeners) 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. API Note The supplied `TestPlan` must not have been executed previously. Parameters testPlan:TestPlan the test plan to execute; never `null` listeners:TestExecutionListener[] additional test execution listeners; never `null` Annotations @API status:STABLE since:1.4 Since 1.4 See Also `execute(LauncherDiscoveryRequest, TestExecutionListener...)`, `execute(LauncherExecutionRequest)`

public void execute(TestPlan testPlan, TestExecutionListener... listeners)

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.

API Note

The supplied TestPlan must not have been executed previously.

Parameters

testPlan:TestPlan: the test plan to execute; never null
listeners:TestExecutionListener[]: additional test execution listeners; never null

Annotations

@API
status:STABLE
since:1.4

Since

1.4

execute back to summary

execute	back to summary
public void execute(LauncherExecutionRequest executionRequest) Execute tests according to the supplied `LauncherExecutionRequest` and notify 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. 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. Parameters executionRequest:LauncherExecutionRequest the launcher execution request; never `null` Annotations @API status:MAINTAINED since:6.0 Since 6.0 See Also `execute(LauncherDiscoveryRequest, TestExecutionListener...)`, `execute(TestPlan, TestExecutionListener...)`

public void execute(LauncherExecutionRequest executionRequest)

Execute tests according to the supplied LauncherExecutionRequest and notify 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.

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.

Parameters

executionRequest:LauncherExecutionRequest: the launcher execution request; never null

Annotations

@API
status:MAINTAINED
since:6.0

Since

6.0

registerLauncherDiscoveryListeners back to summary

registerLauncherDiscoveryListeners	back to summary
public void registerLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners) Register one or more listeners for test discovery. Parameters listeners:LauncherDiscoveryListener[] the listeners to be notified of test discovery events; never `null` or empty Annotations @API status:STABLE since:1.10

public void registerLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners)

Parameters

listeners:LauncherDiscoveryListener[]: the listeners to be notified of test discovery events; never null or empty

Annotations

@API
status:STABLE
since:1.10

registerTestExecutionListeners back to summary

registerTestExecutionListeners	back to summary
public void registerTestExecutionListeners(TestExecutionListener... listeners) Register one or more listeners for test execution. Parameters listeners:TestExecutionListener[] the listeners to be notified of test execution events; never `null` or empty

public void registerTestExecutionListeners(TestExecutionListener... listeners)

Parameters

listeners:TestExecutionListener[]: the listeners to be notified of test execution events; never null or empty

public Interface Launcher

Method Summary

Method Detail