Add TestMethodReturnValueHandler SPI for non-void @Test methods

documentation/antora.yml

@@ -212,6 +212,7 @@ asciidoc:
     TestInstancePreDestroyCallback: '{javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestInstancePreDestroyCallback.html[TestInstancePreDestroyCallback]'
     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]'
+    TestMethodReturnValueHandler: '{javadoc-root}/org.junit.jupiter.api/org/junit/jupiter/api/extension/TestMethodReturnValueHandler.html[TestMethodReturnValueHandler]'
     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

documentation/modules/ROOT/nav.adoc

@@ -49,6 +49,7 @@
 ** xref:extensions/exception-handling.adoc[]
 ** xref:extensions/pre-interrupt-callback.adoc[]
 ** xref:extensions/intercepting-invocations.adoc[]
+** xref:extensions/test-method-return-value-handling.adoc[]
 ** xref:extensions/providing-invocation-contexts-for-class-templates.adoc[]
 ** xref:extensions/providing-invocation-contexts-for-test-templates.adoc[]
 ** xref:extensions/keeping-state-in-extensions.adoc[]

documentation/modules/ROOT/pages/extensions/test-method-return-value-handling.adoc

@@ -0,0 +1,71 @@
+= Test Method Return Value Handling
+
+`{TestMethodReturnValueHandler}` defines an extension point that allows `@Test` methods
+to return non-void types. By default, JUnit Jupiter requires `@Test` methods to return
+`void`. A registered `TestMethodReturnValueHandler` relaxes this requirement for return
+types it supports.
+
+[[registration]]
+== Registration
+
+Implementations are discovered via Java's `{ServiceLoader}` mechanism and must be
+registered in a file named
+`META-INF/services/org.junit.jupiter.api.extension.TestMethodReturnValueHandler` on the
+classpath.
+
+[[how-it-works]]
+== How It Works
+
+A `TestMethodReturnValueHandler` has two responsibilities:
+
+1. **Declare supported return types** via `supportsReturnType(Class<?>)` — during
+   discovery, JUnit calls this method to decide whether a non-void `@Test` method should
+   be accepted.
+
+2. **Execute the test method** via `execute(Invocation<Object>, ExtensionContext)` — at
+   execution time, the handler receives an `{InvocationInterceptor}.Invocation` that wraps
+   the test method call. The handler must call `invocation.proceed()` to invoke the test
+   and obtain the return value. It is then responsible for processing the result — for
+   example, subscribing to a reactive type and awaiting completion.
+
+Because the handler controls _when_ `proceed()` is called, it can set up a custom
+execution context beforehand — for example, running the test on a specific thread or
+executor.
+
+[[example]]
+== Example
+
+The following handler adds support for `@Test` methods that return `CompletableFuture`:
+
+[source,java,indent=0]
+----
+public class CompletableFutureHandler implements TestMethodReturnValueHandler {
+
+    @Override
+    public boolean supportsReturnType(Class<?> returnType) {
+        return CompletableFuture.class.isAssignableFrom(returnType);
+    }
+
+    @Override
+    public void execute(InvocationInterceptor.Invocation<Object> invocation,
+            ExtensionContext context) throws Throwable {
+        Object result = invocation.proceed();
+        if (result != null) {
+            ((CompletableFuture<?>) result).get(30, TimeUnit.SECONDS);
+        }
+    }
+}
+----
+
+With this handler registered, the following test is discovered and executed:
+
+[source,java,indent=0]
+----
+@Test
+CompletableFuture<String> asyncTest() {
+    return CompletableFuture.supplyAsync(() -> {
+        // test logic
+        return "result";
+    });
+}
+----

documentation/modules/ROOT/partials/release-notes/release-notes-6.2.0-M1.adoc

@@ -71,6 +71,11 @@ repository on GitHub.
   and `@DisabledOnOs`.
 * Failures caused by `@Timeout` expirations now include a hint about enabling
   xref:writing-tests/timeouts.adoc#debugging-thread-dump[thread dumps].
