- Finished making TestCoroutineExceptionHandler threadsafe

- Added missing defaults to ctor of TestCoroutineScope
- Docs cleanup & tests for coverage

Author: objcode

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

@@ -1,10 +1,11 @@
+@file:JvmName("TestBuilders")
+
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
 import kotlin.coroutines.ContinuationInterceptor
 import kotlin.coroutines.CoroutineContext
 
-
 /**
  * Executes a [testBody] inside an immediate execution dispatcher.
  *
@@ -35,9 +36,10 @@ import kotlin.coroutines.CoroutineContext
  * @throws UncompletedCoroutinesError If the [testBody] does not complete (or cancel) all coroutines that it launches
  * (including coroutines suspended on join/await).
  *
- * @param context An optional context that MAY contain a [DelayController] and/or [TestCoroutineExceptionHandler]
+ * @param context An optional context that MUST contain a [DelayController] and/or [TestCoroutineCoroutineExceptionHandler]
  * @param testBody The code of the unit-test.
  */
+@ExperimentalCoroutinesApi
 fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend TestCoroutineScope.() -> Unit) {
     val (safeContext, dispatcher) = context.checkArguments()
     // smart cast dispatcher to expose interface
@@ -60,26 +62,28 @@ fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend TestCor
     }
 }
 
-private fun CoroutineContext.activeJobs() =
-        checkNotNull(this[Job]).children.filter { it.isActive }.toSet()
+private fun CoroutineContext.activeJobs(): Set<Job> {
+    return checkNotNull(this[Job]).children.filter { it.isActive }.toSet()
+}
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
  */
+@ExperimentalCoroutinesApi
 fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
     runBlockingTest(coroutineContext, block)
 }
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
- *
  */
