1 package kotlinx.coroutines.test 2 3 import kotlinx.coroutines.CoroutineDispatcher 4 import kotlinx.coroutines.ExperimentalCoroutinesApi 5 6 /** 7 * Control the virtual clock time of a [CoroutineDispatcher]. 8 * 9 * Testing libraries may expose this interface to tests instead of [TestCoroutineDispatcher]. 10 */ 11 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 12 public interface DelayController { 13 /** 14 * Returns the current virtual clock-time as it is known to this Dispatcher. 15 * 16 * @return The virtual clock-time 17 */ 18 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 19 public val currentTime: Long 20 21 /** 22 * Moves the Dispatcher's virtual clock forward by a specified amount of time. 23 * 24 * The amount the clock is progressed may be larger than the requested `delayTimeMillis` if the code under test uses 25 * blocking coroutines. 26 * 27 * The virtual clock time will advance once for each delay resumed until the next delay exceeds the requested 28 * `delayTimeMills`. In the following test, the virtual time will progress by 2_000 then 1 to resume three different 29 * calls to delay. 30 * 31 * ``` 32 * @Test 33 * fun advanceTimeTest() = runBlockingTest { 34 * foo() 35 * advanceTimeBy(2_000) // advanceTimeBy(2_000) will progress through the first two delays 36 * // virtual time is 2_000, next resume is at 2_001 37 * advanceTimeBy(2) // progress through the last delay of 501 (note 500ms were already advanced) 38 * // virtual time is 2_0002 39 * } 40 * 41 * fun CoroutineScope.foo() { 42 * launch { 43 * delay(1_000) // advanceTimeBy(2_000) will progress through this delay (resume @ virtual time 1_000) 44 * // virtual time is 1_000 45 * delay(500) // advanceTimeBy(2_000) will progress through this delay (resume @ virtual time 1_500) 46 * // virtual time is 1_500 47 * delay(501) // advanceTimeBy(2_000) will not progress through this delay (resume @ virtual time 2_001) 48 * // virtual time is 2_001 49 * } 50 * } 51 * ``` 52 * 53 * @param delayTimeMillis The amount of time to move the CoroutineContext's clock forward. 54 * @return The amount of delay-time that this Dispatcher's clock has been forwarded. 55 */ 56 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 advanceTimeBynull57 public fun advanceTimeBy(delayTimeMillis: Long): Long 58 59 /** 60 * Immediately execute all pending tasks and advance the virtual clock-time to the last delay. 61 * 62 * If new tasks are scheduled due to advancing virtual time, they will be executed before `advanceUntilIdle` 63 * returns. 64 * 65 * @return the amount of delay-time that this Dispatcher's clock has been forwarded in milliseconds. 66 */ 67 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 68 public fun advanceUntilIdle(): Long 69 70 /** 71 * Run any tasks that are pending at or before the current virtual clock-time. 72 * 73 * Calling this function will never advance the clock. 74 */ 75 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 76 public fun runCurrent() 77 78 /** 79 * Call after test code completes to ensure that the dispatcher is properly cleaned up. 80 * 81 * @throws UncompletedCoroutinesError if any pending tasks are active, however it will not throw for suspended 82 * coroutines. 83 */ 84 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 85 @Throws(UncompletedCoroutinesError::class) 86 public fun cleanupTestCoroutines() 87 88 /** 89 * Run a block of code in a paused dispatcher. 90 * 91 * By pausing the dispatcher any new coroutines will not execute immediately. After block executes, the dispatcher 92 * will resume auto-advancing. 93 * 94 * This is useful when testing functions that start a coroutine. By pausing the dispatcher assertions or 95 * setup may be done between the time the coroutine is created and started. 96 */ 97 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 98 public suspend fun pauseDispatcher(block: suspend () -> Unit) 99 100 /** 101 * Pause the dispatcher. 102 * 103 * When paused, the dispatcher will not execute any coroutines automatically, and you must call [runCurrent] or 104 * [advanceTimeBy], or [advanceUntilIdle] to execute coroutines. 105 */ 106 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 107 public fun pauseDispatcher() 108 109 /** 110 * Resume the dispatcher from a paused state. 111 * 112 * Resumed dispatchers will automatically progress through all coroutines scheduled at the current time. To advance 113 * time and execute coroutines scheduled in the future use, one of [advanceTimeBy], 114 * or [advanceUntilIdle]. 115 */ 116 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 117 public fun resumeDispatcher() 118 } 119 120 /** 121 * Thrown when a test has completed and there are tasks that are not completed or cancelled. 122 */ 123 // todo: maybe convert into non-public class in 1.3.0 (need use-cases for a public exception type) 124 @ExperimentalCoroutinesApi // Since 1.2.1, tentatively till 1.3.0 125 public class UncompletedCoroutinesError(message: String, cause: Throwable? = null): AssertionError(message, cause) 126