+* Added `TestMethodReturnValueHandler` extension point that allows `@Test` methods to
+  return non-void types. Handlers are discovered via Java's `ServiceLoader` mechanism and
+  can control test method invocation — for example, to execute the test on a specific
+  thread or executor and then process the return value (e.g. awaiting a reactive type).
+  See xref:extensions/test-method-return-value-handling.adoc[] for details.
 
 
 [[v6.2.0-M1-junit-vintage]]

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

@@ -0,0 +1,95 @@
+/*
+ * Copyright 2015-2026 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 TestMethodReturnValueHandler} allows extensions to support
+ * {@link org.junit.jupiter.api.Test @Test} methods that return a non-void
+ * value.
+ *
+ * <p>By default, JUnit Jupiter requires {@code @Test} methods to return
+ * {@code void}. A registered {@code TestMethodReturnValueHandler} relaxes
+ * this requirement for return types it {@linkplain #supportsReturnType
+ * supports}. The handler is responsible for invoking the test method
+ * (via {@link InvocationInterceptor.Invocation#proceed()
+ * invocation.proceed()}) and processing the return value.
+ *
+ * <p>Because the handler controls the invocation, it can set up a
+ * custom execution context before calling {@code proceed()} &mdash; for
+ * example, running the test method on a specific thread or executor.
+ *
+ * <p>Implementations are discovered via Java's {@link java.util.ServiceLoader}
+ * mechanism and must be registered in
+ * {@code META-INF/services/org.junit.jupiter.api.extension.TestMethodReturnValueHandler}.
+ *
+ * <h2>Example</h2>
+ * <pre>{@code
+ * public class CompletableFutureHandler implements TestMethodReturnValueHandler {
+ *
+ *     @Override
+ *     public boolean supportsReturnType(Class<?> returnType) {
+ *         return CompletableFuture.class.isAssignableFrom(returnType);
+ *     }
+ *
+ *     @Override
+ *     public void execute(InvocationInterceptor.Invocation<Object> invocation,
+ *             ExtensionContext context) throws Throwable {
+ *         Object result = invocation.proceed();
+ *         if (result != null) {
+ *             ((CompletableFuture<?>) result).get(30, TimeUnit.SECONDS);
+ *         }
+ *     }
+ * }
+ * }</pre>
+ *
+ * @since 6.2
+ * @see org.junit.jupiter.api.Test
+ */
+@API(status = EXPERIMENTAL, since = "6.2")
+public interface TestMethodReturnValueHandler extends Extension {
+
+	/**
+	 * Determine if this handler supports the supplied return type.
+	 *
+	 * @param returnType the return type of the test method; never {@code null}
+	 * @return {@code true} if this handler can handle the return type
+	 */
+	boolean supportsReturnType(Class<?> returnType);
+
+	/**
+	 * Execute a {@code @Test} method that returns a supported type.
+	 *
+	 * <p>The handler must call {@link InvocationInterceptor.Invocation#proceed()
+	 * invocation.proceed()} to invoke the test method and obtain the return
+	 * value. The handler is then responsible for processing the result
+	 * &mdash; for example, subscribing to a reactive type and awaiting
+	 * completion.
+	 *
+	 * <p>Because the handler controls when {@code proceed()} is called, it
+	 * can set up a custom execution context beforehand &mdash; for example,
+	 * running the test on a specific thread or executor.
+	 *
+	 * <p>If this method throws, the test is marked as failed with the thrown
+	 * exception.
+	 *
+	 * @param invocation the invocation that executes the test method;
+	 * calling {@code proceed()} invokes the method and returns its result;
+	 * never {@code null}
+	 * @param context the current extension context; never {@code null}
+	 * @throws Throwable if the return value indicates a test failure
+	 */
+	void execute(InvocationInterceptor.Invocation<Object> invocation, ExtensionContext context) throws Throwable;
+
+}

junit-jupiter-engine/src/main/java/module-info.java

@@ -28,6 +28,7 @@
 	requires org.opentest4j;
 
 	uses org.junit.jupiter.api.extension.Extension;
+	uses org.junit.jupiter.api.extension.TestMethodReturnValueHandler;
 
 	provides org.junit.platform.engine.TestEngine
 			with org.junit.jupiter.engine.JupiterTestEngine;

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/TestMethodTestDescriptor.java

