在 Android 上测试 Kotlin 协程

使用 协程 的代码的单元测试需要一些额外的关注，因为它们的执行可能是异步的，并且可能跨多个线程发生。本指南介绍了如何测试挂起函数、需要熟悉的测试结构以及如何使使用协程的代码可测试。

本指南中使用的 API 是 kotlinx.coroutines.test 库的一部分。请确保 将工件 添加为测试依赖项以访问这些 API。

dependencies {
    testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:$coroutines_version"
}

在测试中调用挂起函数

要在测试中调用挂起函数，您需要在协程中。由于 JUnit 测试函数本身不是挂起函数，因此您需要在测试中调用协程构建器来启动一个新协程。

runTest 是专为测试设计的协程构建器。使用它来包装包含协程的任何测试。请注意，协程不仅可以直接在测试主体中启动，还可以通过测试中使用的对象启动。

suspend fun fetchData(): String {
    delay(1000L)
    return "Hello world"
}

@Test
fun dataShouldBeHelloWorld() = runTest {
    val data = fetchData()
    assertEquals("Hello world", data)
}
SuspendingFunctionTests.kt

一般来说，您应该为每个测试调用一次 runTest，并且建议使用 表达式主体。

将测试代码包装在 runTest 中将适用于测试基本的挂起函数，并且它会自动跳过协程中的任何延迟，使上面的测试比一秒钟完成得快得多。

但是，根据被测代码中发生的事情，还需要进行其他考虑

• 当您的代码创建新的协程（而不是 runTest 创建的顶级测试协程）时，您需要 选择适当的 TestDispatcher 来控制这些新协程的调度方式。
• 如果您的代码将协程执行移动到其他调度器（例如，通过使用 withContext），runTest 通常仍然有效，但延迟将不再被跳过，并且测试将变得不太可预测，因为代码在多个线程上运行。出于这些原因，在测试中，您应该 注入测试调度器 来替换实际调度器。

TestDispatchers

TestDispatchers 是用于测试目的的 CoroutineDispatcher 实现。如果您在测试期间创建了新的协程，则需要使用 TestDispatchers 使新协程的执行可预测。

TestDispatcher 有两种可用的实现：StandardTestDispatcher 和 UnconfinedTestDispatcher，它们对新启动的协程执行不同的调度。它们都使用 TestCoroutineScheduler 来控制虚拟时间并在测试中管理正在运行的协程。

在一个测试中只应使用一个调度程序实例，在所有 TestDispatchers 之间共享。有关共享调度程序的信息，请参阅 注入 TestDispatchers。

要启动顶级测试协程，runTest 会创建一个 TestScope，它是 CoroutineScope 的实现，它将始终使用 TestDispatcher。如果没有指定，TestScope 默认情况下会创建一个 StandardTestDispatcher，并使用它来运行顶级测试协程。

runTest 会跟踪在调度程序上排队的协程（调度程序由其 TestScope 的调度器使用），并且只要调度程序上有待处理的工作，它就不会返回。

StandardTestDispatcher

当您在 StandardTestDispatcher 上启动新的协程时，它们会排队到底层调度器上，并在测试线程空闲时运行。 为了让这些新的协程运行，您需要让出测试线程（将其释放以便其他协程使用）。 这种排队行为使您能够精确控制新的协程在测试期间的运行方式，并且它类似于生产代码中协程的调度。

如果在执行顶级测试协程期间从未让出测试线程，任何新的协程都将在测试协程完成之后（但在 runTest 返回之前）运行。

@Test
fun standardTest() = runTest {
    val userRepo = UserRepository()

    launch { userRepo.register("Alice") }
    launch { userRepo.register("Bob") }

    assertEquals(listOf("Alice", "Bob"), userRepo.getAllUsers()) // ❌ Fails
}
StandardTestDispatcherTest.kt

有多种方法可以让出测试协程以使排队的协程运行。 所有这些调用都允许其他协程在返回之前在测试线程上运行。

