org.junit.platform.launcher.listeners

Class UniqueIdTrackingListener

java.lang.Object

org.junit.platform.launcher.listeners.UniqueIdTrackingListener

All Implemented Interfaces:

TestExecutionListener

@API(status=EXPERIMENTAL,
     since="1.8")
public class UniqueIdTrackingListener
extends java.lang.Object
implements TestExecutionListener

UniqueIdTrackingListener is a TestExecutionListener that tracks the unique IDs of all tests that were executed during the execution of the TestPlan and generates a file containing the unique IDs once execution of the TestPlan has finished.

Tests are tracked regardless of their TestExecutionResult or whether they were skipped, and the unique IDs are written to an output file, one ID per line, encoding using UTF-8.

The output file can be used to execute the same set of tests again without having to query the user configuration for the test plan and without having to perform test discovery again. This can be useful for test environments such as within a native image — for example, a GraalVM native image — in order to rerun the exact same tests from a standard JVM test run within a native image.

Configuration and Defaults

The OUTPUT_DIR is the directory in which this listener generates the output file. The exact path of the generated file is OUTPUT_DIR/OUTPUT_FILE_PREFIX-<random number>.txt, where <random number> is a pseudo-random number. The inclusion of a random number in the file name ensures that multiple concurrently executing test plans do not overwrite each other's results.

The value of the OUTPUT_FILE_PREFIX defaults to DEFAULT_OUTPUT_FILE_PREFIX, but a custom prefix can be set via the OUTPUT_FILE_PREFIX_PROPERTY_NAME configuration property.

The OUTPUT_DIR can be set to a custom directory via the OUTPUT_DIR_PROPERTY_NAME configuration property. Otherwise the following algorithm is used to select a default output directory.

• If the current working directory of the Java process contains a file named pom.xml, the output directory will be ./target, following the conventions of Maven.
• If the current working directory of the Java process contains a file with the extension .gradle or .gradle.kts, the output directory will be ./build, following the conventions of Gradle.
• Otherwise, the current working directory of the Java process will be used as the output directory.

For example, in a project using Gradle as the build tool, the file generated by this listener would be ./build/junit-platform-unique-ids-<random number>.txt by default.

Configuration properties can be set via JVM system properties, via a junit-platform.properties file in the root of the classpath, or as JUnit Platform configuration parameters.

Since:

1.8

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_OUTPUT_FILE_PREFIX The default prefix for the name of the file generated by the UniqueIdTrackingListener: "junit-platform-unique-ids"
private boolean	enabled
static java.lang.String	LISTENER_ENABLED_PROPERTY_NAME Property name used to enable the UniqueIdTrackingListener: "junit.platform.listeners.uid.tracking.enabled"
private Logger	logger
static java.lang.String	OUTPUT_DIR_PROPERTY_NAME Property name used to set the path to the output directory for the file generated by the UniqueIdTrackingListener: "junit.platform.listeners.uid.tracking.output.dir"
static java.lang.String	OUTPUT_FILE_PREFIX_PROPERTY_NAME Property name used to set the prefix for the name of the file generated by the UniqueIdTrackingListener: "junit.platform.listeners.uid.tracking.output.file.prefix"
private java.util.List<java.lang.String>	uniqueIds

Constructor Summary

Constructors

Constructor and Description
UniqueIdTrackingListener()

Method Summary

Modifier and Type	Method and Description
private java.nio.file.Path	createOutputFile(ConfigurationParameters configurationParameters)
void	executionFinished(TestIdentifier testIdentifier, TestExecutionResult testExecutionResult) Called when the execution of a leaf or subtree of the TestPlan has finished, regardless of the outcome.
void	executionSkipped(TestIdentifier testIdentifier, java.lang.String reason) Called when the execution of a leaf or subtree of the TestPlan has been skipped.
void	testPlanExecutionFinished(TestPlan testPlan) Called when the execution of the TestPlan has finished, after all tests have been executed.
void	testPlanExecutionStarted(TestPlan testPlan) Called when the execution of the TestPlan has started, before any test has been executed.
private void	trackTestUid(TestIdentifier testIdentifier)

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.junit.platform.launcher.TestExecutionListener

dynamicTestRegistered, executionStarted, reportingEntryPublished

Field Detail

