API Cleanup based on review

- removed asyncTest
- added pauseDispatcher(), pausDispatcher(block), and resumeDispatcher() API to delayController
- removed dispatchImmediately (the name was fairly opaque in an actual test case)
- added exception handling to runBlockingTest

Author: objcode

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

@@ -1,108 +1,17 @@
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
-import java.util.concurrent.TimeoutException
 import kotlin.coroutines.ContinuationInterceptor
 import kotlin.coroutines.CoroutineContext
-import kotlin.coroutines.coroutineContext
 
-/**
- * Executes a [testBody] in a [TestCoroutineScope] which provides detailed control over the execution of coroutines.
- *
- * This function should be used when you need detailed control over the execution of your test. For most tests consider
- * using [runBlockingTest].
- *
- * Code executed in a `asyncTest` will dispatch lazily. That means calling builders such as [launch] or [async] will
- * not execute the block immediately. You can use methods like [TestCoroutineScope.runCurrent] and
- * [TestCoroutineScope.advanceTimeTo] on the [TestCoroutineScope]. For a full list of execution methods see
- * [DelayController].
- *
- * ```
- * @Test
- * fun exampleTest() = asyncTest {
- *     // 1: launch will execute but not run the body
- *     launch  {
- *         // 3: the body of launch will execute in response to runCurrent [currentTime = 0ms]
- *         delay(1_000)
- *         // 5: After the time is advanced, delay(1_000) will return [currentTime = 1000ms]
- *         println("Faster delays!")
- *     }
- *
- *     // 2: use runCurrent() to execute the body of launch [currentTime = 0ms]
- *     runCurrent()
- *
- *     // 4: advance the dispatcher "time" by 1_000, which will resume after the delay
- *     advanceTimeTo(1_000)
- *
- * ```
- *
- * This method requires that all coroutines launched inside [testBody] complete, or are cancelled, as part of the test
- * conditions.
- *
- * In addition any unhandled exceptions thrown in coroutines must be rethrown by
- * [TestCoroutineScope.rethrowUncaughtCoroutineException] or cleared via [TestCoroutineScope.exceptions] inside of
- * [testBody].
- *
- * @throws UncompletedCoroutinesError If the [testBody] does not complete (or cancel) all coroutines that it launches
- * (including coroutines suspended on await).
- * @throws Throwable If an uncaught exception was captured by this test it will be rethrown.
- *
- * @param context An optional dispatcher, during [testBody] execution [DelayController.dispatchImmediately] will be set to false
- * @param testBody The code of the unit-test.
- *
- * @see [runBlockingTest]
- */
-fun asyncTest(context: CoroutineContext? = null, testBody: TestCoroutineScope.() -> Unit) {
-    val (safeContext, dispatcher) = context.checkArguments()
-    // smart cast dispatcher to expose interface
-    dispatcher as DelayController
-    val scope = TestCoroutineScope(safeContext)
-
-    val oldDispatch = dispatcher.dispatchImmediately
-    dispatcher.dispatchImmediately = false
-
-    try {
-        scope.testBody()
-        scope.cleanupTestCoroutines()
-
-        // check for any active child jobs after cleanup (e.g. coroutines suspended on calls to await)
-        val job = checkNotNull(safeContext[Job]) { "Job required for asyncTest" }
-        val activeChildren = job.children.filter { it.isActive }.toList()
-        if (activeChildren.isNotEmpty()) {
-            throw UncompletedCoroutinesError("Test finished with active jobs: ${activeChildren}")
-        }
-    } finally {
-        dispatcher.dispatchImmediately = oldDispatch
-    }
-}
-
-/**
- * @see [asyncTest]
- */
-fun TestCoroutineScope.asyncTest(testBody: TestCoroutineScope.() -> Unit) =
-        asyncTest(coroutineContext, testBody)
-
-/**
- * This method is deprecated.
- *
- * @see [cleanupTestCoroutines]
- */
-@Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
-        ReplaceWith("scope.runBlockingTest(testBody)", "kotlinx.coroutines.test"),
-        level = DeprecationLevel.ERROR)
-fun withTestContext(scope: TestCoroutineScope, testBody: suspend TestCoroutineScope.() -> Unit) {
-    scope.runBlockingTest(testBody)
-}
 
 /**
  * Executes a [testBody] inside an immediate execution dispatcher.
  *
  * This is similar to [runBlocking] but it will immediately progress past delays and into [launch] and [async] blocks.
  * You can use this to write tests that execute in the presence of calls to [delay] without causing your test to take
  * extra time.
- *
- * Compared to [asyncTest], it provides a smaller API for tests that don't need detailed control over execution.
- *
+ **
  * ```
  * @Test
  * fun exampleTest() = runBlockingTest {
@@ -121,43 +30,39 @@ fun withTestContext(scope: TestCoroutineScope, testBody: suspend TestCoroutineSc
  * This method requires that all coroutines launched inside [testBody] complete, or are cancelled, as part of the test
  * conditions.
  *
- * In unhandled exceptions inside coroutines will not fail the test.
+ * Unhandled exceptions thrown by coroutines in the test will be re-thrown at the end of the test.
  *
  * @throws UncompletedCoroutinesError If the [testBody] does not complete (or cancel) all coroutines that it launches
- * (including coroutines suspended on await).
+ * (including coroutines suspended on join/await).
  *
- * @param context An optional context, during [testBody] execution [DelayController.dispatchImmediately] will be set to true
+ * @param context An optional context that MAY contain a [DelayController] and/or [TestCoroutineExceptionHandler]
  * @param testBody The code of the unit-test.
- *
- * @see [asyncTest]
  */
 fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend TestCoroutineScope.() -> Unit) {
     val (safeContext, dispatcher) = context.checkArguments()
     // smart cast dispatcher to expose interface
     dispatcher as DelayController
 
-    val oldDispatch = dispatcher.dispatchImmediately
-    dispatcher.dispatchImmediately = true
-    val scope = TestCoroutineScope(safeContext)
-    try {
+    val startingJobs = safeContext.activeJobs()
 
-        val deferred = scope.async {
-            scope.testBody()
-        }
-        dispatcher.advanceUntilIdle()
-        deferred.getCompletionExceptionOrNull()?.let {
-            throw it
-        }
-        scope.cleanupTestCoroutines()
-        val activeChildren = checkNotNull(safeContext[Job]).children.filter { it.isActive }.toList()
-        if (activeChildren.isNotEmpty()) {
-            throw UncompletedCoroutinesError("Test finished with active jobs: ${activeChildren}")
-        }
-    } finally {
-        dispatcher.dispatchImmediately = oldDispatch
+    val scope = TestCoroutineScope(safeContext)
+    val deferred = scope.async {
+        scope.testBody()
+    }
+    dispatcher.advanceUntilIdle()
+    deferred.getCompletionExceptionOrNull()?.let {
+        throw it
+    }
+    scope.cleanupTestCoroutines()
+    val endingJobs = safeContext.activeJobs()
+    if ((endingJobs - startingJobs).isNotEmpty()) {
+        throw UncompletedCoroutinesError("Test finished with active jobs: $endingJobs")
     }
 }
 
+private fun CoroutineContext.activeJobs() =
+        checkNotNull(this[Job]).children.filter { it.isActive }.toSet()
+
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
  */
@@ -194,4 +99,16 @@ private fun CoroutineContext?.checkArguments(): Pair<CoroutineContext, Continuat
 
     safeContext = safeContext + dispatcher + exceptionHandler + job
     return Pair(safeContext, dispatcher)
+}
+
+/**
+ * This method is deprecated.
+ *
+ * @see [cleanupTestCoroutines]
+ */
+@Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
+        ReplaceWith("scope.runBlockingTest(testBody)", "kotlinx.coroutines.test"),
+        level = DeprecationLevel.ERROR)
+fun withTestContext(scope: TestCoroutineScope, testBody: suspend TestCoroutineScope.() -> Unit) {
+    scope.runBlockingTest(testBody)
 }

