Package org.junit.platform.engine

Interface TestEngine

All Known Implementing Classes:

HierarchicalTestEngine, JupiterTestEngine, VintageTestEngine

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

A TestEngine facilitates discovery and execution of tests for a particular programming model.

For example, JUnit provides a TestEngine that discovers and executes tests written using the JUnit Jupiter programming model.

Every TestEngine must provide its own unique ID, discover tests from EngineDiscoveryRequests, and execute those tests according to ExecutionRequests.

In order to facilitate test discovery within IDEs and tools prior to launching the JUnit Platform, TestEngine implementations are encouraged to make use of the @Testable annotation. For example, the @Test and @TestFactory annotations in JUnit Jupiter are meta-annotated with @Testable. Consult the Javadoc for @Testable for further details.

Since:

1.0

See Also:

EngineDiscoveryRequest, ExecutionRequest, Testable

Method Summary

Modifier and Type	Method	Description
TestDescriptor	discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId)	Discover tests according to the supplied EngineDiscoveryRequest.
void	execute(ExecutionRequest request)	Execute tests according to the supplied ExecutionRequest.
default java.util.Optional<java.lang.String>	getArtifactId()	Get the Artifact ID of the JAR in which this test engine is packaged.
default java.util.Optional<java.lang.String>	getGroupId()	Get the Group ID of the JAR in which this test engine is packaged.
java.lang.String	getId()	Get the ID that uniquely identifies this test engine.
default java.util.Optional<java.lang.String>	getVersion()	Get the version of this test engine.

Method Detail

getId

java.lang.String getId()

Get the ID that uniquely identifies this test engine.

Each test engine must provide a unique ID. For example, JUnit Vintage and JUnit Jupiter use "junit-vintage" and "junit-jupiter", respectively. When in doubt, you may use the fully qualified name of your custom TestEngine implementation class.

discover

TestDescriptor discover(EngineDiscoveryRequest discoveryRequest,
                        UniqueId uniqueId)

Discover tests according to the supplied EngineDiscoveryRequest.

The supplied UniqueId must be used as the unique ID of the returned root TestDescriptor. In addition, the UniqueId must be used to create unique IDs for children of the root's descriptor by calling UniqueId.append(java.lang.String, java.lang.String).

Parameters:

discoveryRequest - the discovery request; never null

uniqueId - the unique ID to be used for this test engine's TestDescriptor; never null

Returns:

the root TestDescriptor of this engine, typically an instance of EngineDescriptor

See Also:

EngineDescriptor

execute

void execute(ExecutionRequest request)

Execute tests according to the supplied ExecutionRequest.

The request passed to this method contains the root TestDescriptor that was previously returned by discover(org.junit.platform.engine.EngineDiscoveryRequest, org.junit.platform.engine.UniqueId), the EngineExecutionListener to be notified of test execution events, and ConfigurationParameters that may influence test execution.

Parameters:

request - the request to execute tests for; never null

getGroupId

default java.util.Optional<java.lang.String> getGroupId()

Get the Group ID of the JAR in which this test engine is packaged.

This information is used solely for debugging and reporting purposes.

The default implementation simply returns an empty Optional, signaling that the group ID is unknown.

Concrete test engine implementations may override this method in order to provide a known group ID.

Returns:

an Optional containing the group ID; never null but potentially empty if the group ID is unknown

See Also:

getArtifactId(), getVersion()

getArtifactId

default java.util.Optional<java.lang.String> getArtifactId()

Get the Artifact ID of the JAR in which this test engine is packaged.

This information is used solely for debugging and reporting purposes.

The default implementation assumes the implementation title is equivalent to the artifact ID and therefore attempts to query the implementation title from the package attributes for the Package in which the engine resides. Note that a package only has attributes if the information is defined in the Manifest of the JAR containing that package, and if the class loader created the Package instance with the attributes from the manifest.

If the implementation title cannot be queried from the package attributes, the default implementation simply returns an empty Optional.

Concrete test engine implementations may override this method in order to determine the artifact ID by some other means.

Returns:

an Optional containing the artifact ID; never null but potentially empty if the artifact ID is unknown

See Also:

Class.getPackage(), Package.getImplementationTitle(), getGroupId(), getVersion()

Implementation Note:

Since JUnit Platform version 1.1 this default implementation returns the "module name" stored in the module (modular jar on the module-path) of this test engine.

getVersion

default java.util.Optional<java.lang.String> getVersion()

Get the version of this test engine.

This information is used solely for debugging and reporting purposes.

Initially, the default implementation tries to retrieve the engine version from the manifest attribute named: "Engine-Version-" + getId()

Then the default implementation attempts to query the implementation version from the package attributes for the Package in which the engine resides. Note that a package only has attributes if the information is defined in the Manifest of the JAR containing that package, and if the class loader created the Package instance with the attributes from the manifest.

If the implementation version cannot be queried from the package attributes, the default implementation returns "DEVELOPMENT".

Concrete test engine implementations may override this method to determine the version by some other means.

implNote: Since JUnit Platform version 1.1 this default implementation honors the "raw version" information stored in the module (modular jar on the module-path) of this test engine.

Returns:

an Optional containing the version; never null but potentially empty if the version is unknown

See Also:

Class.getPackage(), Package.getImplementationVersion(), getGroupId(), getArtifactId()