@@ -23,14 +23,17 @@
 import java.util.function.UnaryOperator;
 
 import org.apiguardian.api.API;
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.TestInstance.Lifecycle;
 import org.junit.jupiter.api.extension.AfterEachCallback;
 import org.junit.jupiter.api.extension.AfterTestExecutionCallback;
 import org.junit.jupiter.api.extension.BeforeEachCallback;
 import org.junit.jupiter.api.extension.BeforeTestExecutionCallback;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.InvocationInterceptor;
+import org.junit.jupiter.api.extension.InvocationInterceptor.Invocation;
 import org.junit.jupiter.api.extension.LifecycleMethodExecutionExceptionHandler;
+import org.junit.jupiter.api.extension.TestMethodReturnValueHandler;
 import org.junit.jupiter.api.extension.TestExecutionExceptionHandler;
 import org.junit.jupiter.api.extension.TestInstancePreDestroyCallback;
 import org.junit.jupiter.api.extension.TestInstances;
@@ -39,10 +42,12 @@
 import org.junit.jupiter.engine.execution.AfterEachMethodAdapter;
 import org.junit.jupiter.engine.execution.BeforeEachMethodAdapter;
 import org.junit.jupiter.engine.execution.InterceptingExecutableInvoker;
+import org.junit.jupiter.engine.execution.InterceptingExecutableInvoker.ReflectiveInterceptorCall;
 import org.junit.jupiter.engine.execution.InterceptingExecutableInvoker.ReflectiveInterceptorCall.VoidMethodInterceptorCall;
 import org.junit.jupiter.engine.execution.JupiterEngineExecutionContext;
 import org.junit.jupiter.engine.extension.ExtensionRegistry;
 import org.junit.jupiter.engine.extension.MutableExtensionRegistry;
+import org.junit.jupiter.engine.support.MethodReflectionUtils;
 import org.junit.platform.commons.util.UnrecoverableExceptions;
 import org.junit.platform.engine.TestDescriptor;
 import org.junit.platform.engine.TestExecutionResult;
@@ -216,8 +221,15 @@ protected void invokeTestMethod(JupiterEngineExecutionContext context, DynamicTe
 			try {
 				Method testMethod = getTestMethod();
 				Object instance = extensionContext.getRequiredTestInstance();
-				executableInvoker.invokeVoid(testMethod, instance, extensionContext, context.getExtensionRegistry(),
-					interceptorCall);
+				TestMethodReturnValueHandler handler = MethodReflectionUtils.findReturnValueHandler(testMethod);
+				if (handler != null) {
+					handler.execute(invokeTestMethodCapturingResult(testMethod, instance,
+						extensionContext, context.getExtensionRegistry()), extensionContext);
+				}
+				else {
+					executableInvoker.invokeVoid(testMethod, instance, extensionContext,
+						context.getExtensionRegistry(), interceptorCall);
+				}
 			}
 			catch (Throwable throwable) {
 				UnrecoverableExceptions.rethrowIfUnrecoverable(throwable);
@@ -226,6 +238,33 @@ protected void invokeTestMethod(JupiterEngineExecutionContext context, DynamicTe
 		});
 	}
 
