TestBase documented

Author: elizarov

kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/TestBase.kt

@@ -21,33 +21,76 @@ import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.atomic.AtomicInteger
 import java.util.concurrent.atomic.AtomicReference
 
+/**
+ * Base class for tests, so that tests for predictable scheduling of actions in multiple coroutines sharing a single
+ * thread can be written. Use it like this:
+ *
+ * ```
+ * class MyTest {
+ *    @Test
+ *    fun testSomething() = runBlocking<Unit> { // run in the context of the main thread
+ *        expect(1) // initiate action counter
+ *        val job = launch(context) { // use the context of the main thread
+ *           expect(3) // the body of this coroutine in going to be executed in the 3rd step
+ *        }
+ *        expect(2) // launch just scheduled coroutine for exectuion later, so this line is executed second
+ *        yield() // yield main thread to the launched job
+ *        finish(4) // fourth step is the last one. `finish` must be invoked or test fails
+ *    }
+ * }
+ * ```
+ */
 open class TestBase {
+    /**
+     * Is `true` when nightly stress test is done.
+     */
     val isStressTest = System.getProperty("stressTest") != null
+
+    /**
+     * Multiply various constants in stress tests by this factor, so that they run longer during nightly stress test.
+     */
     val stressTestMultiplier = if (isStressTest) 30 else 1
 
-    var actionIndex = AtomicInteger()
-    var finished = AtomicBoolean()
-    var error = AtomicReference<Throwable>()
+    private var actionIndex = AtomicInteger()
+    private var finished = AtomicBoolean()
+    private var error = AtomicReference<Throwable>()
 
+    /**
+     * Throws [IllegalStateException] like `error` in stdlib, but also ensures that the test will not
+     * complete successfully even if this exception is consumed somewhere in the test.
+     */
     public fun error(message: Any): Nothing {
         val exception = IllegalStateException(message.toString())
         error.compareAndSet(null, exception)
         throw exception
     }
 
+    /**
+     * Throws [IllegalStateException] when `value` is false like `check` in stdlib, but also ensures that the
+     * test will not complete successfully even if this exception is consumed somewhere in the test.
+     */
     public inline fun check(value: Boolean, lazyMessage: () -> Any): Unit {
         if (!value) error(lazyMessage())
     }
 
+    /**
+     * Asserts that this invocation is `index`-th in the execution sequence (counting from one).
+     */
     fun expect(index: Int) {
         val wasIndex = actionIndex.incrementAndGet()
         check(index == wasIndex) { "Expecting action index $index but it is actually $wasIndex" }
     }
 
+    /**
+     * Asserts that this line is never executed.
+     */
     fun expectUnreached() {
         error("Should not be reached")
     }
 
+    /**
+     * Asserts that this it the last action in the test. It must be invoked by any test that used [expect].
+     */
     fun finish(index: Int) {
         expect(index)
         check(!finished.getAndSet(true)) { "Should call 'finish(...)' at most once" }
@@ -58,5 +101,4 @@ open class TestBase {
         error.get()?.let { throw it }
         check(actionIndex.get() == 0 || finished.get()) { "Expecting that 'finish(...)' was invoked, but it was not" }
     }
-
 }