PreInterruptCallback extension

Added PreInterruptCallback extension to allow to hook into the
@timeout extension before the executing Thread is interrupted.

The default implementation of PreInterruptCallback will simply print
the stacks of all Thread to System.out.
It is disabled by default and must be enabled with:
junit.jupiter.execution.timeout.threaddump.enabled = true

Issue: #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

@@ -83,6 +83,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/ExtensionContext.java

@@ -10,6 +10,7 @@
 
 package org.junit.jupiter.api.extension;
 
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
 import static org.apiguardian.api.API.Status.STABLE;
 
 import java.lang.reflect.AnnotatedElement;
@@ -401,6 +402,17 @@ default void publishReportEntry(String value) {
 	@API(status = STABLE, since = "5.11")
 	ExecutableInvoker getExecutableInvoker();
 
+	/**
+	 * Returns a list of registered extension at this context of the passed {@code extensionType}.
+	 *
+	 * @param <E> the extension type
+	 * @param extensionType the extension type
+	 * @return the list of extensions
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	<E extends Extension> List<E> getExtensions(Class<E> extensionType);
+
 	/**
 	 * {@code Store} provides methods for extensions to save and retrieve data.
 	 */

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

@@ -0,0 +1,58 @@
+/*
+ * 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.
+	 * @since 5.12
+	 * @see PreInterruptContext
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	void beforeThreadInterrupt(PreInterruptContext preInterruptContext) throws Exception;
+}

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

@@ -0,0 +1,44 @@
+/*
+ * 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) 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();
+
+	/**
+	 * Get the current {@link ExtensionContext}.
+	 *
+	 * @return the current extension context; never {@code null}
+	 * @since 5.12
+	 */
+	@API(status = EXPERIMENTAL, since = "5.12")
+	ExtensionContext getExtensionContext();
+}

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,6 @@ 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+.