Skip to content

Improve docs for the test module #3074

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 10, 2021
Merged

Improve docs for the test module #3074

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c33c194
Fix a typo
dkhalanskyjb Dec 8, 2021
e80d604
Mention the migration guide
dkhalanskyjb Dec 10, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion kotlinx-coroutines-test/common/src/TestScope.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ public fun TestScope.runCurrent(): Unit = testScheduler.runCurrent()
* Moves the virtual clock of this dispatcher forward by [the specified amount][delayTimeMillis], running the
* scheduled tasks in the meantime.
*
* In contrast with [TestScope.advanceTimeBy], this function does not run the tasks scheduled at the moment
* In contrast with `TestCoroutineScope.advanceTimeBy`, this function does not run the tasks scheduled at the moment
* [currentTime] + [delayTimeMillis].
*
* @throws IllegalStateException if passed a negative [delay][delayTimeMillis].
Expand Down
6 changes: 6 additions & 0 deletions kotlinx-coroutines-test/jvm/src/migration/DelayController.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ import kotlinx.coroutines.*
* Control the virtual clock time of a [CoroutineDispatcher].
*
* Testing libraries may expose this interface to the tests instead of [TestCoroutineDispatcher].
*
* This interface is deprecated without replacement.
* Instead, [TestCoroutineScheduler] is supposed to be used to control the virtual time.
* Please see the
* [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
* for an instruction on how to update the code for the new API.
*/
@ExperimentalCoroutinesApi
@Deprecated(
Expand Down
29 changes: 26 additions & 3 deletions kotlinx-coroutines-test/jvm/src/migration/TestBuildersDeprecated.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ import kotlin.jvm.*
/**
* Executes a [testBody] inside an immediate execution dispatcher.
*
* This method is deprecated in favor of [runTest]. Please see the
* [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
* for an instruction on how to update the code for the new API.
*
* 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.
Expand Down Expand Up @@ -46,7 +50,10 @@ import kotlin.jvm.*
* then they must implement [DelayController] and [TestCoroutineExceptionHandler] respectively.
* @param testBody The code of the unit-test.
*/
@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
@Deprecated("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)
// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
public fun runBlockingTest(
context: CoroutineContext = EmptyCoroutineContext,
Expand Down Expand Up @@ -102,8 +109,16 @@ public fun runBlockingTestOnTestScope(

/**
* Convenience method for calling [runBlockingTest] on an existing [TestCoroutineScope].
*
* This method is deprecated in favor of [runTest], whereas [TestCoroutineScope] is deprecated in favor of [TestScope].
* Please see the
* [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
* for an instruction on how to update the code for the new API.
*/
@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
@Deprecated("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)
// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
public fun TestCoroutineScope.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit): Unit =
runBlockingTest(coroutineContext, block)
Expand All @@ -118,8 +133,16 @@ public fun TestScope.runBlockingTest(block: suspend TestScope.() -> Unit): Unit

/**
* Convenience method for calling [runBlockingTest] on an existing [TestCoroutineDispatcher].
*
* This method is deprecated in favor of [runTest], whereas [TestCoroutineScope] is deprecated in favor of [TestScope].
* Please see the
* [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
* for an instruction on how to update the code for the new API.
*/
@Deprecated("Use `runTest` instead to support completing from other dispatchers.", level = DeprecationLevel.WARNING)
@Deprecated("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)
// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
public fun TestCoroutineDispatcher.runBlockingTest(block: suspend TestCoroutineScope.() -> Unit): Unit =
runBlockingTest(this, block)
Expand Down
15 changes: 14 additions & 1 deletion kotlinx-coroutines-test/jvm/src/migration/TestCoroutineScope.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,17 @@ import kotlin.coroutines.*

/**
* A scope which provides detailed control over the execution of coroutines for tests.
*
* This scope is deprecated in favor of [TestScope].
* Please see the
* [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
* for an instruction on how to update the code for the new API.
*/
@ExperimentalCoroutinesApi
@Deprecated("Use `TestScope` in combination with `runTest` instead")
@Deprecated("Use `TestScope` in combination with `runTest` instead." +
"Please see the migration guide for details: " +
"https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md",
level = DeprecationLevel.WARNING)
// Since 1.6.0, ERROR in 1.7.0 and removed as experimental in 1.8.0
public sealed interface TestCoroutineScope : CoroutineScope {
/**
Expand Down Expand Up @@ -139,6 +147,11 @@ public fun TestCoroutineScope(context: CoroutineContext = EmptyCoroutineContext)
/**
* A coroutine scope for launching test coroutines.
*
* This is a function for aiding in migration from [TestCoroutineScope] to [TestScope].
* Please see the
* [migration guide](https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/MIGRATION.md)
* for an instruction on how to update the code for the new API.
*
* It ensures that all the test module machinery is properly initialized.
* * If [context] doesn't define a [TestCoroutineScheduler] for orchestrating the virtual time used for delay-skipping,
* a new one is created, unless either
Expand Down