Fix support for JVM shutdown hooks (#4474)

When the `ConsoleLauncher` is executed via its `main` method while
passing arguments via its `-cp` option, it no longer closes the custom
class loader it creates eagerly after test discovery or execution.
Instead, it relies on the JVM shutdown to free up any resource held by
the class loader which is initiated by calling `System.exit` directly
afterward.

Fixes #4469.

Author: marcphilipp

documentation/src/docs/asciidoc/release-notes/release-notes-5.13.0-M3.adoc

@@ -29,7 +29,10 @@ repository on GitHub.
 [[release-notes-5.13.0-M3-junit-platform-bug-fixes]]
 ==== Bug Fixes
 
-* ❓
+* Reintroduce support for JVM shutdown hooks when using the `-cp`/`--classpath` option of
+  the `ConsoleLauncher`. Prior to this release, the created class loader was closed prior
+  to JVM shutdown hooks being invoked, which caused hooks to fail with a
+  `ClassNotFoundException` when loading classes during shutdown.
 
 [[release-notes-5.13.0-M3-junit-platform-deprecations-and-breaking-changes]]
 ==== Deprecations and Breaking Changes

junit-platform-console/src/main/java/org/junit/platform/console/ConsoleLauncher.java

@@ -19,6 +19,7 @@
 import org.junit.platform.console.options.CommandFacade;
 import org.junit.platform.console.options.CommandResult;
 import org.junit.platform.console.tasks.ConsoleTestExecutor;
+import org.junit.platform.console.tasks.CustomClassLoaderCloseStrategy;
 
 /**
  * The {@code ConsoleLauncher} is a stand-alone application for launching the
@@ -30,17 +31,20 @@
 public class ConsoleLauncher {
 
 	public static void main(String... args) {
-		CommandResult<?> result = newCommandFacade().run(args);
+		CommandFacade facade = newCommandFacade(CustomClassLoaderCloseStrategy.KEEP_OPEN);
+		CommandResult<?> result = facade.run(args);
 		System.exit(result.getExitCode());
 	}
 
 	@API(status = INTERNAL, since = "1.0")
 	public static CommandResult<?> run(PrintWriter out, PrintWriter err, String... args) {
-		return newCommandFacade().run(args, out, err);
+		CommandFacade facade = newCommandFacade(CustomClassLoaderCloseStrategy.CLOSE_AFTER_CALLING_LAUNCHER);
+		return facade.run(args, out, err);
 	}
 
-	private static CommandFacade newCommandFacade() {
-		return new CommandFacade(ConsoleTestExecutor::new);
+	private static CommandFacade newCommandFacade(CustomClassLoaderCloseStrategy classLoaderCleanupStrategy) {
+		return new CommandFacade((discoveryOptions, outputOptions) -> new ConsoleTestExecutor(discoveryOptions,
+			outputOptions, classLoaderCleanupStrategy));
 	}
 
 }

junit-platform-console/src/main/java/org/junit/platform/console/tasks/ConsoleTestExecutor.java

@@ -50,31 +50,48 @@ public class ConsoleTestExecutor {
 	private final TestDiscoveryOptions discoveryOptions;
 	private final TestConsoleOutputOptions outputOptions;
 	private final Supplier<Launcher> launcherSupplier;
+	private final CustomClassLoaderCloseStrategy classLoaderCloseStrategy;
 
 	public ConsoleTestExecutor(TestDiscoveryOptions discoveryOptions, TestConsoleOutputOptions outputOptions) {
-		this(discoveryOptions, outputOptions, LauncherFactory::create);
+		this(discoveryOptions, outputOptions, CustomClassLoaderCloseStrategy.CLOSE_AFTER_CALLING_LAUNCHER);
+	}
+
+	public ConsoleTestExecutor(TestDiscoveryOptions discoveryOptions, TestConsoleOutputOptions outputOptions,
+			CustomClassLoaderCloseStrategy classLoaderCloseStrategy) {
+		this(discoveryOptions, outputOptions, classLoaderCloseStrategy, LauncherFactory::create);
 	}
 
 	// for tests only
 	ConsoleTestExecutor(TestDiscoveryOptions discoveryOptions, TestConsoleOutputOptions outputOptions,
 			Supplier<Launcher> launcherSupplier) {
+		this(discoveryOptions, outputOptions, CustomClassLoaderCloseStrategy.CLOSE_AFTER_CALLING_LAUNCHER,
+			launcherSupplier);
+	}
+
+	private ConsoleTestExecutor(TestDiscoveryOptions discoveryOptions, TestConsoleOutputOptions outputOptions,
+			CustomClassLoaderCloseStrategy classLoaderCloseStrategy, Supplier<Launcher> launcherSupplier) {
 		this.discoveryOptions = discoveryOptions;
 		this.outputOptions = outputOptions;
 		this.launcherSupplier = launcherSupplier;
+		this.classLoaderCloseStrategy = classLoaderCloseStrategy;
 	}
 
 	public void discover(PrintWriter out) {
-		new CustomContextClassLoaderExecutor(createCustomClassLoader()).invoke(() -> {
+		createCustomContextClassLoaderExecutor().invoke(() -> {
 			discoverTests(out);
 			return null;
 		});
 	}
 
 	public TestExecutionSummary execute(PrintWriter out, Optional<Path> reportsDir) {
-		return new CustomContextClassLoaderExecutor(createCustomClassLoader()) //
+		return createCustomContextClassLoaderExecutor() //
 				.invoke(() -> executeTests(out, reportsDir));
 	}
 
+	private CustomContextClassLoaderExecutor createCustomContextClassLoaderExecutor() {
+		return new CustomContextClassLoaderExecutor(createCustomClassLoader(), classLoaderCloseStrategy);
+	}
+
 	private void discoverTests(PrintWriter out) {
 		Launcher launcher = launcherSupplier.get();
 		Optional<DetailsPrintingListener> commandLineTestPrinter = createDetailsPrintingListener(out);

junit-platform-console/src/main/java/org/junit/platform/console/tasks/CustomClassLoaderCloseStrategy.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package org.junit.platform.console.tasks;
+
+import static org.apiguardian.api.API.Status.INTERNAL;
+
+import org.apiguardian.api.API;
+import org.junit.platform.commons.JUnitException;
+
+/**
+ * Defines the strategy for closing custom class loaders created for test
+ * discovery and execution.
+ */
+@API(status = INTERNAL, since = "1.13")
+public enum CustomClassLoaderCloseStrategy {
+
+	/**
+	 * Close the custom class loader after calling the
+	 * {@link org.junit.platform.launcher.Launcher} for test discovery or
+	 * execution.
+	 */
+	CLOSE_AFTER_CALLING_LAUNCHER {
+
+		@Override
+		public void handle(ClassLoader customClassLoader) {
+			if (customClassLoader instanceof AutoCloseable) {
+				close((AutoCloseable) customClassLoader);
+			}
+		}
+
+		private void close(AutoCloseable customClassLoader) {
+			try {
+				customClassLoader.close();
+			}
+			catch (Exception e) {
+				throw new JUnitException("Failed to close custom class loader", e);
+			}
+		}
+	},
+
+	/**
+	 * Rely on the JVM to release resources held by the custom class loader when
+	 * it terminates.
+	 *
+	 * <p>This mode is only safe to use when calling {@link System#exit(int)}
+	 * afterward.
+	 */
+	KEEP_OPEN {
+		@Override
+		public void handle(ClassLoader customClassLoader) {
+			// do nothing
+		}
+	};
+
+	/**
+	 * Handle the class loader according to the strategy.
+	 */
+	public abstract void handle(ClassLoader classLoader);
+
+}

junit-platform-console/src/main/java/org/junit/platform/console/tasks/CustomContextClassLoaderExecutor.java

@@ -13,17 +13,22 @@
 import java.util.Optional;
 import java.util.function.Supplier;
 
-import org.junit.platform.commons.JUnitException;
-
 /**
  * @since 1.0
  */
 class CustomContextClassLoaderExecutor {
 
 	private final Optional<ClassLoader> customClassLoader;
+	private final CustomClassLoaderCloseStrategy closeStrategy;
 
 	CustomContextClassLoaderExecutor(Optional<ClassLoader> customClassLoader) {
+		this(customClassLoader, CustomClassLoaderCloseStrategy.CLOSE_AFTER_CALLING_LAUNCHER);
+	}
+
+	CustomContextClassLoaderExecutor(Optional<ClassLoader> customClassLoader,
+			CustomClassLoaderCloseStrategy closeStrategy) {
 		this.customClassLoader = customClassLoader;
+		this.closeStrategy = closeStrategy;
 	}
 
 	<T> T invoke(Supplier<T> supplier) {
@@ -43,18 +48,7 @@ private <T> T replaceThreadContextClassLoaderAndInvoke(ClassLoader customClassLo
 		}
 		finally {
 			Thread.currentThread().setContextClassLoader(originalClassLoader);
-			if (customClassLoader instanceof AutoCloseable) {
-				close((AutoCloseable) customClassLoader);
-			}
-		}
-	}
-
-	private static void close(AutoCloseable customClassLoader) {
-		try {
-			customClassLoader.close();
-		}
-		catch (Exception e) {
-			throw new JUnitException("Failed to close custom class loader", e);
+			closeStrategy.handle(customClassLoader);
 		}
 	}
 

platform-tests/src/test/java/org/junit/platform/console/tasks/CustomContextClassLoaderExecutorTests.java

@@ -11,6 +11,7 @@
 package org.junit.platform.console.tasks;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertSame;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -28,7 +29,7 @@
 class CustomContextClassLoaderExecutorTests {
 
 	@Test
-	void invokeWithoutCustomClassLoaderDoesNotSetClassLoader() throws Exception {
+	void invokeWithoutCustomClassLoaderDoesNotSetClassLoader() {
 		var originalClassLoader = Thread.currentThread().getContextClassLoader();
 		var executor = new CustomContextClassLoaderExecutor(Optional.empty());
 
@@ -42,7 +43,7 @@ void invokeWithoutCustomClassLoaderDoesNotSetClassLoader() throws Exception {
 	}
 
 	@Test
-	void invokeWithCustomClassLoaderSetsCustomAndResetsToOriginal() throws Exception {
+	void invokeWithCustomClassLoaderSetsCustomAndResetsToOriginal() {
 		var originalClassLoader = Thread.currentThread().getContextClassLoader();
 		ClassLoader customClassLoader = URLClassLoader.newInstance(new URL[0]);
 		var executor = new CustomContextClassLoaderExecutor(Optional.of(customClassLoader));
@@ -57,7 +58,7 @@ void invokeWithCustomClassLoaderSetsCustomAndResetsToOriginal() throws Exception
 	}
 
 	@Test
-	void invokeWithCustomClassLoaderAndEnsureItIsClosedAfterUsage() throws Exception {
+	void invokeWithCustomClassLoaderAndEnsureItIsClosedAfterUsage() {
 		var closed = new AtomicBoolean(false);
 		ClassLoader localClassLoader = new URLClassLoader(new URL[0]) {
 			@Override
@@ -73,4 +74,23 @@ public void close() throws IOException {
 		assertEquals(4711, result);
 		assertTrue(closed.get());
 	}
+
+	@Test
+	void invokeWithCustomClassLoaderAndKeepItOpenAfterUsage() {
+		var closed = new AtomicBoolean(false);
+		ClassLoader localClassLoader = new URLClassLoader(new URL[0]) {
+			@Override
+			public void close() throws IOException {
+				closed.set(true);
+				super.close();
+			}
+		};
+		var executor = new CustomContextClassLoaderExecutor(Optional.of(localClassLoader),
+			CustomClassLoaderCloseStrategy.KEEP_OPEN);
+
+		int result = executor.invoke(() -> 4711);
+
+		assertEquals(4711, result);
+		assertFalse(closed.get());
+	}
 }

platform-tooling-support-tests/projects/standalone/src/other/OtherwiseNotReferencedClass.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2015-2025 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package other;
+
+public class OtherwiseNotReferencedClass {
+}

platform-tooling-support-tests/projects/standalone/src/standalone/JupiterIntegration.java

@@ -19,6 +19,9 @@ class JupiterIntegration {
 
 	@Test
 	void successful() {
+		Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+			new other.OtherwiseNotReferencedClass();
+		}));
 	}
 
 	@Test