Implement include and exclude filtering when calling registerAutoDetectedExtensions in MutableExtensionRegistry

documentation/src/docs/asciidoc/user-guide/extensions.adoc

@@ -289,6 +289,20 @@ Specifically, a custom extension can be registered by supplying its fully qualif
 name in a file named `org.junit.jupiter.api.extension.Extension` within the
 `/META-INF/services` folder in its enclosing JAR file.
 
+[[automatic-extension-registration-pattern-matching]]
+===== Pattern Matching Syntax
+
+Pattern matching syntax is used to automatically detect and register extensions. Here are some examples of pattern matching syntax:
+
+- `*`: includes all extensions.
+- `org.junit.*`: includes every extension under the `org.junit` base package and any of its subpackages.
+- `*.MyExtension`: includes every extension whose simple class name is exactly `MyExtension`.
+- `*System*`: includes every extension whose FQCN contains `System`.
+- `*System*, *Dev*`: includes every extension whose FQCN contains `System` or `Dev`.
+- `org.example.MyExtension, org.example.TheirExtension`: includes extensions whose FQCN is exactly `org.example.MyExtension` or `org.example.TheirExtension`.
+
+> **Note**: A class that matches both an inclusion and exclusion pattern will be excluded.
+
 [[extensions-registration-automatic-enabling]]
 ===== Enabling Automatic Extension Detection
 
@@ -368,7 +382,7 @@ following system property.
 [[extensions-conditions-deactivation-patterns]]
 ===== Pattern Matching Syntax
 
-Refer to <<running-tests-config-params-deactivation-pattern>> for details.
+Pattern matching syntax is used to automatically detect and register extensions. For more details, refer to the <<automatic-extension-registration-pattern-matching,Pattern Matching Syntax>> section.
 
 [[extensions-test-instance-pre-construct-callback]]
 === Test Instance Pre-construct Callback

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/Constants.java

