Introduce PreInterruptCallback extension point (#3431)

The new extension point allows defines the API for `Extensions` that 
wish to be called prior to invocations of `Thread#interrupt()` by the 
`@Timeout` extension.

When enabled via the
`junit.jupiter.execution.timeout.threaddump.enabled` configuration 
parameter, a default extension implementation that writes a thread dump
to `System.out` is registered.

Resolves #2938.

---------

Co-authored-by: Marc Philipp <[email protected]>

Author: AndreasTu

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -156,6 +156,7 @@ endif::[]
 :TestTemplateInvocationContext:              {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestTemplateInvocationContext.html[TestTemplateInvocationContext]
 :TestTemplateInvocationContextProvider:      {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestTemplateInvocationContextProvider.html[TestTemplateInvocationContextProvider]
 :TestWatcher:                                {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestWatcher.html[TestWatcher]
+:PreInterruptCallback:                       {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/PreInterruptCallback.html[PreInterruptCallback]
 // Jupiter Conditions
 :DisabledForJreRange:                        {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/condition/DisabledForJreRange.html[@DisabledForJreRange]
 :DisabledIf:                                 {javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/condition/DisabledIf.html[@DisabledIf]

documentation/src/docs/asciidoc/release-notes/release-notes-5.12.0-M1.adoc

@@ -90,6 +90,7 @@ JUnit repository on GitHub.
   a test-scoped `ExtensionContext` in `Extension` methods called during test class
   instantiation. This behavior will become the default in future versions of JUnit.
 * `@TempDir` is now supported on test class constructors.
+* Added `PreInterruptCallback`
 
 
 [[release-notes-5.12.0-M1-junit-vintage]]

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

@@ -715,6 +715,15 @@ test methods.
 include::{testDir}/example/exception/MultipleHandlersTestCase.java[tags=user_guide]
 ----
 
+[[extensions-preinterrupt-callback]]
+=== Pre-Interrupt Callback
+
+`{PreInterruptCallback}` defines the API for `Extensions` that wish to react on
+timeouts before the `Thread.interrupt()` is called.
+
+Please refer to <<writing-tests-declarative-timeouts-debugging>> for additional information.
+
+
 [[extensions-intercepting-invocations]]
 === Intercepting Invocations
 

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

@@ -2659,6 +2659,22 @@ asynchronous tests, consider using a dedicated library such as
 link:https://github.com/awaitility/awaitility[Awaitility].
 
 
+[[writing-tests-declarative-timeouts-debugging]]
+===  Debugging Timeouts
+
+Registered <<extensions-preinterrupt-callback>> extensions are called prior to invoking
+`Thread.interrupt()` on the thread that is executing the timed out method. This allows to
+inspect the application state and output additional information that might be helpful for
+diagnosing the cause of a timeout.
+
+
+[[writing-tests-declarative-timeouts-debugging-thread-dump]]
+==== Thread Dump on Timeout
+JUnit registers a default implementation of the <<extensions-preinterrupt-callback>> extension point that
+dumps the stacks of all threads to `System.out` if enabled by setting the
+`junit.jupiter.execution.timeout.threaddump.enabled` configuration parameter to `true`.
+
+
 [[writing-tests-declarative-timeouts-mode]]
 ==== Disable @Timeout Globally
 When stepping through your code in a debug session, a fixed timeout limit may influence

junit-jupiter-api/src/main/java/org/junit/jupiter/api/AssertTimeoutPreemptively.java

@@ -113,7 +113,7 @@ private static <T, E extends Throwable> T resolveFutureAndHandleException(Future
 				cause = new ExecutionTimeoutException("Execution timed out in thread " + thread.getName());
 				cause.setStackTrace(thread.getStackTrace());
 			}
-			throw failureFactory.createTimeoutFailure(timeout, messageSupplier, cause);
+			throw failureFactory.createTimeoutFailure(timeout, messageSupplier, cause, thread);
 		}
 		catch (ExecutionException ex) {
 			throw throwAsUncheckedException(ex.getCause());
@@ -124,7 +124,7 @@ private static <T, E extends Throwable> T resolveFutureAndHandleException(Future
 	}
 
 	private static AssertionFailedError createAssertionFailure(Duration timeout, Supplier<String> messageSupplier,
-			Throwable cause) {
+			Throwable cause, Thread thread) {
 		return assertionFailure() //
 				.message(messageSupplier) //
 				.reason("execution timed out after " + timeout.toMillis() + " ms") //

junit-jupiter-api/src/main/java/org/junit/jupiter/api/Assertions.java

@@ -3662,6 +3662,6 @@ public interface TimeoutFailureFactory<T extends Throwable> {
 		 *
 		 * @return timeout failure; never {@code null}
 		 */
-		T createTimeoutFailure(Duration timeout, Supplier<String> messageSupplier, Throwable cause);
+		T createTimeoutFailure(Duration timeout, Supplier<String> messageSupplier, Throwable cause, Thread testThread);
 	}
 }

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/PreInterruptCallback.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2015-2024 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.jupiter.api.extension;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import org.apiguardian.api.API;
+
+/**
+ * {@code PreInterruptCallback} defines the API for {@link Extension
+ * Extensions} that wish to be called prior to invocations of
+ * {@link Thread#interrupt()} by the {@link org.junit.jupiter.api.Timeout}
+ * extension.
+ *
+ * <p>JUnit registers a default implementation that dumps the stacks of all
+ * {@linkplain Thread threads} to {@code System.out} if the
+ * {@value #THREAD_DUMP_ENABLED_PROPERTY_NAME} configuration parameter is set to
+ * {@code true}.
+ *
+ * @since 5.12
+ * @see org.junit.jupiter.api.Timeout
+ */
+@API(status = EXPERIMENTAL, since = "5.12")
+public interface PreInterruptCallback extends Extension {
+
+	/**
+	 * Property name used to enable dumping the stack of all
+	 * {@linkplain Thread threads} to {@code System.out} when a timeout has occurred.
+	 *
+	 * <p>This behavior is disabled by default.
+	 *
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	String THREAD_DUMP_ENABLED_PROPERTY_NAME = "junit.jupiter.execution.timeout.threaddump.enabled";
+
+	/**
+	 * Callback that is invoked <em>before</em> a {@link Thread} is interrupted with
+	 * {@link Thread#interrupt()}.
+	 *
+	 * <p>Note: There is no guarantee on which {@link Thread} this callback will be
+	 * executed.
+	 *
+	 * @param preInterruptContext the context with the target {@link Thread}, which will get interrupted.
+	 * @param extensionContext the extension context for the callback; never {@code null}
+	 * @since 5.12
+	 * @see PreInterruptContext
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	void beforeThreadInterrupt(PreInterruptContext preInterruptContext, ExtensionContext extensionContext)
+			throws Exception;
+}

junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/PreInterruptContext.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2015-2024 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.jupiter.api.extension;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import org.apiguardian.api.API;
+
+/**
+ * {@code PreInterruptContext} encapsulates the <em>context</em> in which an
+ * {@link PreInterruptCallback#beforeThreadInterrupt(PreInterruptContext, ExtensionContext) beforeThreadInterrupt} method is called.
+ *
+ * @since 5.12
+ * @see PreInterruptCallback
+ */
+@API(status = EXPERIMENTAL, since = "5.12")
+public interface PreInterruptContext {
+
+	/**
+	 * Get the {@link Thread} which will be interrupted.
+	 *
+	 * @return the Thread; never {@code null}
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	Thread getThreadToInterrupt();
+}

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

@@ -108,6 +108,17 @@ public final class Constants {
 	 */
 	public static final String EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME = JupiterConfiguration.EXTENSIONS_AUTODETECTION_ENABLED_PROPERTY_NAME;
 
+	/**
+	 * Property name used to enable dumping the stack of all
+	 * {@linkplain Thread threads} to {@code System.out} when a timeout has occurred.
+	 *
+	 * <p>This behavior is disabled by default.
+	 *
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	public static final String EXTENSIONS_TIMEOUT_THREAD_DUMP_ENABLED_PROPERTY_NAME = JupiterConfiguration.EXTENSIONS_TIMEOUT_THREAD_DUMP_ENABLED_PROPERTY_NAME;
+
 	/**
 	 * Property name used to set the default test instance lifecycle mode: {@value}
 	 *
@@ -192,7 +203,7 @@ public final class Constants {
 	 * <p>When set to {@code false} the underlying fork-join pool will reject
 	 * additional tasks if all available workers are busy and the maximum
 	 * pool-size would be exceeded.
-
+	 *
 	 * <p>Value must either {@code true} or {@code false}; defaults to {@code true}.
 	 *
 	 * <p>Note: This property only takes affect on Java 9+.

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

@@ -68,6 +68,12 @@ public boolean isExtensionAutoDetectionEnabled() {
 			__ -> delegate.isExtensionAutoDetectionEnabled());
 	}
 
+	@Override
+	public boolean isThreadDumpOnTimeoutEnabled() {
+		return (boolean) cache.computeIfAbsent(EXTENSIONS_TIMEOUT_THREAD_DUMP_ENABLED_PROPERTY_NAME,
+			__ -> delegate.isThreadDumpOnTimeoutEnabled());
+	}
+
 	@Override
 	public ExecutionMode getDefaultExecutionMode() {
 		return (ExecutionMode) cache.computeIfAbsent(DEFAULT_EXECUTION_MODE_PROPERTY_NAME,