Increase the deprecation levels for the old test framework API

Author: dkhalanskyjb

README.md

@@ -43,7 +43,7 @@ suspend fun main() = coroutineScope {
   * Integration with `Window` via [Window.asCoroutineDispatcher], etc.
 * [test](kotlinx-coroutines-test/README.md) — test utilities for coroutines:
   * [Dispatchers.setMain] to override [Dispatchers.Main] in tests;
-  * [TestCoroutineScope] to test suspending functions and coroutines.
+  * [runTest] and [TestScope] to test suspending functions and coroutines.
 * [debug](kotlinx-coroutines-debug/README.md) — debug utilities for coroutines:
   * [DebugProbes] API to probe, keep track of, print and dump active coroutines;
   * [CoroutinesTimeout] test rule to automatically dump coroutines on test timeout.
@@ -240,7 +240,8 @@ See [Contributing Guidelines](CONTRIBUTING.md).
 <!--- INDEX kotlinx.coroutines.test -->
 
 [Dispatchers.setMain]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/set-main.html
-[TestCoroutineScope]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-coroutine-scope/index.html
+[runTest]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/run-test.html
+[TestScope]: https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-test/kotlinx.coroutines.test/-test-scope/index.html
 
 <!--- MODULE kotlinx-coroutines-debug -->
 <!--- INDEX kotlinx.coroutines.debug -->

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

@@ -1,4 +1,4 @@
-@file:Suppress("DEPRECATION")
+@file:Suppress("DEPRECATION", "DEPRECATION_ERROR")
 @file:JvmName("TestBuildersKt")
 @file:JvmMultifileClass
 
@@ -51,9 +51,9 @@ import kotlin.time.Duration.Companion.milliseconds
     "Use `runTest` instead to support completing from other dispatchers. " +
         "Please see the migration guide for details: " +
         "https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
-    level = DeprecationLevel.WARNING
+    level = DeprecationLevel.ERROR
 )
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public fun runBlockingTest(
     context: CoroutineContext = EmptyCoroutineContext,
     testBody: suspend TestCoroutineScope.() -> Unit
@@ -73,8 +73,8 @@ public fun runBlockingTest(
 /**
  * A version of [runBlockingTest] that works with [TestScope].
  */
-@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.ERROR)
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public fun runBlockingTestOnTestScope(
     context: CoroutineContext = EmptyCoroutineContext,
     testBody: suspend TestScope.() -> Unit
@@ -121,17 +121,17 @@ public fun runBlockingTestOnTestScope(
     "Use `runTest` instead to support completing from other dispatchers. " +
         "Please see the migration guide for details: " +
         "https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
-    level = DeprecationLevel.WARNING
+    level = DeprecationLevel.ERROR
 )
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit): Unit =
     runBlockingTest(coroutineContext, block)
 
 /**
  * Convenience method for calling [runBlockingTestOnTestScope] on an existing [TestScope].
  */
-@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.ERROR)
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public fun TestScope.runBlockingTest(block: suspend TestScope.() -> Unit): Unit =
     runBlockingTestOnTestScope(coroutineContext, block)
 
@@ -147,18 +147,18 @@ public fun TestScope.runBlockingTest(block: suspend TestScope.() -> Unit): Unit
     "Use `runTest` instead to support completing from other dispatchers. " +
         "Please see the migration guide for details: " +
         "https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
-    level = DeprecationLevel.WARNING
+    level = DeprecationLevel.ERROR
 )
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit): Unit =
     runBlockingTest(this, block)
 
 /**
  * This is an overload of [runTest] that works with [TestCoroutineScope].
  */
 @ExperimentalCoroutinesApi
