Spike support for Kotlin suspending functions #4515

marcphilipp · 2025-05-05T10:14:43Z

Overview

Issue: #1914

Given the function definition of suspend fun suspendingTest(message: String): Unit, the Kotlin compiler generates byte code that results in Java's reflection API seeing:

public final java.lang.Object suspendingTest(
  java.lang.String,kotlin.coroutines.Continuation<? super kotlin.Unit>)

The return type is java.lang.Object and an extra parameter of type kotlin.coroutines.Continuation<? super T> where T is the declared return type is added. Since Continuation<...> can be used as a method parameter for a regular function, its presence is insufficient to determine whether a method is a suspending function. Thus, a dependency on kotlin-reflect is needed so KFunction.isSuspend can be called.

If a suspending function is detected, it can be called using KCallables.callSuspend (also from kotlin-reflect) while wrapping it in runBlocking from kotlinx-coroutines.

To avoid the extra dependencies from being added to junit-jupiter-engine, the prototype in this PR adds a new junit-jupiter-kotlin artifact. The former defines a new MethodAdapterFactory interface that the latter implements via ServiceLoader. The returned MethodAdapter is used for validation (return type), parameter resolution (ignore the Continuation parameter), and invocation (via KCallables.callSuspend rather than ReflectionUtils).

The PR adds support for using suspend on @Test, @TestTemplate (including but not limited to @ParameterizedTest and @RepeatedTest), @TestFactory, and all lifecycle methods. Moreover, it also adds support for calling suspend methods via ExecutableInvoker which is used to support @After/@BeforeClassTemplateInvocationCallback lifecycle methods. See the KotlinSuspendFunctionsTests test class for a demo.

Open Questions

Can the extra junit-jupiter-kotlin artifact be avoided somehow without forcing Kotlin dependencies on plain-Java users and without forcing Kotlin users to declare extra dependencies on kotlin-reflect and kotlinx-coroutines?

I hereby agree to the terms of the JUnit Contributor License Agreement.

Definition of Done

There are no TODOs left in the code
Method preconditions are checked and documented in the method's Javadoc
Coding conventions (e.g. for logging) have been followed
Change is covered by automated tests including corner cases, errors, and exception handling
Public API has Javadoc and @API annotations
Change is documented in the User Guide and Release Notes

marcphilipp · 2025-05-05T10:15:56Z

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

+		if (parameterTypes[parameterTypes.length - 1].getName().equals("kotlin.coroutines.Continuation")) {
+			// Kotlin suspend functions have a Continuation parameter at the end that should not be included
+			parameterTypes = Arrays.copyOf(parameterTypes, parameterTypes.length - 1);
+		}


💬 This removes the Continuation parameter from display names because it's generated by the Kotlin compiler.

marcphilipp · 2025-05-05T10:16:19Z

junit-jupiter-engine/junit-jupiter-engine.gradle.kts