• advanceUntilIdle：运行调度器上的所有其他协程，直到队列中没有任何内容。 这是让所有挂起的协程运行的良好默认选择，它将在大多数测试场景中起作用。
• advanceTimeBy：将虚拟时间提前给定量，并运行在虚拟时间中该时间点之前安排运行的任何协程。
• runCurrent：运行安排在当前虚拟时间的协程。

为了修复之前的测试，可以使用 advanceUntilIdle 来让两个挂起的协程在继续进行断言之前执行其工作。

@Test
fun standardTest() = runTest {
    val userRepo = UserRepository()

    launch { userRepo.register("Alice") }
    launch { userRepo.register("Bob") }
    advanceUntilIdle() // Yields to perform the registrations

    assertEquals(listOf("Alice", "Bob"), userRepo.getAllUsers()) // ✅ Passes
}
StandardTestDispatcherTest.kt

UnconfinedTestDispatcher

当在 UnconfinedTestDispatcher 上启动新的协程时，它们会立即在当前线程上启动。 这意味着它们将立即开始运行，而无需等待其协程构建器返回。 在许多情况下，这种调度行为会导致更简单的测试代码，因为您不需要手动让出测试线程以让新的协程运行。

但是，这种行为与您在生产中使用非测试调度器时看到的行为不同。 如果您的测试侧重于并发，请优先使用 StandardTestDispatcher。

要将此调度器用于 runTest 中的顶级测试协程而不是默认调度器，请创建一个实例并将其作为参数传递。 这将使在 runTest 中创建的新协程急切地执行，因为它们从 TestScope 中继承了调度器。

@Test
fun unconfinedTest() = runTest(UnconfinedTestDispatcher()) {
    val userRepo = UserRepository()

    launch { userRepo.register("Alice") }
    launch { userRepo.register("Bob") }

    assertEquals(listOf("Alice", "Bob"), userRepo.getAllUsers()) // ✅ Passes
}
UnconfinedTestDispatcherTest.kt

在此示例中，launch 调用将在 UnconfinedTestDispatcher 上急切地启动其新的协程，这意味着每次调用 launch 仅在注册完成后才会返回。

请记住，UnconfinedTestDispatcher 会急切地启动新的协程，但这并不意味着它也会急切地将它们运行到完成。 如果新的协程挂起，其他协程将恢复执行。

例如，在此测试中启动的新协程将注册 Alice，但在调用 delay 时挂起。 这允许顶级协程继续进行断言，并且测试失败，因为 Bob 尚未注册。

@Test
fun yieldingTest() = runTest(UnconfinedTestDispatcher()) {
    val userRepo = UserRepository()

    launch {
        userRepo.register("Alice")
        delay(10L)
        userRepo.register("Bob")
    }

    assertEquals(listOf("Alice", "Bob"), userRepo.getAllUsers()) // ❌ Fails
}
UnconfinedTestDispatcherTest.kt

注入测试调度器

测试代码可能会使用调度器来切换线程（使用 withContext）或启动新的协程。 当代码在多个线程上并行执行时，测试可能会变得不稳定。 如果它们在您无法控制的后台线程上运行，则很难在正确的时间执行断言或等待任务完成。

在测试中，用 TestDispatchers 的实例替换这些调度器。 这有几个好处。

• 代码将在单个测试线程上运行，使测试更确定性。
• 您可以控制新的协程的调度和执行方式。
• TestDispatchers 使用调度器来处理虚拟时间，它会自动跳过延迟，并允许您手动推进时间。

使用依赖注入 将调度器提供给您的类，可以轻松地在测试中替换真实的调度器。 在这些示例中，我们将注入一个 CoroutineDispatcher，但您也可以注入更广泛的 CoroutineContext 类型，这在测试期间提供了更大的灵活性。

对于启动协程的类，您也可以注入一个 CoroutineScope 而不是调度器，如注入范围部分所述。

TestDispatchers 默认会在实例化时创建一个新的调度器。 在 runTest 内部，您可以访问 TestScope 的 testScheduler 属性，并将它传递给任何新创建的 TestDispatchers。 这将共享它们对虚拟时间的理解，并且像 advanceUntilIdle 这样的方法将运行所有测试调度器上的协程直到完成。

