Module org.junit.platform.testkit

Package org.junit.platform.testkit.engine

Class EngineTestKit

java.lang.Object

org.junit.platform.testkit.engine.EngineTestKit

@API(status=MAINTAINED,
     since="1.7")
public final class EngineTestKit
extends Object

EngineTestKit provides support for discovering and executing tests for a given TestEngine and provides convenient access to the results.

For discovery, EngineDiscoveryResults provides access to the TestDescriptor of the engine and any DiscoveryIssues that were encountered.

For execution, EngineExecutionResults provides a fluent API to verify the expected results.

Since:

1.4

See Also:

• engine(String)
• engine(TestEngine)
• discover(String, LauncherDiscoveryRequest)
• discover(TestEngine, LauncherDiscoveryRequest)
• execute(String, LauncherDiscoveryRequest)
• execute(TestEngine, LauncherDiscoveryRequest)
• EngineDiscoveryResults
• EngineExecutionResults

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	EngineTestKit.Builder	TestEngine execution builder.

Method Summary

Modifier and Type	Method	Description
static EngineDiscoveryResults	discover(String engineId, LauncherDiscoveryRequest discoveryRequest)	Discover tests for the given LauncherDiscoveryRequest using the TestEngine with the supplied ID.
static EngineDiscoveryResults	discover(TestEngine testEngine, LauncherDiscoveryRequest discoveryRequest)	Discover tests for the given LauncherDiscoveryRequest using the supplied TestEngine.
static EngineTestKit.Builder	engine(String engineId)	Create an execution EngineTestKit.Builder for the TestEngine with the supplied ID.
static EngineTestKit.Builder	engine(TestEngine testEngine)	Create an execution EngineTestKit.Builder for the supplied TestEngine.
static EngineExecutionResults	execute(String engineId, EngineDiscoveryRequest discoveryRequest)	Deprecated. Please use execute(String, LauncherDiscoveryRequest) instead.
static EngineExecutionResults	execute(String engineId, LauncherDiscoveryRequest discoveryRequest)	Execute tests for the given LauncherDiscoveryRequest using the TestEngine with the supplied ID.
static EngineExecutionResults	execute(TestEngine testEngine, EngineDiscoveryRequest discoveryRequest)	Deprecated. Please use execute(TestEngine, LauncherDiscoveryRequest) instead.
static EngineExecutionResults	execute(TestEngine testEngine, LauncherDiscoveryRequest discoveryRequest)	Execute tests for the given LauncherDiscoveryRequest using the supplied TestEngine.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

engine

public static EngineTestKit.Builder engine(String engineId)

Create an execution EngineTestKit.Builder for the TestEngine with the supplied ID.

The TestEngine will be loaded via Java's ServiceLoader mechanism, analogous to the manner in which test engines are loaded in the JUnit Platform Launcher API.

Example Usage

 EngineTestKit
     .engine("junit-jupiter")
     .selectors(selectClass(MyTests.class))
     .execute()
     .testEvents()
     .assertStatistics(stats -> stats.started(2).finished(2));
 

Parameters:

engineId - the ID of the TestEngine to use; must not be null or blank

Returns:

the engine execution Builder

Throws:

PreconditionViolationException - if the supplied ID is null or blank, or if the TestEngine with the supplied ID cannot be loaded

See Also:

• engine(TestEngine)
• execute(String, LauncherDiscoveryRequest)
• execute(TestEngine, LauncherDiscoveryRequest)

engine

public static EngineTestKit.Builder engine(TestEngine testEngine)

Create an execution EngineTestKit.Builder for the supplied TestEngine.

Example Usage

 EngineTestKit
     .engine(new MyTestEngine())
     .selectors(selectClass(MyTests.class))
     .execute()
     .testEvents()
     .assertStatistics(stats -> stats.started(2).finished(2));
 

Parameters:

testEngine - the TestEngine to use; must not be null

Returns:

the engine execution Builder

Throws:

PreconditionViolationException - if the TestEngine is null

See Also:

• engine(String)
• execute(String, LauncherDiscoveryRequest)
• execute(TestEngine, LauncherDiscoveryRequest)

discover

@API(status=EXPERIMENTAL,
     since="1.13")
public static EngineDiscoveryResults discover(String engineId,
 LauncherDiscoveryRequest discoveryRequest)

Discover tests for the given LauncherDiscoveryRequest using the TestEngine with the supplied ID.

The TestEngine will be loaded via Java's ServiceLoader mechanism, analogous to the manner in which test engines are loaded in the JUnit Platform Launcher API.

LauncherDiscoveryRequestBuilder provides a convenient way to build an appropriate discovery request to supply to this method. As an alternative, consider using engine(TestEngine) for a more fluent API.

Parameters:

engineId - the ID of the TestEngine to use; must not be null or blank

discoveryRequest - the LauncherDiscoveryRequest to use

Returns:

the results of the discovery

Throws:

PreconditionViolationException - for invalid arguments or if the TestEngine with the supplied ID cannot be loaded

