Allow specifying the timeout for runTest

Deprecate `dispatchTimeoutMs`, as this is a confusing
implementation detail that made it to the final API.

We use the fact that the `runTest(Duration)` overload was never
published, so we can reuse it to have the `Duration` mean the
whole-test timeout in a backward-compatible manner.

Author: dkhalanskyjb

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

@@ -22,10 +22,10 @@ public final class kotlinx/coroutines/test/TestBuildersKt {
 	public static final fun runTest (Lkotlinx/coroutines/test/TestScope;JLkotlin/jvm/functions/Function2;)V
 	public static synthetic fun runTest$default (Lkotlin/coroutines/CoroutineContext;JLkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
 	public static synthetic fun runTest$default (Lkotlinx/coroutines/test/TestCoroutineScope;JLkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
-	public static synthetic fun runTest$default (Lkotlinx/coroutines/test/TestScope;JLkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
-	public static final fun runTest-8Mi8wO0 (Lkotlin/coroutines/CoroutineContext;JLkotlin/jvm/functions/Function2;)V
-	public static final fun runTest-8Mi8wO0 (Lkotlinx/coroutines/test/TestScope;JLkotlin/jvm/functions/Function2;)V
-	public static synthetic fun runTest-8Mi8wO0$default (Lkotlin/coroutines/CoroutineContext;JLkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
+	public static final fun runTest-Kx4hsE0 (Lkotlin/coroutines/CoroutineContext;Lkotlin/time/Duration;Lkotlin/jvm/functions/Function2;)V
+	public static final fun runTest-Kx4hsE0 (Lkotlinx/coroutines/test/TestScope;Lkotlin/time/Duration;Lkotlin/jvm/functions/Function2;)V
+	public static synthetic fun runTest-Kx4hsE0$default (Lkotlin/coroutines/CoroutineContext;Lkotlin/time/Duration;Lkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
+	public static synthetic fun runTest-Kx4hsE0$default (Lkotlinx/coroutines/test/TestScope;Lkotlin/time/Duration;Lkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
 	public static final fun runTestWithLegacyScope (Lkotlin/coroutines/CoroutineContext;JLkotlin/jvm/functions/Function2;)V
 	public static synthetic fun runTestWithLegacyScope$default (Lkotlin/coroutines/CoroutineContext;JLkotlin/jvm/functions/Function2;ILjava/lang/Object;)V
 }
@@ -66,6 +66,7 @@ public final class kotlinx/coroutines/test/TestCoroutineScheduler : kotlin/corou
 	public static final field Key Lkotlinx/coroutines/test/TestCoroutineScheduler$Key;
 	public fun <init> ()V
 	public final fun advanceTimeBy (J)V
+	public final fun advanceTimeBy-LRDsOJo (J)V
 	public final fun advanceUntilIdle ()V
 	public final fun getCurrentTime ()J
 	public final fun getTimeSource ()Lkotlin/time/TimeSource;

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

@@ -137,7 +137,6 @@ private class UnconfinedTestDispatcherImpl(
  *
  * @see UnconfinedTestDispatcher for a dispatcher that is not confined to any particular thread.
  */
-@ExperimentalCoroutinesApi
 @Suppress("FunctionName")
 public fun StandardTestDispatcher(
     scheduler: TestCoroutineScheduler? = null,

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

@@ -26,7 +26,6 @@ import kotlin.time.*
  * virtual time as needed (via [advanceUntilIdle]), or run the tasks that are scheduled to run as soon as possible but
  * haven't yet been dispatched (via [runCurrent]).
  */
-@ExperimentalCoroutinesApi
 public class TestCoroutineScheduler : AbstractCoroutineContextElement(TestCoroutineScheduler),
     CoroutineContext.Element {
 
@@ -49,6 +48,9 @@ public class TestCoroutineScheduler : AbstractCoroutineContextElement(TestCorout
         get() = synchronized(lock) { field }
         private set
 
+    /** A channel for notifying about the fact that a foreground work dispatch recently happened. */
+    private val dispatchEventsForeground: Channel<Unit> = Channel(CONFLATED)
+
     /** A channel for notifying about the fact that a dispatch recently happened. */
     private val dispatchEvents: Channel<Unit> = Channel(CONFLATED)
 
@@ -73,8 +75,8 @@ public class TestCoroutineScheduler : AbstractCoroutineContextElement(TestCorout
             val time = addClamping(currentTime, timeDeltaMillis)
             val event = TestDispatchEvent(dispatcher, count, time, marker as Any, isForeground) { isCancelled(marker) }
             events.addLast(event)
-            /** can't be moved above: otherwise, [onDispatchEvent] could consume the token sent here before there's
-             * actually anything in the event queue. */
+            /** can't be moved above: otherwise, [onDispatchEventForeground] or [receiveDispatchEvent] could consume the
+             * token sent here before there's actually anything in the event queue. */
             sendDispatchEvent(context)
             DisposableHandle {
                 synchronized(lock) {
@@ -109,7 +111,6 @@ public class TestCoroutineScheduler : AbstractCoroutineContextElement(TestCorout
      * milliseconds by which the execution of this method has advanced the virtual time. If you want to recreate that
      * functionality, query [currentTime] before and after the execution to achieve the same result.
      */
-    @ExperimentalCoroutinesApi
     public fun advanceUntilIdle(): Unit = advanceUntilIdleOr { events.none(TestDispatchEvent<*>::isForeground) }
 
     /**
@@ -125,7 +126,6 @@ public class TestCoroutineScheduler : AbstractCoroutineContextElement(TestCorout
     /**
      * Runs the tasks that are scheduled to execute at this moment of virtual time.
      */
-    @ExperimentalCoroutinesApi
     public fun runCurrent() {
         val timeMark = synchronized(lock) { currentTime }
         while (true) {
@@ -177,6 +177,14 @@ public class TestCoroutineScheduler : AbstractCoroutineContextElement(TestCorout
         }
     }
 
+    /**
+     * Moves the virtual clock of this dispatcher forward by [the specified amount][delayTime], running the
+     * scheduled tasks in the meantime.
+     *
+     * @throws IllegalStateException if passed a negative [delay][delayTime].
+     */
+    public fun advanceTimeBy(delayTime: Duration): Unit = advanceTimeBy(delayTime.inWholeMicroseconds)
+
     /**
      * Checks that the only tasks remaining in the scheduler are cancelled.
      */
@@ -191,19 +199,24 @@ public class TestCoroutineScheduler : AbstractCoroutineContextElement(TestCorout
      * [context] is the context in which the task will be dispatched.
      */
     internal fun sendDispatchEvent(context: CoroutineContext) {
+        dispatchEvents.trySend(Unit)
         if (context[BackgroundWork] !== BackgroundWork)
-            dispatchEvents.trySend(Unit)
+            dispatchEventsForeground.trySend(Unit)
     }
 
     /**
-     * Consumes the knowledge that a dispatch event happened recently.
+     * Waits for a notification about a dispatch event.
+     */
+    internal suspend fun receiveDispatchEvent() = dispatchEvents.receive()
+
+    /**
+     * Consumes the knowledge that a foreground work dispatch event happened recently.
      */
-    internal val onDispatchEvent: SelectClause1<Unit> get() = dispatchEvents.onReceive
+    internal val onDispatchEventForeground: SelectClause1<Unit> get() = dispatchEventsForeground.onReceive
 
     /**
      * Returns the [TimeSource] representation of the virtual time of this scheduler.
      */
-    @ExperimentalCoroutinesApi
     @ExperimentalTime
     public val timeSource: TimeSource = object : AbstractLongTimeSource(DurationUnit.MILLISECONDS) {
         override fun read(): Long = currentTime

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

@@ -16,10 +16,8 @@ import kotlin.jvm.*
  * * [UnconfinedTestDispatcher] is a dispatcher that behaves like [Dispatchers.Unconfined] while allowing to control
  *   the virtual time.
  */
-@ExperimentalCoroutinesApi
 public abstract class TestDispatcher internal constructor() : CoroutineDispatcher(), Delay {
     /** The scheduler that this dispatcher is linked to. */
-    @ExperimentalCoroutinesApi
     public abstract val scheduler: TestCoroutineScheduler
 
     /** Notifies the dispatcher that it should process a single event marked with [marker] happening at time [time]. */

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

@@ -40,12 +40,10 @@ import kotlin.time.*
  *   paused by default, like [StandardTestDispatcher].
  * * No access to the list of unhandled exceptions.
  */
-@ExperimentalCoroutinesApi
 public sealed interface TestScope : CoroutineScope {
     /**
      * The delay-skipping scheduler used by the test dispatchers running the code in this scope.
      */
-    @ExperimentalCoroutinesApi
     public val testScheduler: TestCoroutineScheduler
 
     /**
@@ -82,7 +80,6 @@ public sealed interface TestScope : CoroutineScope {
      * }
      * ```
      */
-    @ExperimentalCoroutinesApi
     public val backgroundScope: CoroutineScope
 }
 
@@ -156,7 +153,6 @@ public val TestScope.testTimeSource: TimeSource get() = testScheduler.timeSource
  * @throws IllegalArgumentException if [context] has an [CoroutineExceptionHandler] that is not an
  * [UncaughtExceptionCaptor].
  */
-@ExperimentalCoroutinesApi
 @Suppress("FunctionName")
 public fun TestScope(context: CoroutineContext = EmptyCoroutineContext): TestScope {
     val ctxWithDispatcher = context.withDelaySkipping()

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

@@ -72,7 +72,12 @@ class RunTestTest {
     /** Tests that too low of a dispatch timeout causes crashes. */
     @Test
     fun testRunTestWithSmallTimeout() = testResultMap({ fn ->
-        assertFailsWith<UncompletedCoroutinesError> { fn() }
+        try {
+            fn()
+            fail("shouldn't be reached")
+        } catch (e: Throwable) {
+            assertIs<UncompletedCoroutinesError>(e)
+        }
     }) {
         runTest(dispatchTimeoutMs = 100) {
             withContext(Dispatchers.Default) {

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

@@ -13,3 +13,10 @@ internal actual fun createTestResult(testProcedure: suspend CoroutineScope.() ->
     GlobalScope.promise {
         testProcedure()
     }
+
+internal actual fun getLastKnownPosition(): Any? = null
+
+internal actual fun dumpCoroutinesAndThrow(exception: Throwable, lastKnownPosition: Any?) {
+    console.error(exception)
+    throw exception
+}

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

@@ -4,6 +4,7 @@
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
+import kotlinx.coroutines.debug.internal.*
 
 @Suppress("ACTUAL_WITHOUT_EXPECT")
 public actual typealias TestResult = Unit
@@ -13,3 +14,21 @@ internal actual fun createTestResult(testProcedure: suspend CoroutineScope.() ->
         testProcedure()
     }
 }
+
+internal actual fun getLastKnownPosition(): Any? = Thread.currentThread()
+
+internal actual fun dumpCoroutinesAndThrow(exception: Throwable, lastKnownPosition: Any?) {
+    val thread = lastKnownPosition as? Thread
+    @Suppress("INVISIBLE_REFERENCE", "INVISIBLE_MEMBER")
+    if (DebugProbesImpl.isInstalled) {
+        DebugProbesImpl.install()
+        try {
+            DebugProbesImpl.dumpCoroutines(System.err)
+            System.err.flush()
+        } finally {
+            DebugProbesImpl.uninstall()
+        }
+    }
+    thread?.stackTrace?.let { exception.stackTrace = it }
+    throw exception
+}

kotlinx-coroutines-test/jvm/src/TestBuildersJvm.kt

@@ -165,7 +165,7 @@ public fun runTestWithLegacyScope(
         throw IllegalStateException("Calls to `runTest` can't be nested. Please read the docs on `TestResult` for details.")
     val testScope = TestBodyCoroutine(createTestCoroutineScope(context + RunningInRunTest))
     return createTestResult {
-        runTestCoroutine(testScope, dispatchTimeoutMs.milliseconds, TestBodyCoroutine::tryGetCompletionCause, testBody) {
+        runTestCoroutine(testScope, dispatchTimeoutMs.milliseconds, null, TestBodyCoroutine::tryGetCompletionCause, testBody) {
             try {
                 testScope.cleanup()
                 emptyList()

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

@@ -99,14 +99,24 @@ class MultithreadingTest {
         }
     }
 
-    /** Tests that [StandardTestDispatcher] is confined to the thread that interacts with the scheduler. */
+    /** Tests that [StandardTestDispatcher] is not executed in-place but confined to the thread in which the
+     * virtual time control happens. */
     @Test
-    fun testStandardTestDispatcherIsConfined() = runTest {
+    fun testStandardTestDispatcherIsConfined(): Unit = runBlocking {
+        val scheduler = TestCoroutineScheduler()
         val initialThread = Thread.currentThread()
-        withContext(Dispatchers.IO) {
-            val ioThread = Thread.currentThread()
-            assertNotSame(initialThread, ioThread)
+        val job = launch(StandardTestDispatcher(scheduler)) {
+            assertEquals(initialThread, Thread.currentThread())
+            withContext(Dispatchers.IO) {
+                val ioThread = Thread.currentThread()
+                assertNotSame(initialThread, ioThread)
+            }
+            assertEquals(initialThread, Thread.currentThread())
+        }
+        scheduler.advanceUntilIdle()
+        while (job.isActive) {
+            scheduler.receiveDispatchEvent()
+            scheduler.advanceUntilIdle()
         }
-        assertEquals(initialThread, Thread.currentThread())
     }
 }

kotlinx-coroutines-test/jvm/test/MultithreadingTest.kt

@@ -4,6 +4,7 @@
 
 package kotlinx.coroutines.test
 import kotlinx.coroutines.*
+import kotlin.native.concurrent.*
 
 @Suppress("ACTUAL_WITHOUT_EXPECT")
 public actual typealias TestResult = Unit
@@ -13,3 +14,12 @@ internal actual fun createTestResult(testProcedure: suspend CoroutineScope.() ->
         testProcedure()
     }
 }
+
+internal actual fun getLastKnownPosition(): Any? = null
+
+@OptIn(ExperimentalStdlibApi::class)
+internal actual fun dumpCoroutinesAndThrow(exception: Throwable, lastKnownPosition: Any?) {
+    // log exception
+    processUnhandledException(exception)
+    throw exception
+}