@@ -80,6 +80,8 @@ public final class Constants {
 	 * {@code org.example.TheirExtension}.
 	 * </ul>
 	 *
+	 * <p>Note: A class that matches both an inclusion and exclusion pattern will be excluded.
+	 *
 	 * @see JupiterConfiguration#EXTENSIONS_AUTODETECTION_INCLUDE_PROPERTY_NAME
 	 */
 	public static final String EXTENSIONS_AUTODETECTION_INCLUDE_PROPERTY_NAME = JupiterConfiguration.EXTENSIONS_AUTODETECTION_INCLUDE_PROPERTY_NAME;
@@ -115,6 +117,8 @@ public final class Constants {
 	 * {@code org.example.TheirExtension}.
 	 * </ul>
 	 *
+	 * <p>Note: A class that matches both an inclusion and exclusion pattern will be excluded.
+	 *
 	 * @see JupiterConfiguration#EXTENSIONS_AUTODETECTION_EXCLUDE_PROPERTY_NAME
 	 */
 	public static final String EXTENSIONS_AUTODETECTION_EXCLUDE_PROPERTY_NAME = JupiterConfiguration.EXTENSIONS_AUTODETECTION_EXCLUDE_PROPERTY_NAME;

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/CachingJupiterConfiguration.java

@@ -49,8 +49,8 @@ public CachingJupiterConfiguration(JupiterConfiguration delegate) {
 	}
 
 	@Override
-	public Predicate<Class<? extends Extension>> createExtensionFilterByPatterns() {
-		return delegate.createExtensionFilterByPatterns();
+	public Predicate<Class<? extends Extension>> getFilterForAutoDetectedExtensions() {
+		return delegate.getFilterForAutoDetectedExtensions();
 	}
 
 	@Override

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/DefaultJupiterConfiguration.java

@@ -79,7 +79,7 @@ public DefaultJupiterConfiguration(ConfigurationParameters configurationParamete
 	}
 
 	@Override
-	public Predicate<Class<? extends Extension>> createExtensionFilterByPatterns() {
+	public Predicate<Class<? extends Extension>> getFilterForAutoDetectedExtensions() {
 		Predicate<String> predicate = ClassNamePatternFilterUtils.includeMatchingClassNames(
 			getExtensionAutodetectionIncludePattern().orElse(ClassNamePatternFilterUtils.ALL_PATTERN)) //
 				.and(ClassNamePatternFilterUtils.excludeMatchingClassNames(

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/config/JupiterConfiguration.java

@@ -52,7 +52,7 @@ public interface JupiterConfiguration {
 	String DEFAULT_TEST_CLASS_ORDER_PROPERTY_NAME = ClassOrderer.DEFAULT_ORDER_PROPERTY_NAME;;
 	String DEFAULT_TEST_INSTANTIATION_EXTENSION_CONTEXT_SCOPE_PROPERTY_NAME = ExtensionContextScope.DEFAULT_SCOPE_PROPERTY_NAME;
 
-	Predicate<Class<? extends Extension>> createExtensionFilterByPatterns();
+	Predicate<Class<? extends Extension>> getFilterForAutoDetectedExtensions();
 
 	Optional<String> getRawConfigurationParameter(String key);
 

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/extension/MutableExtensionRegistry.java

@@ -29,6 +29,7 @@
 import java.util.Set;
 import java.util.function.Function;
 import java.util.function.Predicate;
+import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 import org.apiguardian.api.API;
@@ -97,12 +98,34 @@ public static MutableExtensionRegistry createRegistryWithDefaultExtensions(Jupit
 
 	private static void registerAutoDetectedExtensions(MutableExtensionRegistry extensionRegistry,
 			JupiterConfiguration configuration) {
-		Predicate<Class<? extends Extension>> filter = configuration.createExtensionFilterByPatterns();
+		Predicate<Class<? extends Extension>> filter = configuration.getFilterForAutoDetectedExtensions();
 
 		ServiceLoader<Extension> serviceLoader = ServiceLoader.load(Extension.class,
 			ClassLoaderUtils.getDefaultClassLoader());
 		ServiceLoaderUtils.filter(serviceLoader, filter) //
 				.forEach(extensionRegistry::registerAutoDetectedExtension);
+
+		logExcludedExtensions(serviceLoader, filter);
+	}
+
+	private static void logExcludedExtensions(ServiceLoader<Extension> serviceLoader,
+			Predicate<Class<? extends Extension>> filter) {
+		List<Class<? extends Extension>> excludeExtensions = new ArrayList<>();
+		serviceLoader.forEach(extension -> {
+			if (!filter.test(extension.getClass())) {
+				excludeExtensions.add(extension.getClass());
+			}
+		});
+
+		if (!excludeExtensions.isEmpty()) {
+			// @formatter:off
+			List<String> excludeExtensionNames = excludeExtensions
+					.stream()
+					.map(Class::getName)
+					.collect(Collectors.toList());
+			// @formatter:on
+			logger.config(() -> String.format("Excluded auto-detected extensions: %s", excludeExtensionNames));
+		}
 	}
 
 	/**

jupiter-tests/src/test/java/org/junit/jupiter/engine/extension/ExtensionRegistryTests.java

@@ -60,7 +60,7 @@ void newRegistryWithoutParentHasDefaultExtensions() {
 	void newRegistryWithoutParentHasDefaultExtensionsPlusAutodetectedExtensionsLoadedViaServiceLoader() {
 
 		when(configuration.isExtensionAutoDetectionEnabled()).thenReturn(true);
-		when(configuration.createExtensionFilterByPatterns()).thenReturn(__ -> true);
+		when(configuration.getFilterForAutoDetectedExtensions()).thenReturn(__ -> true);
 		registry = createRegistryWithDefaultExtensions(configuration);
 
 		List<Extension> extensions = registry.getExtensions(Extension.class);