- All Known Implementing Classes:
HierarchicalTestEngine
,JupiterTestEngine
,SuiteTestEngine
,VintageTestEngine
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:
-
Method Summary
Modifier and TypeMethodDescriptiondiscover
(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) Discover tests according to the suppliedEngineDiscoveryRequest
.void
execute
(ExecutionRequest request) Execute tests according to the suppliedExecutionRequest
.Get the Artifact ID of the JAR in which this test engine is packaged.Get the Group ID of the JAR in which this test engine is packaged.getId()
Get the ID that uniquely identifies this test engine.Get the version of this test engine.
-
Method Details
-
getId
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 customTestEngine
implementation class.- Returns:
- the ID of this test engine; never
null
or blank
-
discover
Discover tests according to the suppliedEngineDiscoveryRequest
.The supplied
UniqueId
must be used as the unique ID of the returned rootTestDescriptor
. In addition, theUniqueId
must be used to create unique IDs for children of the root's descriptor by callingUniqueId.append(java.lang.String, java.lang.String)
.- Parameters:
discoveryRequest
- the discovery request; nevernull
uniqueId
- the unique ID to be used for this test engine'sTestDescriptor
; nevernull
- Returns:
- the root
TestDescriptor
of this engine, typically an instance ofEngineDescriptor
- See Also:
-
execute
Execute tests according to the suppliedExecutionRequest
.The
request
passed to this method contains the rootTestDescriptor
that was previously returned bydiscover(org.junit.platform.engine.EngineDiscoveryRequest, org.junit.platform.engine.UniqueId)
, theEngineExecutionListener
to be notified of test execution events, andConfigurationParameters
that may influence test execution.- Parameters:
request
- the request to execute tests for; nevernull
-
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 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; nevernull
but potentially empty if the group ID is unknown - See Also:
-
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 theManifest
of the JAR containing that package, and if the class loader created thePackage
instance with the attributes from the manifest.If the implementation title cannot be queried from the package attributes, the default implementation 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; nevernull
but potentially empty if the artifact ID is unknown - See Also:
- 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
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 theManifest
of the JAR containing that package, and if the class loader created thePackage
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; nevernull
but potentially empty if the version is unknown - See Also:
-