Unit testing API improvements

Author: wkornewald

README.md

@@ -1,10 +1,10 @@
-# ReactiveState for Kotlin Multiplatform and Android
+# ReactiveState
 
-[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.ensody.reactivestate/reactivestate/badge.svg?gav=true)](https://maven-badges.herokuapp.com/maven-central/com.ensody.reactivestate/reactivestate-core?gav=true)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.ensody.reactivestate/reactivestate-core/badge.svg?gav=true)](https://maven-badges.herokuapp.com/maven-central/com.ensody.reactivestate/reactivestate-core?gav=true)
 
-Easy reactive state management and ViewModels for Kotlin Multiplatform.
+Kotlin Multiplatform ViewModels and reactive state management based on `StateFlow`.
 
-See the [ReactiveState documentation](https://ensody.github.io/ReactiveState-Kotlin/reactivestate-core/) for more details.
+See the [ReactiveState documentation](https://ensody.github.io/ReactiveState-Kotlin/) for more details.
 
 ## Examples
 
@@ -60,7 +60,7 @@ val mutable: MutableStateFlow<Int> = readOnly.toMutable { value: Int ->
 }
 ```
 
-See the [ReactiveState documentation](https://ensody.github.io/ReactiveState-Kotlin/reactivestate-core/) for more details.
+See the [ReactiveState documentation](https://ensody.github.io/ReactiveState-Kotlin/) for more details.
 
 ## Supported platforms
 

build.gradle

@@ -219,16 +219,11 @@ subprojects {
 
 apply from: "$rootDir/gradle/common/dokka.gradle"
 setupDokka()
-dependencies {
-    dokka(project)
-}
 dokka {
-    dokkaSourceSets {
+    dokkaPublications {
         configureEach {
-            includes.from("README.md")
+            includes.from(rootProject.file("docs/README.md"))
         }
-    }
-    dokkaPublications {
         html {
             outputDirectory.set(project.file("build/docs/html"))
         }

docs/README.md

@@ -0,0 +1,102 @@
+# ReactiveState
+
+Kotlin Multiplatform ViewModels and reactive state management based on `StateFlow`.
+
+See the `reactivestate-core` module documentation as a starting point with several usage examples.
+
+## Short examples
+
+Map/transform a StateFlow:
+
+```kotlin
+val number = MutableStateFlow(0)
+val doubledNumber: StateFlow<Int> = derived { 2 * get(number) }
+```
+
+Collect two StateFlows (just collect without transforming):
+
+```kotlin
+val base = MutableStateFlow(0)
+val extra = MutableStateFlow(0)
+autoRun {
+    if (get(base) + get(extra) > 10) {
+        alert("You're flying too high")
+    }
+}
+```
+
+Multiplatform ViewModels with automatic error handling and loading indicator tracking:
+
+```kotlin
+class ExampleViewModel(scope: CoroutineScope, val repository: ExampleRepository) : ReactiveViewModel(scope) {
+    val inputFieldValue = MutableStateFlow("default")
+
+    fun submit() {
+        // The launch function automatically catches exceptions and increments/decrements the loading indicator.
+        // This way you can't forget the fundamentals that have to be always handled correctly.
+        launch {
+            repository.submit(inputFieldValue.value)
+        }
+    }
+}
+```
+
+Intercept MutableStateFlow:
+
+```kotlin
+public val state: MutableStateFlow<String> = MutableStateFlow("value").afterUpdate {
+    // This is called every time after someone sets `state.value = ...`
+}
+```
+
+Convert StateFlow to MutableStateFlow:
+
+```kotlin
+val readOnly: StateFlow<Int> = getSomeStateFlow()
+val mutable: MutableStateFlow<Int> = readOnly.toMutable { value: Int ->
+    // This is executed whenever someone sets `mutable.value = ...`.
+}
+```
+
+## Supported platforms
+
+android, jvm, ios, tvos, watchos, macosArm64, macosX64, mingwX64, linuxX64
+
+## Installation
+
+Add the package to your `build.gradle`:
+
+```groovy
+dependencies {
+    // Add the BOM using the desired ReactiveState version
+    api platform("com.ensody.reactivestate:reactivestate-bom:VERSION")
+    // Leave out the version number from now on.
+
+    // Jetpack Compose integration
+    implementation "com.ensody.reactivestate:reactivestate-compose"
+
+    // Android-only integration for Activity/Fragment
+    implementation "com.ensody.reactivestate:reactivestate-android"
+
+    // UI-independent core APIs
+    implementation "com.ensody.reactivestate:reactivestate-core"
+
+    // Utils for unit tests that want to use coroutines
+    implementation "com.ensody.reactivestate:reactivestate-core-test"
+
+    // Android-only unit test extensions
+    implementation "com.ensody.reactivestate:reactivestate-android-test"
+}
+```
+
+Also, make sure you've integrated the Maven Central repo, e.g. in your root `build.gradle`:
+
+```groovy
+subprojects {
+    repositories {
+        // ...
+        mavenCentral()
+        // ...
+    }
+}
+```

gradle/common/scm-version.gradle

@@ -30,7 +30,7 @@ ext.setupScmVersion = { args ->
         }
     }
     allprojects {
-        version = scmVersion.version
+        version = System.getenv("OVERRIDE_VERSION") ?: scmVersion.version
     }
     println("Version: $version")
 }

reactivestate-core-test/src/commonMain/kotlin/com/ensody/reactivestate/test/CoroutineTestRule.kt

@@ -1,8 +1,12 @@
 package com.ensody.reactivestate.test
 
+import com.ensody.reactivestate.ContextualErrorsFlow
+import com.ensody.reactivestate.ContextualValRoot
 import com.ensody.reactivestate.DefaultCoroutineDispatcherConfig
 import com.ensody.reactivestate.dispatchers
+import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.plus
 import kotlinx.coroutines.test.StandardTestDispatcher
 import kotlinx.coroutines.test.TestCoroutineScheduler
 import kotlinx.coroutines.test.TestDispatcher
@@ -30,7 +34,7 @@ public open class CoroutineTestRule(
     testDispatcherBuilder: (TestCoroutineScheduler) -> TestDispatcher = { StandardTestDispatcher(it) },
     context: CoroutineContext = EmptyCoroutineContext,
 ) {
-    public val testScope: TestScope = TestScope(context)
+    public val testScope: TestScope = TestScope(ContextualErrorsFlow.valued { ThrowOnEmitFlow() } + context)
     public val testDispatcher: TestDispatcher = testDispatcherBuilder(testScope.testScheduler)
 
     init {
@@ -52,3 +56,7 @@ public open class CoroutineTestRule(
         dispatchers = DefaultCoroutineDispatcherConfig
     }
 }
+
+/** Creates a [TestScope.backgroundScope] with a [ContextualValRoot] for ViewModels. */
+public fun TestScope.contextualBackgroundScope(): CoroutineScope =
+    backgroundScope + ContextualValRoot()

reactivestate-core-test/src/commonMain/kotlin/com/ensody/reactivestate/test/ThrowOnEmitFlow.kt

@@ -0,0 +1,13 @@
+package com.ensody.reactivestate.test
+
+import com.ensody.reactivestate.MutableFlow
+
+public class ThrowOnEmitFlow : MutableFlow<Throwable> by MutableFlow() {
+    override fun tryEmit(value: Throwable): Boolean {
+        throw value
+    }
+
+    override suspend fun emit(value: Throwable) {
+        throw value
+    }
+}

reactivestate-core/src/commonMain/kotlin/com/ensody/reactivestate/CoroutineLauncher.kt

@@ -93,10 +93,6 @@ public interface CoroutineLauncher {
     }
 }
 
-public val ContextualOnError: ContextualVal<(Throwable) -> Unit> = ContextualVal("ContextualOnError") {
-    { throw it }
-}
-
 public val ContextualStateFlowStore: ContextualVal<StateFlowStore> = ContextualVal("ContextualStateFlowStore") {
     error("ContextualStateFlowStore missing in CoroutineScope")
 }

reactivestate-core/src/commonMain/kotlin/com/ensody/reactivestate/ReactiveViewModel.kt

@@ -25,5 +25,6 @@ public abstract class ReactiveViewModel(final override val scope: CoroutineScope
 
 @ExperimentalReactiveStateApi
 public val ContextualErrorsFlow: ContextualVal<MutableFlow<Throwable>> = ContextualVal("ContextualErrorsFlow") {
+    requireContextualValRoot(it)
     MutableFlow(capacity = Channel.UNLIMITED, onBufferOverflow = BufferOverflow.DROP_OLDEST)
 }