Using Listeners and Interceptors

The JUnit Platform provides the following listener APIs that allow JUnit, third parties, and custom user code to react to events fired at various points during the discovery and execution of a TestPlan.

LauncherSessionListener: receives events when a LauncherSession is opened and closed.
LauncherInterceptor: intercepts test discovery and execution in the context of a LauncherSession.
LauncherDiscoveryListener: receives events that occur during test discovery.
TestExecutionListener: receives events that occur during test execution.

The LauncherSessionListener API is typically implemented by build tools or IDEs and registered automatically for you in order to support some feature of the build tool or IDE.

The LauncherDiscoveryListener and TestExecutionListener APIs are often implemented in order to produce some form of report or to display a graphical representation of the test plan in an IDE. Such listeners may be implemented and automatically registered by a build tool or IDE, or they may be included in a third-party library – potentially registered for you automatically. You can also implement and register your own listeners.

For details on registering and configuring listeners, see the following sections of this guide.

The JUnit Platform provides the following listeners which you may wish to use with your test suite.

JUnit Platform Reporting: LegacyXmlReportGeneratingListener can be used via the Console Launcher or registered manually to generate XML reports compatible with the de facto standard for JUnit 4 based test reports.

OpenTestReportGeneratingListener generates an XML report in the event-based format specified by Open Test Reporting. It is auto-registered and can be enabled and configured via Configuration Parameters.

See JUnit Platform Reporting for details.
Flight Recorder Support: FlightRecordingExecutionListener and FlightRecordingDiscoveryListener that generate Java Flight Recorder events during test discovery and execution.
LoggingListener: TestExecutionListener for logging informational messages for all events via a BiConsumer that consumes Throwable and Supplier<String>.
SummaryGeneratingListener: TestExecutionListener that generates a summary of the test execution which can be printed via a PrintWriter.
UniqueIdTrackingListener: TestExecutionListener that that tracks the unique IDs of all tests that were skipped or executed during the execution of the TestPlan and generates a file containing the unique IDs once execution of the TestPlan has finished.

Flight Recorder Support

Since version 1.7, the JUnit Platform provides opt-in support for generating Flight Recorder events. JEP 328 describes the Java Flight Recorder (JFR) as:

Flight Recorder records events originating from applications, the JVM, and the OS. Events are stored in a single file that can be attached to bug reports and examined by support engineers, allowing after-the-fact analysis of issues in the period leading up to a problem.

In order to record Flight Recorder events generated while running tests, you need to:

Ensure that you are using either Java 8 Update 262 or higher or Java 11 or later.
Provide the org.junit.platform.jfr module (junit-platform-jfr-1.14.2-SNAPSHOT.jar) on the class-path or module-path at test runtime.
Start flight recording when launching a test suite. Flight Recorder can be started via java command line option:
```
-XX:StartFlightRecording:filename=...
```

Please consult the manual of your build tool for the appropriate commands.

To analyze the recorded events, use the jfr command line tool shipped with recent JDKs or open the recording file with JDK Mission Control.

Flight Recorder support is currently an experimental feature. You’re invited to give it a try and provide feedback to the JUnit team so they can improve and eventually promote this feature.