API changes from review. Cleaning up docs.

Author: objcode

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

@@ -44,9 +44,9 @@ import kotlin.coroutines.CoroutineContext
  *
  * @throws UncompletedCoroutinesError If the [testBody] does not complete (or cancel) all coroutines that it launches
  * (including coroutines suspended on await).
- * @throws UnhandledExceptionsError If an uncaught exception is not handled by [testBody]
+ * @throws Throwable If an uncaught exception was captured by this test it will be rethrown.
  *
- * @param dispatcher An optional dispatcher, during [testBody] execution [TestCoroutineDispatcher.dispatchImmediately] will be set to false
+ * @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]
@@ -106,10 +106,15 @@ fun TestCoroutineScope.asyncTest(testBody: TestCoroutineScope.() -> Unit) =
  *
  * ```
  *
- * [runBlockingTest] will allow tests to finish successfully while started coroutines are unfinished. In addition unhandled
- * exceptions inside coroutines will not fail the test.
+ * 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.
  *
- * @param dispatcher An optional dispatcher, during [testBody] execution [TestCoroutineDispatcher.dispatchImmediately] will be set to true
+ * @throws UncompletedCoroutinesError If the [testBody] does not complete (or cancel) all coroutines that it launches
+ * (including coroutines suspended on await).
+ *
+ * @param context An optional context, during [testBody] execution [DelayController.dispatchImmediately] will be set to true
  * @param testBody The code of the unit-test.
  *
  * @see [asyncTest]
@@ -127,58 +132,44 @@ fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend Corouti
             scope.testBody()
             scope.cleanupTestCoroutines()
         }
+        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
     }
 }
 
 /**
- * Convenience method for calling runBlocking on an existing [TestCoroutineScope].
- *
- * [block] will be executed in immediate execution mode, similar to [runBlockingTest].
+ * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
  */
-fun <T> TestCoroutineScope.runBlocking(block: suspend CoroutineScope.() -> T): T {
-    val oldDispatch = dispatchImmediately
-    dispatchImmediately = true
-    try {
-        return runBlocking(coroutineContext, block)
-    } finally {
-        dispatchImmediately = oldDispatch
-    }
+fun TestCoroutineScope.runBlockingTest(block: suspend CoroutineScope.() -> Unit) {
+    runBlockingTest(coroutineContext, block)
 }
 
 /**
- * Convenience method for calling runBlocking on an existing [TestCoroutineDispatcher].
+ * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
  *
- * [block] will be executed in immediate execution mode, similar to [runBlockingTest].
  */
-fun <T> TestCoroutineDispatcher.runBlocking(block: suspend CoroutineScope.() -> T): T {
-    val oldDispatch = dispatchImmediately
-    dispatchImmediately = true
-    try {
-        return runBlocking(this, block)
-    } finally {
-        dispatchImmediately = oldDispatch
-    }
+fun TestCoroutineDispatcher.runBlockingTest(block: suspend CoroutineScope.() -> Unit) {
+    runBlockingTest(this, block)
 }
 
 private fun CoroutineContext?.checkArguments(): Pair<CoroutineContext, ContinuationInterceptor> {
     var safeContext= this ?: TestCoroutineExceptionHandler() + TestCoroutineDispatcher()
 
     val dispatcher = safeContext[ContinuationInterceptor].run {
         this?.let {
-            if (this !is DelayController) {
-                throw IllegalArgumentException("Dispatcher must implement DelayController")
-            }
+            require(this is DelayController) { "Dispatcher must implement DelayController" }
         }
         this ?: TestCoroutineDispatcher()
     }
 
     val exceptionHandler = safeContext[CoroutineExceptionHandler].run {
         this?.let {
-            if (this !is ExceptionCaptor) {
-                throw IllegalArgumentException("coroutineExceptionHandler must implement ExceptionCaptor")
-            }
+            require(this is ExceptionCaptor) { "coroutineExceptionHandler must implement ExceptionCaptor" }
         }
         this ?: TestCoroutineExceptionHandler()
     }

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

@@ -3,7 +3,6 @@ package kotlinx.coroutines.test
 import kotlinx.coroutines.*
 import kotlinx.coroutines.internal.ThreadSafeHeap
 import kotlinx.coroutines.internal.ThreadSafeHeapNode
-import java.lang.IllegalStateException
 import java.util.concurrent.TimeUnit
 import kotlin.coroutines.CoroutineContext
 
@@ -24,8 +23,8 @@ interface DelayController {
     /**
      * Moves the Dispatcher's virtual clock forward by a specified amount of time.
      *
-     * The returned delay-time can be larger than the specified delay-time if the code
-     * under test contains *blocking* Coroutines.
+     * The amount the clock is progressed may be larger than the requested delayTime if the code under test uses
+     * blocking coroutines.
      *
      * @param delayTime The amount of time to move the CoroutineContext's clock forward.
      * @param unit The [TimeUnit] in which [delayTime] and the return value is expressed.
@@ -34,20 +33,18 @@ interface DelayController {
     fun advanceTimeBy(delayTime: Long, unit: TimeUnit = TimeUnit.MILLISECONDS): Long
 
     /**
-     * Moves the current virtual clock forward until the next pending delay.
-     *
-     * Any pending immediate dispatches will be executed, and the clock will be advanced to the next delayed dispatch.
+     * Moves the current virtual clock forward just far enough so the next delay will return.
      *
      * @return the amount of delay-time that this Dispatcher's clock has been forwarded.
      */
     fun advanceTimeToNextDelayed(): Long
 
     /**
-     * Immediately execute all pending tasks and advance the virtual clock-time to the latest delay.
+     * Immediately execute all pending tasks and advance the virtual clock-time to the last delay.
      *
      * @return the amount of delay-time that this Dispatcher's clock has been forwarded.
      */
-    fun runUntilIdle(): Long
+    fun advanceUntilIdle(): Long
 
     /**
      * Run any tasks that are pending at or before the current virtual clock-time.
@@ -129,7 +126,7 @@ class TestCoroutineDispatcher:
             field = value
             if (value) {
                 // there may already be tasks from setup code we need to run
-                runUntilIdle()
+                advanceUntilIdle()
             }
         }
 
@@ -225,7 +222,7 @@ class TestCoroutineDispatcher:
         return time - oldTime
     }
 
-    override fun runUntilIdle(): Long {
+    override fun advanceUntilIdle(): Long {
         val oldTime = time
         while(!queue.isEmpty) {
             advanceTimeToNextDelayed()

core/kotlinx-coroutines-core/src/test_/TestCoroutineExceptionHandler.kt

@@ -14,38 +14,18 @@ interface ExceptionCaptor {
     /**
      * List of uncaught coroutine exceptions.
      *
-     * Tests must process these exceptions prior to [cleanupTestCoroutines] either by clearing this list with
-     * [exceptions.clear] or calling [rethrowUncaughtCoroutineException].
+     * During [cleanupTestCoroutines] the first element of this list will be rethrown if it is not empty.
      */
     val exceptions: MutableList<Throwable>
 
-    /**
-     * Rethrow the first uncaught coroutine exception immediately.
-     *
-     * This allows tests to use their preferred exception testing techniques.
-     *
-     * If a test generates uncaught exceptions, it must call this method, or clear [exceptions] prior to calling
-     * [cleanupTestCoroutines].
-     */
-    fun rethrowUncaughtCoroutineException(): Nothing
-
     /**
      * Call after the test completes.
      *
-     * @throws UnhandledExceptionsError if any exceptions have not been handled via [rethrowUncaughtCoroutineException]
-     * or ignored via [exceptions.clear]
+     * @throws Throwable the first uncaught exception, if there are any uncaught exceptions
      */
     fun cleanupTestCoroutines()
 }
 
-/**
- * Thrown when a test completes with uncaught exceptions that have not been handled.
- *
- * @param message descriptive message
- * @param cause the first uncaught exception
- */
-class UnhandledExceptionsError(message: String, cause: Throwable): AssertionError(message, cause)
-
 /**
  * An exception handler that can be used to capture uncaught exceptions in tests.
  */
@@ -58,16 +38,8 @@ class TestCoroutineExceptionHandler: ExceptionCaptor, CoroutineExceptionHandler
 
     override val exceptions = LinkedList<Throwable>()
 
-    override fun rethrowUncaughtCoroutineException(): Nothing {
-        if(!exceptions.isEmpty()) {
-            throw exceptions.removeAt(0)
-        }
-        throw AssertionError("No exceptions were caught to rethrow")
-    }
-
     override fun cleanupTestCoroutines() {
         val exception = exceptions.firstOrNull() ?: return
-        throw UnhandledExceptionsError("Unhandled exceptions were not processed by test. " +
-                "Call rethrowUncaughtCoroutineException() to handle uncaught exceptions.", exception)
+        throw exception
     }
 }

core/kotlinx-coroutines-core/test/test/TestAsyncTest.kt

@@ -219,7 +219,7 @@ class TestAsyncTest {
         }
     }
 
-    @Test(expected = AssertionError::class)
+    @Test(expected = IllegalAccessError::class)
     fun testWithTestContextThrowingAnAssertionError() = asyncTest {
         val expectedError = IllegalAccessError("hello")
 
@@ -240,7 +240,6 @@ class TestAsyncTest {
         }
 
         runCurrent()
-        rethrowUncaughtCoroutineException()
     }
 
     @Test(expected = IllegalArgumentException::class)
@@ -255,8 +254,6 @@ class TestAsyncTest {
 
         advanceTimeBy(delay)
         assertTrue(job.isCancelled)
-
-        rethrowUncaughtCoroutineException()
     }
 
     @Test
@@ -367,7 +364,7 @@ class TestAsyncTest {
         }
     }
 
-    @Test(expected = UnhandledExceptionsError::class)
+    @Test(expected = IllegalArgumentException::class)
     fun asyncTest_withUnhandledExceptions_failsTest() {
         asyncTest {
             launch {
@@ -422,7 +419,7 @@ class TestAsyncTest {
                 }
             }
 
-            this.runBlocking {
+            this.runBlockingTest {
                 // the only way to make the thread switch is to use runBlocking and await()
                 assertEquals(3, deferred.await())
             }
@@ -447,7 +444,7 @@ class TestAsyncTest {
                     3
                 }
             }
-            runUntilIdle()
+            advanceUntilIdle()
             assertEquals(3, deferred.getCompleted())
         }
     }

core/kotlinx-coroutines-core/test/test/TestRunBlockingTest.kt

@@ -269,8 +269,8 @@ class TestRunBlockingTest {
         job.join()
     }
 
-    @Test
-    fun whenACoroutineLeaks_thereIsNoError() = runBlockingTest {
+    @Test(expected = UncompletedCoroutinesError::class)
+    fun whenACoroutineLeaks_errorIsThrown() = runBlockingTest {
         val uncompleted = CompletableDeferred<Unit>()
         launch {
             uncompleted.await()

core/kotlinx-coroutines-core/test/test/TestTestBuilders.kt

@@ -13,15 +13,15 @@ class TestTestBuilders {
     @Test
     fun scopeRunBlocking_passesDispatcher() {
         val scope = TestCoroutineScope()
-        scope.runBlocking {
+        scope.runBlockingTest {
             assertSame(scope.coroutineContext[ContinuationInterceptor], coroutineContext[ContinuationInterceptor])
         }
     }
 
     @Test
     fun dispatcherRunBlocking_passesDispatcher() {
         val dispatcher = TestCoroutineDispatcher()
-        dispatcher.runBlocking {
+        dispatcher.runBlockingTest {
             assertSame(dispatcher, coroutineContext[ContinuationInterceptor])
         }
     }
@@ -34,7 +34,7 @@ class TestTestBuilders {
             3
         }
 
-        scope.runBlocking {
+        scope.runBlockingTest {
             assertRunsFast {
                 assertEquals(3, deferred.await())
             }
@@ -50,7 +50,7 @@ class TestTestBuilders {
             3
         }
 
-        dispatcher.runBlocking {
+        dispatcher.runBlockingTest {
             assertRunsFast {
                 assertEquals(3, deferred.await())
             }
@@ -60,7 +60,7 @@ class TestTestBuilders {
     @Test
     fun scopeRunBlocking_disablesImmedateOnExit() {
         val scope = TestCoroutineScope()
-        scope.runBlocking {
+        scope.runBlockingTest {
             assertRunsFast {
                 delay(SLOW)
             }
@@ -109,7 +109,7 @@ class TestTestBuilders {
         val scope = TestCoroutineScope()
         var calls = 0
 
-        val result = scope.runBlocking {
+        scope.runBlockingTest {
             delay(1_000)
             calls++
             asyncTest {
@@ -118,13 +118,13 @@ class TestTestBuilders {
                     calls++
                 }
                 assertTrue(job.isActive)
-                runUntilIdle()
+                advanceUntilIdle()
                 assertFalse(job.isActive)
                 calls++
             }
             ++calls
         }
 
-        assertEquals(4, result)
+        assertEquals(4, calls)
     }
 }