Add deprecations to TestCoroutineContext.

Add deprecations to new API for changes.

Author: objcode

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

@@ -30,7 +30,9 @@ import kotlin.coroutines.*
  *
  * @param name A user-readable name for debugging purposes.
  */
-@ObsoleteCoroutinesApi
+@Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
+        ReplaceWith("TestCoroutineScope", "kotlin.coroutines.test"),
+        level = DeprecationLevel.WARNING)
 class TestCoroutineContext(private val name: String? = null) : CoroutineContext {
     private val uncaughtExceptions = mutableListOf<Throwable>()
 
@@ -281,12 +283,14 @@ private class TimedRunnable(
  * provided instead.
  * @param testBody The code of the unit-test.
  */
-@ObsoleteCoroutinesApi
+@Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
+        ReplaceWith("testContext.runBlockingTest(testBody)", "kotlin.coroutines.test"),
+        level = DeprecationLevel.WARNING)
 public fun withTestContext(testContext: TestCoroutineContext = TestCoroutineContext(), testBody: TestCoroutineContext.() -> Unit) {
     with (testContext) {
         testBody()
         if (!exceptions.all { it is CancellationException }) {
             throw AssertionError("Coroutine encountered unhandled exceptions:\n$exceptions")
         }
     }
-}
+}

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

@@ -82,6 +82,17 @@ fun asyncTest(context: CoroutineContext? = null, testBody: TestCoroutineScope.()
 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.
@@ -150,15 +161,15 @@ fun runBlockingTest(context: CoroutineContext? = null, testBody: suspend TestCor
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
  */
-fun TestCoroutineScope.runBlockingTest(block: suspend CoroutineScope.() -> Unit) {
+fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
     runBlockingTest(coroutineContext, block)
 }
 
 /**
  * Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
  *
  */
-fun TestCoroutineDispatcher.runBlockingTest(block: suspend CoroutineScope.() -> Unit) {
+fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit) {
     runBlockingTest(this, block)
 }
 

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

@@ -96,6 +96,24 @@ interface DelayController {
      * Setting it to false will resume lazy execution.
      */
     var dispatchImmediately: Boolean
+
+    @Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
+            ReplaceWith("if (targetTime > currentTime(unit)) { advanceTimeBy(targetTime - currentTime(unit), unit) }",
+                    "kotlinx.coroutines.test"),
+            level = DeprecationLevel.WARNING)
+    fun advanceTimeTo(targetTime: Long, unit: TimeUnit = TimeUnit.MILLISECONDS) {
+        advanceTimeBy(targetTime - currentTime(unit), unit)
+    }
+
+    @Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
+            ReplaceWith("currentTime(unit)", "kotlinx.coroutines.test"),
+            level = DeprecationLevel.WARNING)
+    fun now(unit: TimeUnit = TimeUnit.MILLISECONDS) = currentTime(unit)
+
+    @Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
+            ReplaceWith("runCurrent()", "kotlinx.coroutines.test"),
+            level = DeprecationLevel.WARNING)
+    fun triggerActions() = runCurrent()
 }
 
 /**
@@ -197,7 +215,7 @@ class TestCoroutineDispatcher:
 
     override fun advanceTimeBy(delayTime: Long, unit: TimeUnit): Long {
         val oldTime = time
-        advanceTimeTo(oldTime + unit.toNanos(delayTime), TimeUnit.NANOSECONDS)
+        advanceUntilTime(oldTime + unit.toNanos(delayTime), TimeUnit.NANOSECONDS)
         return unit.convert(time - oldTime, TimeUnit.NANOSECONDS)
     }
 
@@ -207,7 +225,7 @@ class TestCoroutineDispatcher:
      * @param targetTime The point in time to which to move the CoroutineContext's clock.
      * @param unit The [TimeUnit] in which [targetTime] is expressed.
      */
-    private fun advanceTimeTo(targetTime: Long, unit: TimeUnit) {
+    private fun advanceUntilTime(targetTime: Long, unit: TimeUnit) {
         val nanoTime = unit.toNanos(targetTime)
         triggerActions(nanoTime)
         if (nanoTime > time) time = nanoTime
@@ -217,7 +235,7 @@ class TestCoroutineDispatcher:
         val oldTime = time
         runCurrent()
         val next = queue.peek() ?: return 0
-        advanceTimeTo(next.time, TimeUnit.NANOSECONDS)
+        advanceUntilTime(next.time, TimeUnit.NANOSECONDS)
         return time - oldTime
     }
 

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

@@ -25,6 +25,16 @@ class TestCoroutineScope(
     }
 
     override val coroutineContext = context
+
+    /**
+     * This method is deprecated.
+     *
+     * @see [cleanupTestCoroutines]
+     */
+    @Deprecated("This API has been deprecated to integrate with Structured Concurrency.",
+            ReplaceWith("cleanupTestCoroutines()"),
+            level = DeprecationLevel.WARNING)
+    fun cancelAllActions() = cleanupTestCoroutines()
 }
 
 fun TestCoroutineScope(dispatcher: TestCoroutineDispatcher) =