diff --git a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc index c4978a431362..e1fb5e37efca 100644 --- a/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc +++ b/documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc @@ -173,6 +173,16 @@ former, clients can register custom implementations of `{LauncherInterceptor}` v `junit.platform.launcher.interceptors.enabled` <> to `true`. +[NOTE] +==== +Since interceptors are registered before the test run starts, the +`junit.platform.launcher.interceptors.enabled` _configuration parameter_ can only be +supplied as a JVM system property or via the JUnit Platform configuration file (see +<> for details). This _configuration parameter_ cannot be +supplied in the `LauncherDiscoveryRequest` that is passed to the `{Launcher}`. +==== + + A typical use case is to create a custom interceptor to replace the `ClassLoader` used by the JUnit Platform to load test classes and engine implementations. diff --git a/junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherConstants.java b/junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherConstants.java index da4d81625f6d..5cb30bf8e69d 100644 --- a/junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherConstants.java +++ b/junit-platform-launcher/src/main/java/org/junit/platform/launcher/LauncherConstants.java @@ -92,8 +92,9 @@ public class LauncherConstants { public static final String STDERR_REPORT_ENTRY_KEY = "stderr"; /** - * Property name used to provide patterns for deactivating listeners registered - * via the {@link java.util.ServiceLoader ServiceLoader} mechanism: {@value} + * Property name used to provide patterns for deactivating + * {@linkplain TestExecutionListener listeners} registered via the + * {@link java.util.ServiceLoader ServiceLoader} mechanism: {@value} * *

Pattern Matching Syntax

* @@ -121,6 +122,17 @@ public class LauncherConstants { * {@code org.example.TheirListener}. * * + *

Only listeners registered via the {@code ServiceLoader} mechanism can + * be deactivated. In other words, any listener registered explicitly via the + * {@link LauncherDiscoveryRequest} cannot be deactivated via this + * configuration parameter. + * + *

In addition, since execution listeners are registered before the test + * run starts, this configuration parameter can only be supplied as a JVM + * system property or via the JUnit Platform configuration file but cannot + * be supplied in the {@link LauncherDiscoveryRequest}} that is passed to + * the {@link Launcher}. + * * @see #DEACTIVATE_ALL_LISTENERS_PATTERN * @see org.junit.platform.launcher.TestExecutionListener */ @@ -143,6 +155,11 @@ public class LauncherConstants { * *

By default, interceptor registration is disabled. * + *

Since interceptors are registered before the test run starts, this + * configuration parameter can only be supplied as a JVM system property or + * via the JUnit Platform configuration file but cannot be supplied in the + * {@link LauncherDiscoveryRequest}} that is passed to the {@link Launcher}. + * * @see LauncherInterceptor */ @API(status = EXPERIMENTAL, since = "1.10")