+@ExperimentalCoroutinesApi
 fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
     runBlockingTest(this, block)
 }
 
 private fun CoroutineContext?.checkArguments(): Pair<CoroutineContext, ContinuationInterceptor> {
-    var safeContext= this ?: TestCoroutineExceptionHandler() + TestCoroutineDispatcher()
+    var safeContext= this ?: TestCoroutineCoroutineExceptionHandler() + TestCoroutineDispatcher()
 
     val dispatcher = safeContext[ContinuationInterceptor].run {
         this?.let {
@@ -90,9 +94,9 @@ private fun CoroutineContext?.checkArguments(): Pair<CoroutineContext, Continuat
 
     val exceptionHandler = safeContext[CoroutineExceptionHandler].run {
         this?.let {
-            require(this is ExceptionCaptor) { "coroutineExceptionHandler must implement ExceptionCaptor" }
+            require(this is UncaughtExceptionCaptor) { "coroutineExceptionHandler must implement UncaughtExceptionCaptor" }
         }
-        this ?: TestCoroutineExceptionHandler()
+        this ?: TestCoroutineCoroutineExceptionHandler()
     }
 
     val job = safeContext[Job] ?: SupervisorJob()

core/kotlinx-coroutines-test/src/TestCoroutineExceptionHandler.kt renamed to core/kotlinx-coroutines-test/src/TestCoroutineCoroutineExceptionHandler.kt

@@ -1,24 +1,22 @@
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.CoroutineExceptionHandler
-import java.util.*
+import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlin.coroutines.CoroutineContext
 
 /**
- * Access uncaught coroutines exceptions captured during test execution.
- *
- * Note, tests executed via [runBlockingTest] or [TestCoroutineScope.runBlocking] will not trigger uncaught exception
- * handling and should use [Deferred.await] or [Job.getCancellationException] to test exceptions.
+ * Access uncaught coroutine exceptions captured during test execution.
  */
-interface ExceptionCaptor {
+@ExperimentalCoroutinesApi
+interface UncaughtExceptionCaptor {
     /**
      * List of uncaught coroutine exceptions.
      *
      * The returned list will be a copy of the currently caught exceptions.
      *
      * During [cleanupTestCoroutines] the first element of this list will be rethrown if it is not empty.
      */
-    val exceptions: List<Throwable>
+    val uncaughtExceptions: List<Throwable>
 
     /**
      * Call after the test completes.
@@ -31,11 +29,11 @@ interface ExceptionCaptor {
 /**
  * An exception handler that can be used to capture uncaught exceptions in tests.
  */
-class TestCoroutineExceptionHandler: ExceptionCaptor, CoroutineExceptionHandler {
-    val lock = Object()
+@ExperimentalCoroutinesApi
+class TestCoroutineCoroutineExceptionHandler: UncaughtExceptionCaptor, CoroutineExceptionHandler {
 
     override fun handleException(context: CoroutineContext, exception: Throwable) {
-        synchronized(lock) {
+        synchronized(_exceptions) {
             _exceptions += exception
         }
     }
@@ -44,11 +42,11 @@ class TestCoroutineExceptionHandler: ExceptionCaptor, CoroutineExceptionHandler
 
     private val _exceptions = mutableListOf<Throwable>()
 
-    override val exceptions
-        get() = _exceptions.toList()
+    override val uncaughtExceptions
+        get() = synchronized(_exceptions) { _exceptions.toList() }
 
     override fun cleanupTestCoroutines() {
-        synchronized(lock) {
+        synchronized(_exceptions) {
             val exception = _exceptions.firstOrNull() ?: return
             throw exception
         }

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

@@ -11,13 +11,15 @@ import kotlin.coroutines.CoroutineContext
  *
  * Testing libraries may expose this interface to tests instead of [TestCoroutineDispatcher].
  */
+@ExperimentalCoroutinesApi
 interface DelayController {
     /**
      * Returns the current virtual clock-time as it is known to this Dispatcher.
      *
      * @param unit The [TimeUnit] in which the clock-time must be returned.
      * @return The virtual clock-time
      */
+    @ExperimentalCoroutinesApi
     fun currentTime(unit: TimeUnit = TimeUnit.MILLISECONDS): Long
 
     /**
@@ -30,27 +32,31 @@ interface DelayController {
      * @param unit The [TimeUnit] in which [delayTime] and the return value is expressed.
      * @return The amount of delay-time that this Dispatcher's clock has been forwarded.
      */
+    @ExperimentalCoroutinesApi
     fun advanceTimeBy(delayTime: Long, unit: TimeUnit = TimeUnit.MILLISECONDS): Long
 
     /**
      * 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.
      */
+    @ExperimentalCoroutinesApi
     fun advanceTimeToNextDelayed(): Long
 
     /**
      * 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.
      */
+    @ExperimentalCoroutinesApi
     fun advanceUntilIdle(): Long
 
     /**
      * Run any tasks that are pending at or before the current virtual clock-time.
      *
      * Calling this function will never advance the clock.
      */
+    @ExperimentalCoroutinesApi
     fun runCurrent()
 
     /**
@@ -59,6 +65,7 @@ interface DelayController {
      * @throws UncompletedCoroutinesError if any pending tasks are active, however it will not throw for suspended
      * coroutines.
      */
+    @ExperimentalCoroutinesApi
     @Throws(UncompletedCoroutinesError::class)
     fun cleanupTestCoroutines()
 
@@ -71,6 +78,7 @@ interface DelayController {
      * 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.
      */
+    @ExperimentalCoroutinesApi
     suspend fun pauseDispatcher(block: suspend () -> Unit)
 
     /**
@@ -79,6 +87,7 @@ interface DelayController {
      * 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.
      */
+    @ExperimentalCoroutinesApi
     fun pauseDispatcher()
 
     /**
@@ -88,6 +97,7 @@ interface DelayController {
      * time and execute coroutines scheduled in the future use one of [advanceTimeBy], [advanceTimeToNextDelayed],
      * or [advanceUntilIdle].
      */
+    @ExperimentalCoroutinesApi
     fun resumeDispatcher()
 
     @Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
@@ -112,12 +122,13 @@ interface DelayController {
 /**
  * Thrown when a test has completed by there are tasks that are not completed or cancelled.
  */
+@ExperimentalCoroutinesApi
 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.
  *
- * By default, [TestCoroutineDispatcher] will be immediate. That means any tasks scheduled to be run immediately will
+ * By default, [TestCoroutineDispatcher] will be immediate. That means any tasks scheduled to be run without delay 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]
  *
@@ -127,6 +138,7 @@ class UncompletedCoroutinesError(message: String, cause: Throwable? = null): Ass
  *
  * @see DelayController
  */
+@ExperimentalCoroutinesApi
 class TestCoroutineDispatcher:
         CoroutineDispatcher(),
         Delay,
@@ -171,7 +183,7 @@ class TestCoroutineDispatcher:
         }
     }
 
-    override fun toString(): String = "TestCoroutineDispatcher[time=$time ns]"
+    override fun toString(): String = "TestCoroutineDispatcher[time=${time}ns]"
 
     private fun post(block: Runnable) =
             queue.addLast(TimedRunnable(block, counter++))

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

@@ -8,24 +8,12 @@ import kotlinx.coroutines.*
 import kotlin.coroutines.ContinuationInterceptor
 import kotlin.coroutines.CoroutineContext
 
+
 /**
  * A scope which provides detailed control over the execution of coroutines for tests.
- *
- * @param context an optional context that must provide delegates [ExceptionCaptor] and [DelayController]
  */
-class TestCoroutineScope(
-        context: CoroutineContext = TestCoroutineDispatcher() + TestCoroutineExceptionHandler()):
-        CoroutineScope,
-        ExceptionCaptor by context.exceptionDelegate,
-        DelayController by context.delayDelegate
-{
-    override fun cleanupTestCoroutines() {
-        coroutineContext.exceptionDelegate.cleanupTestCoroutines()
-        coroutineContext.delayDelegate.cleanupTestCoroutines()
-    }
-
-    override val coroutineContext = context
-
+@ExperimentalCoroutinesApi
+interface TestCoroutineScope: CoroutineScope, UncaughtExceptionCaptor, DelayController {
     /**
      * This method is deprecated.
      *
@@ -37,21 +25,54 @@ class TestCoroutineScope(
     fun cancelAllActions() = cleanupTestCoroutines()
 }
 
-fun TestCoroutineScope(dispatcher: TestCoroutineDispatcher) =
-        TestCoroutineScope(dispatcher + TestCoroutineExceptionHandler())
+private class TestCoroutineScopeImpl (
+        context: CoroutineContext = TestCoroutineDispatcher() + TestCoroutineCoroutineExceptionHandler()):
+        TestCoroutineScope,
+        UncaughtExceptionCaptor by context.uncaughtExceptionDelegate,
+        DelayController by context.delayDelegate
+{
+
+    override fun cleanupTestCoroutines() {
+        coroutineContext.uncaughtExceptionDelegate.cleanupTestCoroutines()
+        coroutineContext.delayDelegate.cleanupTestCoroutines()
+    }
+
+    override val coroutineContext = context
+}
+
+/**
+ * A scope which provides detailed control over the execution of coroutines for tests.
+ *
+ * If the provided context does not provide a [ContinuationInterceptor] (Dispatcher) or [CoroutineExceptionHandler], the
+ * scope will add [TestCoroutineDispatcher] and [TestCoroutineExceptionHandler] automatically.
+ *
+ * @param context an optional context that MAY provide [UncaughtExceptionCaptor] and/or [DelayController]
+ */
+@ExperimentalCoroutinesApi
+fun TestCoroutineScope(context: CoroutineContext? = null): TestCoroutineScope {
+    var safeContext = context ?: return TestCoroutineScopeImpl()
+    if (context[ContinuationInterceptor] == null) {
+        safeContext += TestCoroutineDispatcher()
+    }
+    if (context[CoroutineExceptionHandler] == null) {
+        safeContext += TestCoroutineCoroutineExceptionHandler()
+    }
+
+    return TestCoroutineScopeImpl(safeContext)
+}
 
-private inline val CoroutineContext.exceptionDelegate: ExceptionCaptor
+private inline val CoroutineContext.uncaughtExceptionDelegate: UncaughtExceptionCaptor
     get() {
         val handler = this[CoroutineExceptionHandler]
-        return handler as? ExceptionCaptor ?: throw
-            IllegalArgumentException("TestCoroutineScope requires a ExceptionCaptor as the " +
-                    "CoroutineExceptionHandler")
+        return handler as? UncaughtExceptionCaptor ?: throw
+            IllegalArgumentException("TestCoroutineScope requires a UncaughtExceptionCaptor such as " +
+                    "TestCoroutineCoroutineExceptionHandler as the CoroutineExceptionHandler")
     }
 
 private inline val CoroutineContext.delayDelegate: DelayController
     get() {
         val handler = this[ContinuationInterceptor]
         return handler as? DelayController ?: throw
-            IllegalArgumentException("TestCoroutineScope requires a DelayController as the " +
-                    "ContinuationInterceptor (Dispatcher)")
+            IllegalArgumentException("TestCoroutineScope requires a DelayController such as TestCoroutineDispatcher as " +
+                    "the ContinuationInterceptor (Dispatcher)")
     }

core/kotlinx-coroutines-test/test/TestTestBuilders.kt renamed to core/kotlinx-coroutines-test/test/TestBuildersTest.kt

@@ -8,7 +8,7 @@ import org.junit.*
 import org.junit.Assert.*
 import kotlin.coroutines.ContinuationInterceptor
 
-class TestTestBuilders {
+class TestBuildersTest {
 
     @Test
     fun scopeRunBlocking_passesDispatcher() {