dispatch-test-junit4/dispatch.test/TestCoroutineRule

TestCoroutineRule

@ExperimentalCoroutinesApi

class TestCoroutineRule(factory: () -> TestProvidedCoroutineScope) : TestWatcher, TestProvidedCoroutineScope

A basic JUnit 4 TestRule which creates a new TestProvidedCoroutineScope for each test, sets Dispatchers.Main, and calls cleanupTestCoroutines afterwards.

The rule itself implements TestProvidedCoroutineScope, so it can be used as follows:

Before the test:

Dispatchers.Main is set to the TestCoroutineDispatcher used by the CoroutineContext.

After the test:

cleanupTestCoroutines is called to ensure there are no leaking coroutines. Any unfinished coroutine will throw an UncompletedCoroutinesError.
Dispatchers.Main is reset via Dispatchers.resetMain.

Requires JUnit 4.

dependencies {
  testImplementation("junit:junit:4.12")
  -- or --
  testImplementation("org.junit.vintage:junit-vintage-engine:5.5.1")
}

Samples

import dispatch.test.TestCoroutineRule
import dispatch.test.TestProvidedCoroutineScope
import io.kotest.matchers.types.shouldBeInstanceOf
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import org.junit.Rule
import org.junit.Test
fun main() { 
   //sampleStart 
   @ExperimentalCoroutinesApi
class TestCoroutineRuleSample {

  @JvmField
  @Rule
  val rule = TestCoroutineRule()

  @Test
  fun `rule should be a TestProvidedCoroutineScope`() = runBlocking {

    rule.shouldBeInstanceOf<TestProvidedCoroutineScope>()

    rule.launch {
      // use the rule like any other CoroutineScope
    }
      .join()
  }
} 
   //sampleEnd
}

import dispatch.test.TestCoroutineRule
import dispatch.test.TestProvidedCoroutineScope
import io.kotest.matchers.shouldBe
import io.kotest.matchers.types.shouldBeInstanceOf
import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import org.junit.Rule
import org.junit.jupiter.api.Test
fun main() { 
   //sampleStart 
   @ExperimentalCoroutinesApi
class TestCoroutineRuleWithFactorySample {

  val customScope = TestProvidedCoroutineScope(
    context = CoroutineName("custom name")
  )

  @JvmField
  @Rule
  val rule = TestCoroutineRule { customScope }

  @Test
  fun `rule should be a TestProvidedCoroutineScope`() = runBlocking {

    rule.shouldBeInstanceOf<TestProvidedCoroutineScope>()

    rule.launch {
      // use the rule like any other CoroutineScope
    }
      .join()
  }

  @Test
  fun `rule should be the provided custom scope`() = runBlocking {

    val context = rule.coroutineContext

    context shouldBe customScope.coroutineContext
  }
} 
   //sampleEnd
}

Parameters

factory

optional factory for a custom TestProvidedCoroutineScope. If a factory is not provided, the resultant scope uses the same TestCoroutineDispatcher for each property in its TestDispatcherProvider