+	@SuppressWarnings("NullAway")
+	private InvocationInterceptor.Invocation<Object> invokeTestMethodCapturingResult(Method testMethod, Object instance,
+			ExtensionContext extensionContext, ExtensionRegistry extensionRegistry) {
+		return () -> executableInvoker.<@Nullable Object> invoke(testMethod, instance,
+			extensionContext, extensionRegistry, returnValueCapturingInterceptorCall());
+	}
+
+	@SuppressWarnings("NullAway")
+	private static ReflectiveInterceptorCall<Method, @Nullable Object> returnValueCapturingInterceptorCall() {
+		return (interceptor, invocation, invocationContext, extensionContext) -> {
+			Object[] resultHolder = new Object[1];
+			interceptor.interceptTestMethod(new InvocationInterceptor.Invocation<@Nullable Void>() {
+				@Override
+				public @Nullable Void proceed() throws Throwable {
+					resultHolder[0] = invocation.proceed();
+					return null;
+				}
+
+				@Override
+				public void skip() {
+					invocation.skip();
+				}
+			}, invocationContext, extensionContext);
+			return resultHolder[0];
+		};
+	}
+
 	private void invokeTestExecutionExceptionHandlers(ExtensionRegistry registry, ExtensionContext context,
 			Throwable throwable) {
 

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/discovery/predicates/IsTestableMethod.java

@@ -14,6 +14,8 @@
 import static org.junit.platform.commons.support.AnnotationSupport.isAnnotated;
 import static org.junit.platform.commons.support.ModifierSupport.isNotAbstract;
 
+import org.junit.jupiter.engine.support.MethodReflectionUtils;
+
 import java.lang.annotation.Annotation;
 import java.lang.reflect.Method;
 import java.util.function.BiFunction;
@@ -65,7 +67,9 @@ private static Condition<Method> isNotPrivate(Class<? extends Annotation> annota
 
 	protected static Condition<Method> hasVoidReturnType(Class<? extends Annotation> annotationType,
 			DiscoveryIssueReporter issueReporter) {
-		return issueReporter.createReportingCondition(method -> getReturnType(method) == void.class,
+		return issueReporter.createReportingCondition(
+			method -> getReturnType(method) == void.class
+					|| MethodReflectionUtils.hasReturnValueHandler(method),
 			method -> createIssue(annotationType, method, "must not return a value"));
 	}
 

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/support/MethodReflectionUtils.java

@@ -21,15 +21,41 @@
 import java.lang.reflect.Method;
 import java.lang.reflect.Type;
 import java.util.Arrays;
+import java.util.List;
+import java.util.ServiceLoader;
 
 import org.apiguardian.api.API;
 import org.jspecify.annotations.Nullable;
+import org.junit.jupiter.api.extension.TestMethodReturnValueHandler;
 import org.junit.platform.commons.support.ReflectionSupport;
+import org.junit.platform.commons.util.ClassLoaderUtils;
 import org.junit.platform.commons.util.KotlinReflectionUtils;
 
 @API(status = INTERNAL, since = "6.0")
 public class MethodReflectionUtils {
 
+	private static List<TestMethodReturnValueHandler> getReturnValueHandlers() {
+		return ServiceLoader //
+				.load(TestMethodReturnValueHandler.class, ClassLoaderUtils.getDefaultClassLoader()) //
+				.stream() //
+				.map(ServiceLoader.Provider::get) //
+				.toList();
+	}
+
+	public static boolean hasReturnValueHandler(Method method) {
+		Class<?> returnType = method.getReturnType();
+		return returnType != void.class
+				&& getReturnValueHandlers().stream().anyMatch(h -> h.supportsReturnType(returnType));
+	}
+
+	public static @Nullable TestMethodReturnValueHandler findReturnValueHandler(Method method) {
+		Class<?> returnType = method.getReturnType();
+		return getReturnValueHandlers().stream() //
+				.filter(h -> h.supportsReturnType(returnType)) //
+				.findFirst() //
+				.orElse(null);
+	}
+
 	public static Class<?> getReturnType(Method method) {
 		return isKotlinSuspendingFunction(method) //
 				? getKotlinSuspendingFunctionReturnType(method) //

jupiter-tests/src/test/java/org/junit/jupiter/engine/CompletableFutureReturnValueHandler.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2015-2026 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.engine;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+import org.junit.jupiter.api.extension.ExtensionContext;
+import org.junit.jupiter.api.extension.InvocationInterceptor;
+import org.junit.jupiter.api.extension.TestMethodReturnValueHandler;
+
+public class CompletableFutureReturnValueHandler implements TestMethodReturnValueHandler {
+
+	@Override
+	public boolean supportsReturnType(Class<?> returnType) {
+		return CompletableFuture.class.isAssignableFrom(returnType);
+	}
+
+	@Override
+	public void execute(InvocationInterceptor.Invocation<Object> invocation, ExtensionContext context) throws Throwable {
+		Object result = invocation.proceed();
+		if (result == null) {
+			return;
+		}
+		try {
+			((CompletableFuture<?>) result).get(30, TimeUnit.SECONDS);
+		}
+		catch (ExecutionException ex) {
+			throw ex.getCause();
+		}
+		catch (TimeoutException ex) {
+			throw new AssertionError("CompletableFuture did not complete within 30 seconds", ex);
+		}
+	}
+
+}