Package org.junit.platform.launcher

Interface TestExecutionListener

All Known Subinterfaces:

CompositeTestExecutionListener.EagerTestExecutionListener, DetailsPrintingListener

All Known Implementing Classes:

CompositeTestExecutionListener, FlatPrintingListener, JUnitPlatformRunnerListener, LoggingListener, StreamInterceptingTestExecutionListener, SummaryGeneratingListener, TestFeedPrintingListener, TreePrintingListener, UniqueIdTrackingListener, VerboseTreePrintingListener

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

Register a concrete implementation of this interface with a Launcher to be notified of events that occur during test execution.

All methods in this interface have empty default implementations. Concrete implementations may therefore override one or more of these methods to be notified of the selected events.

All TestExecutionListener methods are called sequentially. Methods for start events are called in registration order while methods for finish events are called in reverse order. Test case execution won't start before all executionStarted(TestIdentifier) calls have returned.

If an exception is thrown by an implementation of a method of this interface, the exception will be caught and logged unless it is deemed unrecoverable. In consequence, a TestExecutionListener cannot cause test execution to fail or abort it early by throwing an exception.

JUnit provides two example implementations.

• LoggingListener
• SummaryGeneratingListener

Contrary to JUnit 4, test engines are supposed to report events not only for identifiers that represent executable leaves in the test plan but also for all intermediate containers. However, while both the JUnit Vintage and JUnit Jupiter engines comply with this contract, there is no way to guarantee this for third-party engines.

As of JUnit Platform 1.8, a TestExecutionListener can access configuration parameters via the getConfigurationParameters() method in the TestPlan supplied to testPlanExecutionStarted(TestPlan) and testPlanExecutionFinished(TestPlan).

Note on concurrency: testPlanExecutionStarted(TestPlan) and testPlanExecutionFinished(TestPlan) are always called from the same thread. It is safe to assume that there is at most one TestPlan instance at a time. All other methods could be called from different threads concurrently in case one or multiple test engines execute tests in parallel.

Since:

1.0

See Also:

Launcher, TestPlan, TestIdentifier

Method Summary

Modifier and Type	Method	Description
default void	dynamicTestRegistered(TestIdentifier testIdentifier)	Called when a new, dynamic TestIdentifier has been registered.
default void	executionFinished(TestIdentifier testIdentifier, TestExecutionResult testExecutionResult)	Called when the execution of a leaf or subtree of the TestPlan has finished, regardless of the outcome.
default void	executionSkipped(TestIdentifier testIdentifier, java.lang.String reason)	Called when the execution of a leaf or subtree of the TestPlan has been skipped.
default void	executionStarted(TestIdentifier testIdentifier)	Called when the execution of a leaf or subtree of the TestPlan is about to be started.
default void	fileEntryPublished(TestIdentifier testIdentifier, FileEntry file)	Called when a file or directory has been published for the supplied TestIdentifier.
default void	reportingEntryPublished(TestIdentifier testIdentifier, ReportEntry entry)	Called when additional test reporting data has been published for the supplied TestIdentifier.
default void	testPlanExecutionFinished(TestPlan testPlan)	Called when the execution of the TestPlan has finished, after all tests have been executed.
default void	testPlanExecutionStarted(TestPlan testPlan)	Called when the execution of the TestPlan has started, before any test has been executed.

Method Detail

testPlanExecutionStarted

default void testPlanExecutionStarted(TestPlan testPlan)

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

Called from the same thread as testPlanExecutionFinished(TestPlan).

Parameters:

testPlan - describes the tree of tests about to be executed

testPlanExecutionFinished

default void testPlanExecutionFinished(TestPlan testPlan)

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

Called from the same thread as testPlanExecutionStarted(TestPlan).

Parameters:

testPlan - describes the tree of tests that have been executed

dynamicTestRegistered

default void dynamicTestRegistered(TestIdentifier testIdentifier)

Called when a new, dynamic TestIdentifier has been registered.

A dynamic test is a test that is not known a-priori and therefore not contained in the original TestPlan.

Parameters:

testIdentifier - the identifier of the newly registered test or container

executionSkipped

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

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.

Parameters:

testIdentifier - the identifier of the skipped test or container

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

executionStarted

default void executionStarted(TestIdentifier testIdentifier)

Called when the execution of a leaf or subtree of the TestPlan is about to be started.

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 before starting or skipping any of its children.

Parameters:

testIdentifier - the identifier of the started test or container

executionFinished

default void executionFinished(TestIdentifier testIdentifier,
                               TestExecutionResult testExecutionResult)

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.

Parameters:

testIdentifier - the identifier of the finished test or container

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

See Also:

TestExecutionResult

reportingEntryPublished

default void reportingEntryPublished(TestIdentifier testIdentifier,
                                     ReportEntry entry)

Called when additional test reporting data has been published for the supplied TestIdentifier.

Can be called at any time during the execution of a test plan.

Parameters:

testIdentifier - describes the test or container to which the entry pertains

entry - the published ReportEntry

fileEntryPublished

@API(status=MAINTAINED,
     since="1.13.3")
default void fileEntryPublished(TestIdentifier testIdentifier,
                                FileEntry file)

Called when a file or directory has been published for the supplied TestIdentifier.

Can be called at any time during the execution of a test plan.

Parameters:

testIdentifier - describes the test or container to which the entry pertains

file - the published FileEntry

Since:

1.12