kotlinx-coroutines-test cleanup

  * Get rid of ThreadSafeHeap usages, make it internal again
  * Yield support in test dispatcher
  * Allow partial override of coroutine context
  * Code style fixes

Author: qwwdfsad

binary-compatibility-validator/reference-public-api/kotlinx-coroutines-test.txt

@@ -23,6 +23,7 @@ public final class kotlinx/coroutines/test/TestCoroutineDispatcher : kotlinx/cor
 	public fun cleanupTestCoroutines ()V
 	public fun delay (JLkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public fun dispatch (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Runnable;)V
+	public fun dispatchYield (Lkotlin/coroutines/CoroutineContext;Ljava/lang/Runnable;)V
 	public fun getCurrentTime ()J
 	public fun invokeOnTimeout (JLjava/lang/Runnable;)Lkotlinx/coroutines/DisposableHandle;
 	public fun pauseDispatcher ()V

kotlinx-coroutines-test/README.md

@@ -274,8 +274,8 @@ important to ensure that [cleanupTestCoroutines][TestCoroutineScope.cleanupTestC
 
 ```kotlin
 class TestClass {
-    val testScope = TestCoroutineScope()
-    lateinit var subject: Subject = null 
+    private val testScope = TestCoroutineScope()
+    private lateinit var subject: Subject = null 
 
     @Before
     fun setup() {

kotlinx-coroutines-test/src/TestBuilders.kt

@@ -13,7 +13,7 @@ import kotlin.coroutines.*
  * 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.
- **
+ *
  * ```
  * @Test
  * fun exampleTest() = runBlockingTest {
@@ -37,17 +37,14 @@ import kotlin.coroutines.*
  * @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 MUST contain a [DelayController] and/or [TestCoroutineExceptionHandler]
+ * @param context additional context elements. If [context] contains [CoroutineDispatcher] or [CoroutineExceptionHandler],
+ *        then they must implement [DelayController] and [TestCoroutineExceptionHandler] respectively.
  * @param testBody The code of the unit-test.
  */
 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0
-public fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend TestCoroutineScope.() -> Unit) {
+public fun runBlockingTest(context: CoroutineContext = EmptyCoroutineContext, testBody: suspend TestCoroutineScope.() -> Unit) {
     val (safeContext, dispatcher) = context.checkArguments()
-    // smart cast dispatcher to expose interface
-    dispatcher as DelayController
-
     val startingJobs = safeContext.activeJobs()
-
     val scope = TestCoroutineScope(safeContext)
     val deferred = scope.async {
         scope.testBody()
@@ -72,37 +69,28 @@ private fun CoroutineContext.activeJobs(): Set<Job> {
  */
 // todo: need documentation on how this extension is supposed to be used
 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0
-public fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
-    runBlockingTest(coroutineContext, block)
-}
+public fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) = runBlockingTest(coroutineContext, block)
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
  */
 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0
-public fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
-    runBlockingTest(this, block)
-}
+public fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) = runBlockingTest(this, block)
 
-private fun CoroutineContext?.checkArguments(): Pair<CoroutineContext, ContinuationInterceptor> {
-    var safeContext = this ?: TestCoroutineExceptionHandler() + TestCoroutineDispatcher()
-
-    val dispatcher = safeContext[ContinuationInterceptor].run {
-        this?.let {
-            require(this is DelayController) { "Dispatcher must implement DelayController" }
-        }
+private fun CoroutineContext.checkArguments(): Pair<CoroutineContext, DelayController> {
+    // TODO optimize it
+    val dispatcher = get(ContinuationInterceptor).run {
+        this?.let { require(this is DelayController) { "Dispatcher must implement DelayController: $this" } }
         this ?: TestCoroutineDispatcher()
     }
 
-    val exceptionHandler = safeContext[CoroutineExceptionHandler].run {
+    val exceptionHandler =  get(CoroutineExceptionHandler).run {
         this?.let {
-            require(this is UncaughtExceptionCaptor) { "coroutineExceptionHandler must implement UncaughtExceptionCaptor" }
+            require(this is UncaughtExceptionCaptor) { "coroutineExceptionHandler must implement UncaughtExceptionCaptor: $this" }
         }
         this ?: TestCoroutineExceptionHandler()
     }
 
-    val job = safeContext[Job] ?: SupervisorJob()
-
-    safeContext = safeContext + dispatcher + exceptionHandler + job
-    return Pair(safeContext, dispatcher)
-}
+    val job = get(Job) ?: SupervisorJob()
+    return Pair(this + dispatcher + exceptionHandler + job, dispatcher as DelayController)
+}

kotlinx-coroutines-test/src/TestCoroutineDispatcher.kt

@@ -136,6 +136,7 @@ public class TestCoroutineDispatcher: CoroutineDispatcher(), Delay, DelayControl
     // Storing time in nanoseconds internally.
     private val _time = atomic(0L)
 
+    /** @suppress */
     override fun dispatch(context: CoroutineContext, block: Runnable) {
         if (dispatchImmediately) {
             block.run()
@@ -144,10 +145,18 @@ public class TestCoroutineDispatcher: CoroutineDispatcher(), Delay, DelayControl
         }
     }
 
+    /** @suppress */
+    @InternalCoroutinesApi
+    override fun dispatchYield(context: CoroutineContext, block: Runnable) {
+        post(block)
+    }
+
+    /** @suppress */
     override fun scheduleResumeAfterDelay(timeMillis: Long, continuation: CancellableContinuation<Unit>) {
         postDelayed(CancellableContinuationRunnable(continuation) { resumeUndispatched(Unit) }, timeMillis)
     }
 
+    /** @suppress */
     override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
         val node = postDelayed(block, timeMillis)
         return object : DisposableHandle {
@@ -157,6 +166,7 @@ public class TestCoroutineDispatcher: CoroutineDispatcher(), Delay, DelayControl
         }
     }
 
+    /** @suppress */
     override fun toString(): String {
         return "TestCoroutineDispatcher[currentTime=${currentTime}ms, queued=${queue.size}]"
     }
@@ -186,8 +196,10 @@ public class TestCoroutineDispatcher: CoroutineDispatcher(), Delay, DelayControl
         }
     }
 
+    /** @suppress */
     override val currentTime get() = _time.value
 
+    /** @suppress */
     override fun advanceTimeBy(delayTimeMillis: Long): Long {
         val oldTime = currentTime
         advanceUntilTime(oldTime + delayTimeMillis)
@@ -204,6 +216,7 @@ public class TestCoroutineDispatcher: CoroutineDispatcher(), Delay, DelayControl
         _time.update { currentValue -> max(currentValue, targetTime) }
     }
 
+    /** @suppress */
     override fun advanceUntilIdle(): Long {
         val oldTime = currentTime
         while(!queue.isEmpty) {
@@ -214,8 +227,10 @@ public class TestCoroutineDispatcher: CoroutineDispatcher(), Delay, DelayControl
         return currentTime - oldTime
     }
 
+    /** @suppress */
     override fun runCurrent() = doActionsUntil(currentTime)
 
+    /** @suppress */
     override suspend fun pauseDispatcher(block: suspend () -> Unit) {
         val previous = dispatchImmediately
         dispatchImmediately = false
@@ -226,14 +241,17 @@ public class TestCoroutineDispatcher: CoroutineDispatcher(), Delay, DelayControl
         }
     }
 
+    /** @suppress */
     override fun pauseDispatcher() {
         dispatchImmediately = false
     }
 
+    /** @suppress */
     override fun resumeDispatcher() {
         dispatchImmediately = true
     }
 
+    /** @suppress */
     override fun cleanupTestCoroutines() {
         // process any pending cancellations or completions, but don't advance time
         doActionsUntil(currentTime)

kotlinx-coroutines-test/src/TestCoroutineExceptionHandler.kt

@@ -35,20 +35,22 @@ public interface UncaughtExceptionCaptor {
  * An exception handler that captures uncaught exceptions in tests.
  */
 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0
-public class TestCoroutineExceptionHandler:
+public class TestCoroutineExceptionHandler :
     AbstractCoroutineContextElement(CoroutineExceptionHandler), UncaughtExceptionCaptor, CoroutineExceptionHandler
 {
+    private val _exceptions = mutableListOf<Throwable>()
+
     override fun handleException(context: CoroutineContext, exception: Throwable) {
         synchronized(_exceptions) {
             _exceptions += exception
         }
     }
 
-    private val _exceptions = mutableListOf<Throwable>()
-
+    /** @suppress **/
     override val uncaughtExceptions
         get() = synchronized(_exceptions) { _exceptions.toList() }
 
+    /** @suppress **/
     override fun cleanupTestCoroutines() {
         synchronized(_exceptions) {
             val exception = _exceptions.firstOrNull() ?: return

kotlinx-coroutines-test/test/TestRunBlockingOrderTest.kt

@@ -6,6 +6,7 @@ package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
 import org.junit.*
+import kotlin.coroutines.*
 
 class TestRunBlockingOrderTest : TestBase() {
     @Test
@@ -17,6 +18,17 @@ class TestRunBlockingOrderTest : TestBase() {
         finish(3)
     }
 
+    @Test
+    fun testYield() = runBlockingTest {
+        expect(1)
+        launch {
+            expect(2)
+            yield()
+            finish(4)
+        }
+        expect(3)
+    }
+
     @Test
     fun testLaunchWithDelayCompletes() = runBlockingTest {
         expect(1)

kotlinx-coroutines-test/test/TestRunBlockingTest.kt

@@ -5,8 +5,6 @@
 package kotlinx.coroutines.test
 
 import kotlinx.coroutines.*
-import org.junit.Assert.*
-import org.junit.Test
 import kotlin.coroutines.*
 import kotlin.test.*
 
@@ -371,4 +369,29 @@ class TestRunBlockingTest {
         runCurrent()
         assertEquals(true, result.isSuccess)
     }
-}
+
+
+    private val exceptionHandler = TestCoroutineExceptionHandler()
+
+    @Test
+    fun testPartialContextOverride() = runBlockingTest(CoroutineName("named")) {
+        assertEquals(CoroutineName("named"), coroutineContext[CoroutineName])
+        assertNotNull(coroutineContext[CoroutineExceptionHandler])
+        assertNotSame(coroutineContext[CoroutineExceptionHandler], exceptionHandler)
+    }
+
+    @Test(expected = IllegalArgumentException::class)
+    fun testPartialDispatcherOverride() = runBlockingTest(Dispatchers.Unconfined) {
+        fail("Unreached")
+    }
+
+    @Test
+    fun testOverrideExceptionHandler() = runBlockingTest(exceptionHandler) {
+        assertSame(coroutineContext[CoroutineExceptionHandler], exceptionHandler)
+    }
+
+    @Test(expected = IllegalArgumentException::class)
+    fun testOverrideExceptionHandlerError() = runBlockingTest(CoroutineExceptionHandler { _, _ -> }) {
+        fail("Unreached")
+    }
+}