-@Deprecated("Use `runTest` instead.", level = DeprecationLevel.WARNING)
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+@Deprecated("Use `runTest` instead.", level = DeprecationLevel.ERROR)
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public fun runTestWithLegacyScope(
     context: CoroutineContext = EmptyCoroutineContext,
     dispatchTimeoutMs: Long = DEFAULT_DISPATCH_TIMEOUT_MS,
@@ -196,8 +196,8 @@ public fun runTestWithLegacyScope(
  * immediately from the test body. See the docs for [TestResult] for details.
  */
 @ExperimentalCoroutinesApi
-@Deprecated("Use `TestScope.runTest` instead.", level = DeprecationLevel.WARNING)
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+@Deprecated("Use `TestScope.runTest` instead.", level = DeprecationLevel.ERROR)
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public fun TestCoroutineScope.runTest(
     dispatchTimeoutMs: Long = DEFAULT_DISPATCH_TIMEOUT_MS,
     block: suspend TestCoroutineScope.() -> Unit

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

@@ -4,25 +4,14 @@ import kotlinx.coroutines.*
 import kotlin.coroutines.*
 
 /**
- * [CoroutineDispatcher] that performs both immediate and lazy execution of coroutines in tests
- * and uses a [TestCoroutineScheduler] to control its virtual clock.
- *
- * By default, [TestCoroutineDispatcher] is immediate. That means any tasks scheduled to be run without delay are
- * immediately executed. If they were scheduled with a delay, the virtual clock-time must be advanced via one of the
- * methods on the dispatcher's [scheduler].
- *
- * When switched to lazy execution using [pauseDispatcher] 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].
- *
- * @see DelayController
+ * @suppress
  */
 @Deprecated("The execution order of `TestCoroutineDispatcher` can be confusing, and the mechanism of " +
     "pausing is typically misunderstood. Please use `StandardTestDispatcher` or `UnconfinedTestDispatcher` instead.",
-    level = DeprecationLevel.WARNING)
-// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.8.0 and removed as experimental in 1.9.0
+    level = DeprecationLevel.ERROR)
+// Since 1.6.0, kept as warning in 1.7.0, ERROR in 1.9.0 and removed as experimental later
 public class TestCoroutineDispatcher(public override val scheduler: TestCoroutineScheduler = TestCoroutineScheduler()):
-    TestDispatcher(), Delay, SchedulerAsDelayController
+    TestDispatcher(), Delay
 {
     private var dispatchImmediately = true
         set(value) {
@@ -56,36 +45,25 @@ public class TestCoroutineDispatcher(public override val scheduler: TestCoroutin
     private fun post(block: Runnable, context: CoroutineContext) =
         scheduler.registerEvent(this, 0, block, context) { false }
 
-    /** @suppress */
-    @Deprecated(
-        "Please use a dispatcher that is paused by default, like `StandardTestDispatcher`.",
-        level = DeprecationLevel.ERROR
-    )
-    override suspend fun pauseDispatcher(block: suspend () -> Unit) {
-        val previous = dispatchImmediately
-        dispatchImmediately = false
-        try {
-            block()
-        } finally {
-            dispatchImmediately = previous
-        }
-    }
+    val currentTime: Long
+        get() = scheduler.currentTime
 
-    /** @suppress */
-    @Deprecated(
-        "Please use a dispatcher that is paused by default, like `StandardTestDispatcher`.",
-        level = DeprecationLevel.ERROR
-    )
-    override fun pauseDispatcher() {
-        dispatchImmediately = false
+    fun advanceUntilIdle(): Long {
+        val oldTime = scheduler.currentTime
+        scheduler.advanceUntilIdle()
+        return scheduler.currentTime - oldTime
     }
 
-    /** @suppress */
-    @Deprecated(
-        "Please use a dispatcher that is paused by default, like `StandardTestDispatcher`.",
-        level = DeprecationLevel.ERROR
-    )
-    override fun resumeDispatcher() {
-        dispatchImmediately = true
+    fun runCurrent(): Unit = scheduler.runCurrent()
+
+    fun cleanupTestCoroutines() {
+        // process any pending cancellations or completions, but don't advance time
+        scheduler.runCurrent()
+        if (!scheduler.isIdle(strict = false)) {
+            throw UncompletedCoroutinesError(
+                "Unfinished coroutines during tear-down. Ensure all coroutines are" +
+                    " completed or cancelled by your test."
+            )
+        }
     }
 }