Make UncompletedTestCoroutines more verbose

kotlinx-coroutines-core/common/src/internal/StackTraceRecovery.common.kt

@@ -40,6 +40,7 @@ internal expect suspend inline fun recoverAndThrow(exception: Throwable): Nothin
  * The opposite of [recoverStackTrace].
  * It is guaranteed that `unwrap(recoverStackTrace(e)) === e`
  */
+@PublishedApi
 internal expect fun <E: Throwable> unwrap(exception: E): E
 
 internal expect class StackTraceElement

kotlinx-coroutines-test/common/src/TestBuilders.kt

@@ -164,7 +164,7 @@ public fun TestScope.runTest(
 ): TestResult = asSpecificImplementation().let {
     it.enter()
     createTestResult {
-        runTestCoroutine(it, dispatchTimeoutMs, testBody) { it.leave() }
+        runTestCoroutine(it, dispatchTimeoutMs, TestScopeImpl::tryGetCompletionCause, testBody) { it.leave() }
     }
 }
 
@@ -196,6 +196,7 @@ internal const val DEFAULT_DISPATCH_TIMEOUT_MS = 60_000L
 internal suspend fun <T: AbstractCoroutine<Unit>> runTestCoroutine(
     coroutine: T,
     dispatchTimeoutMs: Long,
+    tryGetCompletionCause: T.() -> Throwable?,
     testBody: suspend T.() -> Unit,
     cleanup: () -> List<Throwable>,
 ) {
@@ -228,7 +229,26 @@ internal suspend fun <T: AbstractCoroutine<Unit>> runTestCoroutine(
                     // we expect these and will instead throw a more informative exception just below.
                     emptyList()
                 }.throwAll()
-                throw UncompletedCoroutinesError("The test coroutine was not completed after waiting for $dispatchTimeoutMs ms")
+                var completing: Boolean
+                val completionCause = try {
+                    coroutine.tryGetCompletionCause().also { completing = true }
+                } catch (e: Throwable) {
+                    completing = false
+                    null
+                }
+                var message = "After waiting for $dispatchTimeoutMs ms"
+                if (!completing)
+                    message += ", the test coroutine is not completing"
+                val activeChildren = coroutine.children.filter { it.isActive }.toList()
+                if (activeChildren.isNotEmpty())
+                    message += ", there were active child jobs: $activeChildren"
+                if (completing && activeChildren.isEmpty()) {
+                    // some sort of race condition? write something generic.
+                    message += ", the test coroutine was not completed"
+                }
+                val error = UncompletedCoroutinesError(message)
+                completionCause?.let { cause -> error.addSuppressed(cause) }
+                throw error
             }
         }
     }

kotlinx-coroutines-test/common/src/TestScope.kt

@@ -216,6 +216,9 @@ internal class TestScopeImpl(context: CoroutineContext) :
         }
     }
 
+    /** Throws an exception if the coroutine is not completing. */
+    fun tryGetCompletionCause(): Throwable? = completionCause
+
     override fun toString(): String =
         "TestScope[" + (if (finished) "test ended" else if (entered) "test started" else "test not started") + "]"
 }

kotlinx-coroutines-test/common/test/RunTestTest.kt

@@ -5,6 +5,7 @@
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
+import kotlinx.coroutines.internal.*
 import kotlinx.coroutines.flow.*
 import kotlin.coroutines.*
 import kotlin.test.*
@@ -97,6 +98,59 @@ class RunTestTest {
         }
     }
 
+    /** Tests that, on timeout, the names of the active coroutines are listed,
+     * whereas the names of the completed ones are not. */
+    @Test
+    @NoJs
+    @NoNative
+    fun testListingActiveCoroutinesOnTimeout(): TestResult {
+        val name1 = "GoodUniqueName"
+        val name2 = "BadUniqueName"
+        return testResultMap({
+            try {
+                it()
+                fail("unreached")
+            } catch (e: UncompletedCoroutinesError) {
+                assertTrue((e.message ?: "").contains(name1))
+                assertFalse((e.message ?: "").contains(name2))
+            }
+        }) {
+            runTest(dispatchTimeoutMs = 10) {
+                launch(CoroutineName(name1)) {
+                    CompletableDeferred<Unit>().await()
+                }
+                launch(CoroutineName(name2)) {
+                }
+            }
+        }
+    }
+
+    /** Tests that the [UncompletedCoroutinesError] suppresses an exception with which the coroutine is completing. */
+    @Test
+    fun testFailureWithPendingCoroutine() = testResultMap({
+        try {
+            it()
+            fail("unreached")
+        } catch (e: UncompletedCoroutinesError) {
+            @Suppress("INVISIBLE_MEMBER")
+            val suppressed = unwrap(e).suppressedExceptions
+            assertEquals(1, suppressed.size)
+            assertIs<TestException>(suppressed[0]).also {
+                assertEquals("A", it.message)
+            }
+        }
+    }) {
+        runTest(dispatchTimeoutMs = 10) {
+            launch {
+                withContext(NonCancellable) {
+                    awaitCancellation()
+                }
+            }
+            yield()
+            throw TestException("A")
+        }
+    }
+
     /** Tests that real delays can be accounted for with a large enough dispatch timeout. */
     @Test
     fun testRunTestWithLargeTimeout() = runTest(dispatchTimeoutMs = 5000) {

kotlinx-coroutines-test/jvm/src/migration/TestBuildersDeprecated.kt

@@ -8,7 +8,6 @@
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
-import kotlinx.coroutines.selects.*
 import kotlin.coroutines.*
 import kotlin.jvm.*
 
@@ -137,9 +136,9 @@ public fun runTestWithLegacyScope(
 ): TestResult {
     if (context[RunningInRunTest] != null)
         throw IllegalStateException("Calls to `runTest` can't be nested. Please read the docs on `TestResult` for details.")
-    val testScope = TestBodyCoroutine<Unit>(createTestCoroutineScope(context + RunningInRunTest))
+    val testScope = TestBodyCoroutine(createTestCoroutineScope(context + RunningInRunTest))
     return createTestResult {
-        runTestCoroutine(testScope, dispatchTimeoutMs, testBody) {
+        runTestCoroutine(testScope, dispatchTimeoutMs, TestBodyCoroutine::tryGetCompletionCause, testBody) {
             try {
                 testScope.cleanup()
                 emptyList()
@@ -169,9 +168,9 @@ public fun TestCoroutineScope.runTest(
     block: suspend TestCoroutineScope.() -> Unit
 ): TestResult = runTestWithLegacyScope(coroutineContext, dispatchTimeoutMs, block)
 
-private class TestBodyCoroutine<T>(
+private class TestBodyCoroutine(
     private val testScope: TestCoroutineScope,
-) : AbstractCoroutine<T>(testScope.coroutineContext, initParentJob = true, active = true), TestCoroutineScope {
+) : AbstractCoroutine<Unit>(testScope.coroutineContext, initParentJob = true, active = true), TestCoroutineScope {
 
     override val testScheduler get() = testScope.testScheduler
 
@@ -187,4 +186,7 @@ private class TestBodyCoroutine<T>(
         )
 
     fun cleanup() = testScope.cleanupTestCoroutines()
+
+    /** Throws an exception if the coroutine is not completing. */
+    fun tryGetCompletionCause(): Throwable? = completionCause
 }