@@ -1,5 +1,5 @@
 plugins {
-	id("junitbuild.kotlin-library-conventions")
+	id("junitbuild.java-library-conventions")


💬 We were not actually using Kotlin in this project.

sbrannen · 2025-05-05T11:14:26Z

Can the extra junit-jupiter-kotlin artifact be avoided somehow without forcing Kotlin dependencies on plain-Java users

Yes, Spring Framework provides transparent Kotlin support without Kotlin-specific Spring artifacts.

See KotlinDetector.isSuspendingFunction(Method) for an example.

and without forcing Kotlin users to declare extra dependencies on kotlin-reflect and kotlinx-coroutines?

Probably not.

See: https://docs.spring.io/spring-framework/reference/languages/kotlin/requirements.html

marcphilipp · 2025-05-05T12:30:41Z

@sbrannen Thanks for the pointers!

I think we have two options:

Make the Kotlin dependencies optional (like Spring does)
Create an extra artifact/variant that carries the dependencies

As far as manual effort is concerned, (1) requires adding at least two dependencies (kotlin-reflect and kotlinx-coroutines) while (2) requires adding only one (junit-jupiter-kotlin or whichever name we decide for). If we add support for some other Kotlin feature, it might require additional dependencies which we could add to our artifact/variant in case of (2) without users having to modify their builds again. Moreover, I think (2) is cleaner and carries a smaller risk of running into ClassNotFoundErrors etc. at runtime.

Are there any other pros/cons?

junit-jupiter-kotlin/junit-jupiter-kotlin.gradle.kts

marcphilipp · 2025-05-05T12:41:46Z

junit-jupiter-params/src/main/java/org/junit/jupiter/params/ParameterizedClassContext.java

@@ -155,9 +153,6 @@ private static <A extends Annotation> List<ArgumentSetLifecycleMethod> findLifec
 		List<Method> methods = findAnnotatedMethods(testClass, annotationType, traversalMode);

 		return methods.stream() //
-				.filter(ModifierSupport::isNotPrivate) //
-				.filter(testInstanceLifecycle == PER_METHOD ? ModifierSupport::isStatic : __ -> true) //
-				.filter(ReflectionUtils::returnsPrimitiveVoid) //


💬 This is already validated in junit-jupiter-engine so there's no need to do so again.

jlink · 2025-05-06T06:39:04Z

@sbrannen Thanks for the pointers!

I think we have two options:
1. Make the Kotlin dependencies optional (like Spring does)

2. Create an extra artifact/variant that carries the dependencies
As far as manual effort is concerned, (1) requires adding at least two dependencies (kotlin-reflect and kotlinx-coroutines) while (2) requires adding only one (junit-jupiter-kotlin or whichever name we decide for). If we add support for some other Kotlin feature, it might require additional dependencies which we could add to our artifact/variant in case of (2) without users having to modify their builds again. Moreover, I think (2) is cleaner and carries a smaller risk of running into ClassNotFoundErrors etc. at runtime.

Are there any other pros/cons?

IMO having an explicit artifact for Kotlin support is sending a clear message: JUnit Jupiter wants to support Kotlin. That's a win in my book. And it opens the door for further support, e.g. providing Kotlin-style API for some constructs.

marcphilipp · 2025-05-09T10:31:20Z

...n/src/main/kotlin/org/junit/jupiter/kotlin/coroutines/KotlinSuspendFunctionAdapterFactory.kt

+                override fun getReturnType() =
+                    with(kotlinFunction.returnType.jvmErasure) {
+                        if (this == Unit::class) {
+                            Void.TYPE


Suggested change

Void.TYPE

void.class

marcphilipp · 2025-05-09T10:34:20Z

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

+
+	public MethodAdapterRegistry() {
+		// Load and instantiate factories eagerly to avoid GraalVM issue
+		this.factories = ServiceLoader.load(MethodAdapterFactory.class).stream() //


❌ Use getDefaultClassLoader() here

marcphilipp · 2025-05-14T11:29:05Z

Superseded by #4530.

marcphilipp added 6 commits May 3, 2025 16:04

Spike support for Kotlin suspend functions

11b31f6

Move to subpackage

870e2b7

Simplify test

778440c

Add support for suspend on core lifecycle methods

f6433e8

Add support for suspend on params lifecycle methods

43adaac

Remove unused dependency

f01684b

marcphilipp commented May 5, 2025

View reviewed changes

Remove methods no longer called from production code

6c01632

Add missing API annotations

880c90c

marcphilipp linked an issue May 5, 2025 that may be closed by this pull request

Support test methods with Kotlin suspend modifier #1914

Open

marcphilipp mentioned this pull request May 5, 2025

Support test methods with Kotlin suspend modifier #1914

Open

marcphilipp commented May 5, 2025

View reviewed changes

junit-jupiter-kotlin/junit-jupiter-kotlin.gradle.kts Outdated Show resolved Hide resolved

marcphilipp force-pushed the marc/1914-kotlin-suspend-support branch from 24b1f79 to 83aaa48 Compare May 5, 2025 12:36

marcphilipp added 8 commits May 5, 2025 14:40

Fix GraalVmStarterTests

9894186

Fix JarDescribeModuleTests

9df4fce

Fix HelperTests

d778687

Fix ModularUserGuideTests

505e4b2

Fix unit tests

2735482

Fix ClasspathAlignmentChecker

598dc88

Disable demo test for now

855b4cd

Disable OSGi verification for now

329f2d6

marcphilipp force-pushed the marc/1914-kotlin-suspend-support branch from 83aaa48 to 329f2d6 Compare May 5, 2025 12:40

marcphilipp commented May 5, 2025

View reviewed changes

Mark kotlinx.coroutines as optional for OSGi resolution

34b9700

marcphilipp added 2 commits May 6, 2025 12:17

Fix Javadoc generation

c8bca03

Document suspend support

a85696a

marcphilipp commented May 9, 2025

View reviewed changes

marcphilipp mentioned this pull request May 14, 2025

Add support for Kotlin suspending functions as test/lifecycle methods #4530

Merged

6 tasks

marcphilipp closed this May 14, 2025

marcphilipp deleted the marc/1914-kotlin-suspend-support branch May 14, 2025 18:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Spike support for Kotlin suspending functions #4515

Spike support for Kotlin suspending functions #4515

marcphilipp commented May 5, 2025 •

edited

Loading

marcphilipp May 5, 2025

marcphilipp May 5, 2025

sbrannen commented May 5, 2025 •

edited

Loading

marcphilipp commented May 5, 2025

marcphilipp May 5, 2025

jlink commented May 6, 2025

marcphilipp May 9, 2025

marcphilipp May 9, 2025

marcphilipp commented May 14, 2025

Spike support for Kotlin suspending functions #4515

Spike support for Kotlin suspending functions #4515

Conversation

marcphilipp commented May 5, 2025 • edited Loading

Overview

Open Questions

Definition of Done

marcphilipp May 5, 2025

Choose a reason for hiding this comment

marcphilipp May 5, 2025

Choose a reason for hiding this comment

sbrannen commented May 5, 2025 • edited Loading

marcphilipp commented May 5, 2025

marcphilipp May 5, 2025

Choose a reason for hiding this comment

jlink commented May 6, 2025

marcphilipp May 9, 2025

Choose a reason for hiding this comment

marcphilipp May 9, 2025

Choose a reason for hiding this comment

marcphilipp commented May 14, 2025

marcphilipp commented May 5, 2025 •

edited

Loading

sbrannen commented May 5, 2025 •

edited

Loading