Document limitations of interceptor enabling configuration parameter

Resolves #3877.
junit-team · Aug 11, 2024 · c17fc9c · c17fc9c
1 parent 418131f
commit c17fc9c
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 2 deletions.
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
@@ -173,6 +173,16 @@ former, clients can register custom implementations of `{LauncherInterceptor}` v
 `junit.platform.launcher.interceptors.enabled` <<running-tests-config-params,
 configuration parameter>> 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
+<<running-tests-config-params>> 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
@@ -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}
 	 *
 	 * <h4>Pattern Matching Syntax</h4>
 	 *
@@ -121,6 +122,17 @@ public class LauncherConstants {
 	 * {@code org.example.TheirListener}.
 	 * </ul>
 	 *
+	 * <p>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.
+	 *
+	 * <p>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 {
 	 *
 	 * <p>By default, interceptor registration is disabled.
 	 *
+	 * <p>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")