Explain the test framework behavior in the withTimeout message (#3623)

Fixes #3588

Author: dkhalanskyjb

kotlinx-coroutines-core/common/src/Delay.kt

@@ -56,6 +56,19 @@ public interface Delay {
         DefaultDelay.invokeOnTimeout(timeMillis, block, context)
 }
 
+/**
+ * Enhanced [Delay] interface that provides additional diagnostics for [withTimeout].
+ * Is going to be removed once there is proper JVM-default support.
+ * Then we'll be able put this function into [Delay] without breaking binary compatibility.
+ */
+@InternalCoroutinesApi
+internal interface DelayWithTimeoutDiagnostics : Delay {
+    /**
+     * Returns a string that explains that the timeout has occurred, and explains what can be done about it.
+     */
+    fun timeoutMessage(timeout: Duration): String
+}
+
 /**
  * Suspends until cancellation, in which case it will throw a [CancellationException].
  *

kotlinx-coroutines-core/common/src/Timeout.kt

@@ -13,6 +13,7 @@ import kotlin.coroutines.*
 import kotlin.coroutines.intrinsics.*
 import kotlin.jvm.*
 import kotlin.time.*
+import kotlin.time.Duration.Companion.milliseconds
 
 /**
  * Runs a given suspending [block] of code inside a coroutine with a specified [timeout][timeMillis] and throws
@@ -135,9 +136,9 @@ public suspend fun <T> withTimeoutOrNull(timeMillis: Long, block: suspend Corout
  * > Implementation note: how the time is tracked exactly is an implementation detail of the context's [CoroutineDispatcher].
  */
 public suspend fun <T> withTimeoutOrNull(timeout: Duration, block: suspend CoroutineScope.() -> T): T? =
-        withTimeoutOrNull(timeout.toDelayMillis(), block)
+    withTimeoutOrNull(timeout.toDelayMillis(), block)
 
-private fun <U, T: U> setupTimeout(
+private fun <U, T : U> setupTimeout(
     coroutine: TimeoutCoroutine<U, T>,
     block: suspend CoroutineScope.() -> T
 ): Any? {
@@ -150,12 +151,12 @@ private fun <U, T: U> setupTimeout(
     return coroutine.startUndispatchedOrReturnIgnoreTimeout(coroutine, block)
 }
 
-private class TimeoutCoroutine<U, in T: U>(
+private class TimeoutCoroutine<U, in T : U>(
     @JvmField val time: Long,
     uCont: Continuation<U> // unintercepted continuation
 ) : ScopeCoroutine<T>(uCont.context, uCont), Runnable {
     override fun run() {
-        cancelCoroutine(TimeoutCancellationException(time, this))
+        cancelCoroutine(TimeoutCancellationException(time, context.delay, this))
     }
 
     override fun nameString(): String =
@@ -173,7 +174,6 @@ public class TimeoutCancellationException internal constructor(
      * Creates a timeout exception with the given message.
      * This constructor is needed for exception stack-traces recovery.
      */
-    @Suppress("UNUSED")
     internal constructor(message: String) : this(message, null)
 
     // message is never null in fact
@@ -183,5 +183,10 @@ public class TimeoutCancellationException internal constructor(
 
 internal fun TimeoutCancellationException(
     time: Long,
+    delay: Delay,
     coroutine: Job
-) : TimeoutCancellationException = TimeoutCancellationException("Timed out waiting for $time ms", coroutine)
+) : TimeoutCancellationException {
+    val message = (delay as? DelayWithTimeoutDiagnostics)?.timeoutMessage(time.milliseconds)
+        ?: "Timed out waiting for $time ms"
+    return TimeoutCancellationException(message, coroutine)
+}

kotlinx-coroutines-core/common/test/flow/operators/TimeoutTest.kt

@@ -97,7 +97,8 @@ class TimeoutTest : TestBase() {
     fun testUpstreamError() = testUpstreamError(TestException())
 
     @Test
-    fun testUpstreamErrorTimeoutException() = testUpstreamError(TimeoutCancellationException(0, Job()))
+    fun testUpstreamErrorTimeoutException() =
+        testUpstreamError(TimeoutCancellationException("Timed out waiting for ${0} ms", Job()))
 
     @Test
     fun testUpstreamErrorCancellationException() = testUpstreamError(CancellationException(""))

kotlinx-coroutines-test/api/kotlinx-coroutines-test.api

@@ -95,11 +95,12 @@ public final class kotlinx/coroutines/test/TestCoroutineScopeKt {
 	public static final fun runCurrent (Lkotlinx/coroutines/test/TestCoroutineScope;)V
 }
 
-public abstract class kotlinx/coroutines/test/TestDispatcher : kotlinx/coroutines/CoroutineDispatcher, kotlinx/coroutines/Delay {
+public abstract class kotlinx/coroutines/test/TestDispatcher : kotlinx/coroutines/CoroutineDispatcher, kotlinx/coroutines/Delay, kotlinx/coroutines/DelayWithTimeoutDiagnostics {
 	public fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public abstract fun getScheduler ()Lkotlinx/coroutines/test/TestCoroutineScheduler;
 	public fun invokeOnTimeout (JLjava/lang/Runnable;Lkotlin/coroutines/CoroutineContext;)Lkotlinx/coroutines/DisposableHandle;
 	public fun scheduleResumeAfterDelay (JLkotlinx/coroutines/CancellableContinuation;)V
+	public synthetic fun timeoutMessage-LRDsOJo (J)Ljava/lang/String;
 }
 
 public final class kotlinx/coroutines/test/TestDispatchers {

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

@@ -7,6 +7,7 @@ package kotlinx.coroutines.test
 import kotlinx.coroutines.*
 import kotlin.coroutines.*
 import kotlin.jvm.*
+import kotlin.time.*
 
 /**
  * A test dispatcher that can interface with a [TestCoroutineScheduler].
@@ -17,7 +18,8 @@ import kotlin.jvm.*
  *   the virtual time.
  */
 @ExperimentalCoroutinesApi
-public abstract class TestDispatcher internal constructor() : CoroutineDispatcher(), Delay {
+@Suppress("INVISIBLE_REFERENCE")
+public abstract class TestDispatcher internal constructor() : CoroutineDispatcher(), Delay, DelayWithTimeoutDiagnostics {
     /** The scheduler that this dispatcher is linked to. */
     @ExperimentalCoroutinesApi
     public abstract val scheduler: TestCoroutineScheduler
@@ -44,6 +46,13 @@ public abstract class TestDispatcher internal constructor() : CoroutineDispatche
     /** @suppress */
     override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle =
         scheduler.registerEvent(this, timeMillis, block, context) { false }
+
+    /** @suppress */
+    @Suppress("CANNOT_OVERRIDE_INVISIBLE_MEMBER")
+    @Deprecated("Is only needed internally", level = DeprecationLevel.HIDDEN)
+    public override fun timeoutMessage(timeout: Duration): String =
+        "Timed out after $timeout of _virtual_ (kotlinx.coroutines.test) time. " +
+            "To use the real time, wrap 'withTimeout' in 'withContext(Dispatchers.Default.limitedParallelism(1))'"
 }
 
 /**

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

@@ -476,6 +476,20 @@ class TestScopeTest {
         }
     }
 
+    /**
+     * Tests that [TestScope.withTimeout] notifies the programmer about using the virtual time.
+     */
+    @Test
+    fun testTimingOutWithVirtualTimeMessage() = runTest {
+        try {
+            withTimeout(1_000_000) {
+                Channel<Unit>().receive()
+            }
+        } catch (e: TimeoutCancellationException) {
+            assertContains(e.message!!, "virtual")
+        }
+    }
+
     companion object {
         internal val invalidContexts = listOf(
             Dispatchers.Default, // not a [TestDispatcher]