Document CoroutineTestInterceptor (#185)

Co-authored-by: Jesse Wilson <jwilson@squareup.com>

Author: swankjesse

CHANGELOG.md

@@ -1,7 +1,7 @@
 # Change Log
 
 ## [Unreleased]
-[Unreleased]: https://github.com/cashapp/burst/compare/2.6.0...HEAD
+[Unreleased]: https://github.com/cashapp/burst/compare/2.7.1...HEAD
 
 Nothing yet!
 

README.md

@@ -188,6 +188,40 @@ cleaning up
 intercepted DrinkSodaTest.drinkSoda
 ```
 
+### Coroutines
+
+If your tests use [kotlinx-coroutines-test], you must use `CoroutineTestInterceptor` instead of
+`TestInterceptor`. Its intercept function suspends:
+
+```kotlin
+class DrinkSodaTest {
+  @InterceptTest
+  val loggingInterceptor = object : CoroutineTestInterceptor {
+    override suspend fun intercept(testFunction: CoroutineTestFunction) {
+      println("intercepting $testFunction")
+      testFunction()
+    }
+  }
+
+  @Test
+  fun drinkSoda() = runTest {
+    println("drinking a Pepsi")
+  }
+}
+```
+
+The `CoroutineTestFunction` has the `TestScope` property so interceptors have the same capabilities
+as tests.
+
+You’ll also need this Gradle dependency:
+
+```kotlin
+dependencies {
+  testImplementation("app.cash.burst:burst-coroutines:2.7.1")
+  ...
+}
+```
+
 ### Features and Limitations
 
 You can have multiple test interceptors in each class. They are executed in declaration order.
@@ -200,6 +234,9 @@ You can use `try/catch/finally` to execute code when tests fail.
 Intercepted test functions must be `final`. Mixing `@InterceptTest` with non-final test functions
 will cause a compilation error.
 
+You cannot mix and match `CoroutinesTestInterceptor` and `TestInterceptor` in the same test. You
+cannot use `runTest()` with `TestInterceptor`, and you must use it with `CoroutinesTestInterceptor`.
+
 
 Gradle Setup
 ------------
@@ -212,7 +249,7 @@ buildscript {
     mavenCentral()
   }
   dependencies {
-    classpath("app.cash.burst:burst-gradle-plugin:2.6.0")
+    classpath("app.cash.burst:burst-gradle-plugin:2.7.1")
   }
 }
 ```
@@ -233,7 +270,7 @@ certain versions of Kotlin.
 
 | Kotlin          | Burst         |
 |-----------------|---------------|
-| 2.2.0           | 2.6.0         |
+| 2.2.0           | 2.6.0 - 2.7.1 |
 | 2.1.20          | 2.5.0         |
 | 2.1.0           | 2.2.0 - 2.4.0 |
 | 2.0.20 - 2.0.21 | 0.1.0 - 2.1.0 |
@@ -261,3 +298,4 @@ License
 
 [JUnit Rules]: https://junit.org/junit4/javadoc/4.12/org/junit/Rule.html
 [TestParameterInjector]: https://github.com/google/TestParameterInjector
+[kotlinx-coroutines-test]: https://github.com/Kotlin/kotlinx.coroutines/blob/master/kotlinx-coroutines-test/

burst-coroutines/src/commonMain/kotlin/app/cash/burst/coroutines/CoroutineTestInterceptor.kt

@@ -17,6 +17,12 @@ package app.cash.burst.coroutines
 
 import kotlinx.coroutines.test.TestScope
 
+/**
+ * Intercepts the execution of a test function, including its `@BeforeTest` and `@AfterTest`
+ * functions.
+ *
+ * Test functions must make a single call to `kotlinx.coroutines.test.runTest` in their test body.
+ */
 interface CoroutineTestInterceptor {
   suspend fun intercept(
     testFunction: CoroutineTestFunction,
@@ -25,12 +31,27 @@ interface CoroutineTestInterceptor {
 
 abstract class CoroutineTestFunction(
   val scope: TestScope,
+  /** The package that this test is defined in, or "" it has none. */
   val packageName: String,
+  /** The classes that enclose the test function, separated by '.'. */
   val className: String,
+  /** The test function name. */
   val functionName: String,
 ) {
+  /**
+   * Runs the next interceptor in the chain if there is one.
+   *
+   * If there isn't, it runs the following in sequence:
+   *
+   *  * The `@BeforeTest` functions (if any)
+   *  * The `@Test` function
+   *  * The `@AfterTest` functions (if any)
+   */
   abstract suspend operator fun invoke()
 
+  /**
+   * Returns the full test name, like `com.example.project.FeatureTest.testMyFeature`.
+   */
   override fun toString(): String {
     return buildString {
       if (packageName.isNotEmpty()) {

burst-coroutines/src/commonTest/kotlin/app/cash/burst/CoroutineTestFunctionTest.kt

@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2025 Cash App
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package app.cash.burst
+
+import app.cash.burst.coroutines.CoroutineTestFunction
+import assertk.assertThat
+import assertk.assertions.isEqualTo
+import kotlin.test.Test
+import kotlinx.coroutines.test.runTest
+
+class CoroutineTestFunctionTest {
+  @Test
+  fun testToString() = runTest {
+    val testFunction = object : CoroutineTestFunction(
+      scope = this,
+      packageName = "app.cash.burst.test",
+      className = "SampleTest",
+      functionName = "happyPath",
+    ) {
+      override suspend fun invoke() {
+      }
+    }
+    assertThat(testFunction.toString()).isEqualTo("app.cash.burst.test.SampleTest.happyPath")
+  }
+
+  @Test
+  fun testToStringWithEmptyPackageName() = runTest {
+    val testFunction = object : CoroutineTestFunction(
+      scope = this,
+      packageName = "",
+      className = "SampleTest",
+      functionName = "happyPath",
+    ) {
+      override suspend fun invoke() {
+      }
+    }
+    assertThat(testFunction.toString()).isEqualTo("SampleTest.happyPath")
+  }
+}