在以下示例中，您可以看到一个 Repository 类，它在 initialize 方法中使用 IO 调度器创建新的协程，并在 fetchData 方法中将调用者切换到 IO 调度器。

// Example class demonstrating dispatcher use cases
class Repository(private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO) {
    private val scope = CoroutineScope(ioDispatcher)
    val initialized = AtomicBoolean(false)

    // A function that starts a new coroutine on the IO dispatcher
    fun initialize() {
        scope.launch {
            initialized.set(true)
        }
    }

    // A suspending function that switches to the IO dispatcher
    suspend fun fetchData(): String = withContext(ioDispatcher) {
        require(initialized.get()) { "Repository should be initialized first" }
        delay(500L)
        "Hello world"
    }
}
Repository.kt

在测试中，您可以注入一个 TestDispatcher 实现来替换 IO 调度器。

在下面的示例中，我们将 StandardTestDispatcher 注入到存储库中，并使用 advanceUntilIdle 来确保在继续之前在 initialize 中启动的新的协程完成。

fetchData 也将受益于在 TestDispatcher 上运行，因为它将在测试线程上运行并在测试期间跳过它包含的延迟。

class RepositoryTest {
    @Test
    fun repoInitWorksAndDataIsHelloWorld() = runTest {
        val dispatcher = StandardTestDispatcher(testScheduler)
        val repository = Repository(dispatcher)

        repository.initialize()
        advanceUntilIdle() // Runs the new coroutine
        assertEquals(true, repository.initialized.get())

        val data = repository.fetchData() // No thread switch, delay is skipped
        assertEquals("Hello world", data)
    }
}
RepositoryTest.kt

在 TestDispatcher 上启动的新的协程可以像上面使用 initialize 所示那样手动推进。 但是请注意，这在生产代码中是不可能的或不可取的。 相反，应该重新设计此方法，使其要么是挂起的（用于顺序执行），要么返回 Deferred 值（用于并发执行）。

例如，您可以使用 async 启动新的协程并创建一个 Deferred

class BetterRepository(private val ioDispatcher: CoroutineDispatcher = Dispatchers.IO) {
    private val scope = CoroutineScope(ioDispatcher)

    fun initialize() = scope.async {
        // ...
    }
}
Repository.kt

这使您可以在测试和生产代码中安全地 await 此代码的完成。

@Test
fun repoInitWorks() = runTest {
    val dispatcher = StandardTestDispatcher(testScheduler)
    val repository = BetterRepository(dispatcher)

    repository.initialize().await() // Suspends until the new coroutine is done
    assertEquals(true, repository.initialized.get())
    // ...
}
RepositoryTest.kt

runTest 将在返回之前等待挂起的协程完成，如果这些协程在它与之共享调度器的 TestDispatcher 上。 它还将等待顶级测试协程的子协程完成，即使它们在其他调度器上（直到 dispatchTimeoutMs 参数指定的超时，默认情况下为 60 秒）。

设置 Main 调度器

在本地单元测试中，包装 Android UI 线程的 Main 调度器将不可用，因为这些测试是在本地 JVM 上执行的，而不是在 Android 设备上。 如果您测试的代码引用了主线程，它将在单元测试期间抛出异常。

在某些情况下，您可以像注入其他调度器一样注入 Main 调度器，如 上一节 中所述，允许您在测试中用 TestDispatcher 替换它。但是，一些 API（例如 viewModelScope）在内部使用硬编码的 Main 调度器。

以下是一个 ViewModel 实现的示例，它使用 viewModelScope 启动一个加载数据的协程

class HomeViewModel : ViewModel() {
    private val _message = MutableStateFlow("")
    val message: StateFlow<String> get() = _message

    fun loadMessage() {
        viewModelScope.launch {
            _message.value = "Greetings!"
        }
    }
}
HomeViewModel.kt

要将 Main 调度器替换为所有情况下的 TestDispatcher，请使用 Dispatchers.setMain 和 Dispatchers.resetMain 函数。