Since:

1.13

See Also:

• discover(TestEngine, LauncherDiscoveryRequest)
• engine(String)
• engine(TestEngine)

discover

@API(status=EXPERIMENTAL,
     since="1.13")
public static EngineDiscoveryResults discover(TestEngine testEngine,
 LauncherDiscoveryRequest discoveryRequest)

Discover tests for the given LauncherDiscoveryRequest using the supplied TestEngine.

LauncherDiscoveryRequestBuilder provides a convenient way to build an appropriate discovery request to supply to this method. As an alternative, consider using engine(TestEngine) for a more fluent API.

Parameters:

testEngine - the TestEngine to use; must not be null

discoveryRequest - the EngineDiscoveryResults to use; must not be null

Returns:

the recorded EngineExecutionResults

Throws:

PreconditionViolationException - for invalid arguments

Since:

1.13

See Also:

• discover(String, LauncherDiscoveryRequest)
• engine(String)
• engine(TestEngine)

execute

@Deprecated
@API(status=DEPRECATED,
     since="1.7")
public static EngineExecutionResults execute(String engineId,
 EngineDiscoveryRequest discoveryRequest)

Deprecated.

Please use execute(String, LauncherDiscoveryRequest) instead.

Execute tests for the given EngineDiscoveryRequest using the TestEngine with the supplied ID.

The TestEngine will be loaded via Java's ServiceLoader mechanism, analogous to the manner in which test engines are loaded in the JUnit Platform Launcher API.

Note that LauncherDiscoveryRequest from the junit-platform-launcher module is a subtype of EngineDiscoveryRequest. It is therefore quite convenient to make use of the DSL provided in LauncherDiscoveryRequestBuilder to build an appropriate discovery request to supply to this method. As an alternative, consider using engine(String) for a more fluent API.

Parameters:

engineId - the ID of the TestEngine to use; must not be null or blank

discoveryRequest - the EngineDiscoveryRequest to use

Returns:

the results of the execution

Throws:

PreconditionViolationException - for invalid arguments or if the TestEngine with the supplied ID cannot be loaded

See Also:

• execute(String, LauncherDiscoveryRequest)
• engine(String)
• engine(TestEngine)

execute

public static EngineExecutionResults execute(String engineId,
 LauncherDiscoveryRequest discoveryRequest)

Execute tests for the given LauncherDiscoveryRequest using the TestEngine with the supplied ID.

The TestEngine will be loaded via Java's ServiceLoader mechanism, analogous to the manner in which test engines are loaded in the JUnit Platform Launcher API.

LauncherDiscoveryRequestBuilder provides a convenient way to build an appropriate discovery request to supply to this method. As an alternative, consider using engine(TestEngine) for a more fluent API.

Parameters:

engineId - the ID of the TestEngine to use; must not be null or blank

discoveryRequest - the LauncherDiscoveryRequest to use

Returns:

the results of the execution

Throws:

PreconditionViolationException - for invalid arguments or if the TestEngine with the supplied ID cannot be loaded

Since:

1.7

See Also:

• execute(TestEngine, LauncherDiscoveryRequest)
• engine(String)
• engine(TestEngine)

execute

@Deprecated
@API(status=DEPRECATED,
     since="1.7")
public static EngineExecutionResults execute(TestEngine testEngine,
 EngineDiscoveryRequest discoveryRequest)

Deprecated.

Please use execute(TestEngine, LauncherDiscoveryRequest) instead.

Execute tests for the given EngineDiscoveryRequest using the supplied TestEngine.

Note that LauncherDiscoveryRequest from the junit-platform-launcher module is a subtype of EngineDiscoveryRequest. It is therefore quite convenient to make use of the DSL provided in LauncherDiscoveryRequestBuilder to build an appropriate discovery request to supply to this method. As an alternative, consider using engine(TestEngine) for a more fluent API.

Parameters:

testEngine - the TestEngine to use; must not be null

discoveryRequest - the EngineDiscoveryRequest to use; must not be null

Returns:

the recorded EngineExecutionResults

Throws:

PreconditionViolationException - for invalid arguments

See Also:

• execute(TestEngine, LauncherDiscoveryRequest)
• engine(String)
• engine(TestEngine)

execute

public static EngineExecutionResults execute(TestEngine testEngine,
 LauncherDiscoveryRequest discoveryRequest)

Execute tests for the given LauncherDiscoveryRequest using the supplied TestEngine.

LauncherDiscoveryRequestBuilder provides a convenient way to build an appropriate discovery request to supply to this method. As an alternative, consider using engine(TestEngine) for a more fluent API.

Parameters:

testEngine - the TestEngine to use; must not be null

discoveryRequest - the LauncherDiscoveryRequest to use; must not be null

Returns:

the recorded EngineExecutionResults

Throws:

PreconditionViolationException - for invalid arguments

Since:

1.7

See Also:

• execute(String, LauncherDiscoveryRequest)
• engine(String)
• engine(TestEngine)