LISTENER_ENABLED_PROPERTY_NAME

public static final java.lang.String LISTENER_ENABLED_PROPERTY_NAME

Property name used to enable the UniqueIdTrackingListener: "junit.platform.listeners.uid.tracking.enabled"

The UniqueIdTrackingListener is registered automatically via Java's ServiceLoader mechanism but disabled by default.

Set the value of this property to true to enable this listener.

See Also:

Constant Field Values

OUTPUT_DIR_PROPERTY_NAME

public static final java.lang.String OUTPUT_DIR_PROPERTY_NAME

Property name used to set the path to the output directory for the file generated by the UniqueIdTrackingListener: "junit.platform.listeners.uid.tracking.output.dir"

For details on the default output directory, see the class-level Javadoc.

See Also:

Constant Field Values

OUTPUT_FILE_PREFIX_PROPERTY_NAME

public static final java.lang.String OUTPUT_FILE_PREFIX_PROPERTY_NAME

Property name used to set the prefix for the name of the file generated by the UniqueIdTrackingListener: "junit.platform.listeners.uid.tracking.output.file.prefix"

Defaults to DEFAULT_OUTPUT_FILE_PREFIX.

See Also:

Constant Field Values

DEFAULT_OUTPUT_FILE_PREFIX

public static final java.lang.String DEFAULT_OUTPUT_FILE_PREFIX

The default prefix for the name of the file generated by the UniqueIdTrackingListener: "junit-platform-unique-ids"

See Also:

OUTPUT_FILE_PREFIX_PROPERTY_NAME, Constant Field Values

logger

private final Logger logger

uniqueIds

private final java.util.List<java.lang.String> uniqueIds

enabled

private boolean enabled

Constructor Detail

UniqueIdTrackingListener

public UniqueIdTrackingListener()

Method Detail

testPlanExecutionStarted

public void testPlanExecutionStarted(TestPlan testPlan)

Description copied from interface: TestExecutionListener

Called when the execution of the TestPlan has started, before any test has been executed.

Called from the same thread as TestExecutionListener.testPlanExecutionFinished(TestPlan).

Specified by:

testPlanExecutionStarted in interface TestExecutionListener

Parameters:

testPlan - describes the tree of tests about to be executed

executionSkipped

public void executionSkipped(TestIdentifier testIdentifier,
                             java.lang.String reason)

Description copied from interface: TestExecutionListener

Called when the execution of a leaf or subtree of the TestPlan has been skipped.

The TestIdentifier may represent a test or a container. In the case of a container, no listener methods will be called for any of its descendants.

A skipped test or subtree of tests will never be reported as started or finished.

Specified by:

executionSkipped in interface TestExecutionListener

Parameters:

testIdentifier - the identifier of the skipped test or container

reason - a human-readable message describing why the execution has been skipped

executionFinished

public void executionFinished(TestIdentifier testIdentifier,
                              TestExecutionResult testExecutionResult)

Description copied from interface: TestExecutionListener

Called when the execution of a leaf or subtree of the TestPlan has finished, regardless of the outcome.

The TestIdentifier may represent a test or a container.

This method will only be called if the test or container has not been skipped.

This method will be called for a container TestIdentifier after all of its children have been skipped or have finished.

The TestExecutionResult describes the result of the execution for the supplied TestIdentifier. The result does not include or aggregate the results of its children. For example, a container with a failing test will be reported as SUCCESSFUL even if one or more of its children are reported as FAILED.

Specified by:

executionFinished in interface TestExecutionListener

Parameters:

testIdentifier - the identifier of the finished test or container

testExecutionResult - the (unaggregated) result of the execution for the supplied TestIdentifier

See Also:

TestExecutionResult

trackTestUid

private void trackTestUid(TestIdentifier testIdentifier)

testPlanExecutionFinished

public void testPlanExecutionFinished(TestPlan testPlan)

Description copied from interface: TestExecutionListener

Called when the execution of the TestPlan has finished, after all tests have been executed.

Called from the same thread as TestExecutionListener.testPlanExecutionStarted(TestPlan).

Specified by:

testPlanExecutionFinished in interface TestExecutionListener

Parameters:

testPlan - describes the tree of tests that have been executed

createOutputFile

private java.nio.file.Path createOutputFile(ConfigurationParameters configurationParameters)