class HomeViewModelTest {
    @Test
    fun settingMainDispatcher() = runTest {
        val testDispatcher = UnconfinedTestDispatcher(testScheduler)
        Dispatchers.setMain(testDispatcher)

        try {
            val viewModel = HomeViewModel()
            viewModel.loadMessage() // Uses testDispatcher, runs its coroutine eagerly
            assertEquals("Greetings!", viewModel.message.value)
        } finally {
            Dispatchers.resetMain()
        }
    }
}
HomeViewModelTest.kt

如果 Main 调度器已被替换为 TestDispatcher，任何新创建的 TestDispatchers 将自动使用 Main 调度器的调度程序，包括由 runTest 创建的 StandardTestDispatcher（如果未向其传递其他调度器）。

这使得更容易确保在测试期间只使用一个调度程序。为了使此方法起作用，请确保在调用 Dispatchers.setMain 之后创建所有其他 TestDispatcher 实例。

避免在每个测试中重复替换 Main 调度器的代码的一个常见模式是将其提取到 JUnit 测试规则 中

// Reusable JUnit4 TestRule to override the Main dispatcher
class MainDispatcherRule(
    val testDispatcher: TestDispatcher = UnconfinedTestDispatcher(),
) : TestWatcher() {
    override fun starting(description: Description) {
        Dispatchers.setMain(testDispatcher)
    }

    override fun finished(description: Description) {
        Dispatchers.resetMain()
    }
}

class HomeViewModelTestUsingRule {
    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    @Test
    fun settingMainDispatcher() = runTest { // Uses Main’s scheduler
        val viewModel = HomeViewModel()
        viewModel.loadMessage()
        assertEquals("Greetings!", viewModel.message.value)
    }
}
HomeViewModelTestUsingRule.kt

此规则实现默认使用 UnconfinedTestDispatcher，但如果 Main 调度器不应该在给定的测试类中急切执行，则可以将 StandardTestDispatcher 作为参数传递。

当您需要在测试体中使用 TestDispatcher 实例时，您可以重复使用规则中的 testDispatcher，只要它是所需的类型。如果您想明确使用 TestDispatcher 的类型，或者如果您需要一个与用于 Main 的类型不同的 TestDispatcher，则可以在 runTest 中创建一个新的 TestDispatcher。由于 Main 调度器设置为 TestDispatcher，任何新创建的 TestDispatchers 将自动共享其调度程序。

class DispatcherTypesTest {
    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    @Test
    fun injectingTestDispatchers() = runTest { // Uses Main’s scheduler
        // Use the UnconfinedTestDispatcher from the Main dispatcher
        val unconfinedRepo = Repository(mainDispatcherRule.testDispatcher)

        // Create a new StandardTestDispatcher (uses Main’s scheduler)
        val standardRepo = Repository(StandardTestDispatcher())
    }
}
DispatcherTypesTest.kt

在测试之外创建调度器

在某些情况下，您可能需要在测试方法之外使用 TestDispatcher。例如，在测试类中的属性初始化期间

class Repository(private val ioDispatcher: CoroutineDispatcher) { /* ... */ }

class RepositoryTestWithRule {
    private val repository = Repository(/* What TestDispatcher? */)

    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    @Test
    fun someRepositoryTest() = runTest {
        // Test the repository...
        // ...
    }
}
DispatchersOutsideTests.kt

如果您像上一节中所示的那样替换 Main 调度器，则在替换 Main 调度器之后创建的 TestDispatchers 将自动共享其调度程序。

但是，对于作为测试类属性创建的 TestDispatchers 或在测试类中的属性初始化期间创建的 TestDispatchers 来说，情况并非如此。这些在替换 Main 调度器之前初始化。因此，它们将创建新的调度程序。

为了确保在您的测试中只有一个调度程序，请首先创建 MainDispatcherRule 属性。然后在其他类级属性的初始化程序中根据需要重复使用其调度程序（或其调度程序，如果您需要不同类型的 TestDispatcher）。

class RepositoryTestWithRule {
    @get:Rule
    val mainDispatcherRule = MainDispatcherRule()

    private val repository = Repository(mainDispatcherRule.testDispatcher)