core/kotlinx-coroutines-test/src/TestCoroutineDispatcher.kt

@@ -57,45 +57,38 @@ interface DelayController {
      * Call after a test case completes.
      *
      * @throws UncompletedCoroutinesError if any pending tasks are active, however it will not throw for suspended
-     * coroutines that called await.
+     * coroutines.
      */
     @Throws(UncompletedCoroutinesError::class)
     fun cleanupTestCoroutines()
 
     /**
-     * When true, this dispatcher will perform as an immediate executor.
+     * Run a block of code in a paused dispatcher.
      *
-     * It will immediately run any tasks, which means it will auto-advance the virtual clock-time to the last pending
-     * delay.
+     * By pausing the dispatcher any new coroutines will not execute immediately. After block executes, the dispatcher
+     * will resume auto-advancing.
      *
-     * Test code will rarely call this method directly., Instead use a test builder like [asyncTest], [runBlockingTest] or
-     * the convenience methods [TestCoroutineDispatcher.runBlocking] and [TestCoroutineScope.runBlocking].
-     *
-     * ```
-     * @Test
-     * fun aTest() {
-     *     val scope = TestCoroutineScope() // dispatchImmediately is false
-     *     scope.async {
-     *         // delay will be pending execution (lazy mode)
-     *         delay(1_000)
-     *     }
-     *
-     *     scope.runBlocking {
-     *         // the pending delay will immediately execute
-     *         // dispatchImmediately is true
-     *     }
-     *
-     *     // scope is returned to lazy mode
-     *     // dispatchImmediately is false
-     * }
-     * ```
+     * This is useful when testing functions that that start a coroutine. By pausing the dispatcher assertions or
+     * setup may be done between the time the coroutine is created and started.
+     */
+    suspend fun pauseDispatcher(block: suspend () -> Unit)
+
+    /**
+     * Pause the dispatcher.
      *
-     * Setting this to true will immediately execute any pending tasks and advance the virtual clock-time to the last
-     * pending delay. While true, dispatch will continue to execute immediately, auto-advancing the virtual clock-time.
+     * When paused the dispatcher will not execute any coroutines automatically, and you must call [runCurrent], or one
+     * of [advanceTimeBy], [advanceTimeToNextDelayed], or [advanceUntilIdle] to execute coroutines.
+     */
+    fun pauseDispatcher()
+
+    /**
+     * Resume the dispatcher from a paused state.
      *
-     * Setting it to false will resume lazy execution.
+     * Resumed dispatchers will automatically progress through all coroutines scheduled at the current time. To advance
+     * time and execute coroutines scheduled in the future use one of [advanceTimeBy], [advanceTimeToNextDelayed],
+     * or [advanceUntilIdle].
      */
-    var dispatchImmediately: Boolean
+    fun resumeDispatcher()
 
     @Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
             ReplaceWith("if (targetTime > currentTime(unit)) { advanceTimeBy(targetTime - currentTime(unit), unit) }",
@@ -122,23 +115,24 @@ interface DelayController {
 class UncompletedCoroutinesError(message: String, cause: Throwable? = null): AssertionError(message, cause)
 
 /**
- * [CoroutineDispatcher] that can be used in tests for both immediate  and lazy execution of coroutines.
+ * [CoroutineDispatcher] that can be used in tests for both immediate and lazy execution of coroutines.
+ *
+ * By default, [TestCoroutineDispatcher] will be immediate. That means any tasks scheduled to be run immediately will
+ * be immediately executed. If they were scheduled with a delay, the virtual clock-time must be advanced via one of the
+ * methods on [DelayController]
  *
- * By default, [TestCoroutineDispatcher] will be lazy. That means any coroutines started via [launch] or [async] will
+ * When swiched to lazy execution any coroutines started via [launch] or [async] will
  * not execute until a call to [DelayController.runCurrent] or the virtual clock-time has been advanced via one of the
  * methods on [DelayController].
  *
- * When switched to immediate mode, any tasks will be immediately executed. If they were scheduled with a delay,
- * the virtual clock-time will auto-advance to the last submitted delay.
- *
  * @see DelayController
  */
 class TestCoroutineDispatcher:
         CoroutineDispatcher(),
         Delay,
         DelayController {
 
-    override var dispatchImmediately = false
+    private var dispatchImmediately = true
         set(value) {
             field = value
             if (value) {
@@ -166,9 +160,6 @@ class TestCoroutineDispatcher:
 
     override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) {
         postDelayed(CancellableContinuationRunnable(continuation) { resumeUndispatched(Unit) }, timeMillis)
-        if (dispatchImmediately) {
-//            advanceTimeBy(timeMillis, TimeUnit.MILLISECONDS)
-        }
     }
 
     override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
@@ -180,15 +171,6 @@ class TestCoroutineDispatcher:
         }
     }
 
-//    override fun processNextEvent(): Long {
-//        val current = queue.peek()
-//        if (current != null) {
-//            // Automatically advance time for EventLoop callbacks
-//            triggerActions(current.time)
-//        }
-//        return if (queue.isEmpty) Long.MAX_VALUE else 0L
-//    }
-
     override fun toString(): String = "TestCoroutineDispatcher[time=$time ns]"
 
     private fun post(block: Runnable) =
@@ -247,6 +229,26 @@ class TestCoroutineDispatcher:
         return time - oldTime
     }
 
+    override fun runCurrent() = triggerActions(time)
+
+    override suspend fun pauseDispatcher(block: suspend () -> Unit) {
+        val previous = dispatchImmediately
+        dispatchImmediately = false
+        try {
+            block()
+        } finally {
+            dispatchImmediately = previous
+        }
+    }
+
+    override fun pauseDispatcher() {
+        dispatchImmediately = false
+    }
+
+    override fun resumeDispatcher() {
+        dispatchImmediately = true
+    }
+
     override fun cleanupTestCoroutines() {
         // process any pending cancellations or completions, but don't advance time
         triggerActions(time)
@@ -266,8 +268,6 @@ class TestCoroutineDispatcher:
                     " completed or cancelled by your test.")
         }
     }
-
-    override fun runCurrent() = triggerActions(time)
 }