    @Test
    fun someRepositoryTest() = runTest { // Takes scheduler from Main
        // Any TestDispatcher created here also takes the scheduler from Main
        val newTestDispatcher = StandardTestDispatcher()

        // Test the repository...
    }
}
DispatchersOutsideTests.kt

请注意，runTest 和在测试中创建的 TestDispatchers 仍然会自动共享 Main 调度器的调度程序。

如果您没有替换 Main 调度器，请将您的第一个 TestDispatcher（它创建了一个新的调度程序）作为类的属性创建。然后，手动将该调度程序传递给每个 runTest 调用和每个新创建的 TestDispatcher，既作为属性，又在测试中。

class RepositoryTest {
    // Creates the single test scheduler
    private val testDispatcher = UnconfinedTestDispatcher()
    private val repository = Repository(testDispatcher)

    @Test
    fun someRepositoryTest() = runTest(testDispatcher.scheduler) {
        // Take the scheduler from the TestScope
        val newTestDispatcher = UnconfinedTestDispatcher(this.testScheduler)
        // Or take the scheduler from the first dispatcher, they’re the same
        val anotherTestDispatcher = UnconfinedTestDispatcher(testDispatcher.scheduler)

        // Test the repository...
    }
}
DispatchersOutsideTests.kt

在此示例中，第一个调度程序的调度程序被传递给 runTest。这将使用该调度程序为 TestScope 创建一个新的 StandardTestDispatcher。您也可以直接将调度程序传递给 runTest，以便在该调度程序上运行测试协程。

创建您自己的 TestScope

与 TestDispatchers 一样，您可能需要在测试体之外访问 TestScope。虽然 runTest 会在后台自动创建一个 TestScope，但您也可以创建自己的 TestScope，以便与 runTest 一起使用。

在执行此操作时，请确保在您创建的 TestScope 上调用 runTest

class SimpleExampleTest {
    val testScope = TestScope() // Creates a StandardTestDispatcher

    @Test
    fun someTest() = testScope.runTest {
        // ...
    }
}
CreatingYourOwn.kt

上面的代码隐式地为 TestScope 创建了一个 StandardTestDispatcher，以及一个新的调度程序。这些对象也可以显式地创建。如果您需要将其与依赖注入设置集成，这将非常有用。

class ExampleTest {
    val testScheduler = TestCoroutineScheduler()
    val testDispatcher = StandardTestDispatcher(testScheduler)
    val testScope = TestScope(testDispatcher)

    @Test
    fun someTest() = testScope.runTest {
        // ...
    }
}
CreatingYourOwn.kt

注入范围

如果您有一个创建协程的类，您需要在测试期间控制这些协程，您可以将协程范围注入该类，并在测试中用 TestScope 替换它。

在以下示例中，UserState 类依赖于 UserRepository 来注册新用户并获取已注册用户的列表。由于对 UserRepository 的这些调用是挂起函数调用，因此 UserState 使用注入的 CoroutineScope 在其 registerUser 函数中启动一个新的协程。

class UserState(
    private val userRepository: UserRepository,
    private val scope: CoroutineScope,
) {
    private val _users = MutableStateFlow(emptyList<String>())
    val users: StateFlow<List<String>> = _users.asStateFlow()

    fun registerUser(name: String) {
        scope.launch {
            userRepository.register(name)
            _users.update { userRepository.getAllUsers() }
        }
    }
}
UserState.kt

为了测试此类，您可以将 runTest 中的 TestScope 传递给创建 UserState 对象时。

class UserStateTest {
    @Test
    fun addUserTest() = runTest { // this: TestScope
        val repository = FakeUserRepository()
        val userState = UserState(repository, scope = this)

        userState.registerUser("Mona")
        advanceUntilIdle() // Let the coroutine complete and changes propagate

        assertEquals(listOf("Mona"), userState.users.value)
    }
}
UserStateTest.kt

要将范围注入测试函数之外，例如注入到作为测试类中的属性创建的测试对象中，请参阅 创建您自己的 TestScope。

其他资源

• 在 Android 上测试 Kotlin 流
• kotlinx.coroutines.test on GitHub