Rename headlessIntegrationTest -> renderForTest and deprecate launchForTestingFrom*

Author: steve-the-edwards

workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderTester.kt

@@ -112,6 +112,14 @@ public fun <PropsT, StateT, OutputT, RenderingT>
  * - It is a test failure if no workflow or worker emitted an output, no rendering event was
  *   invoked, and any of the action verification methods on [RenderTestResult] is called.
  *
+ * ## Testing Application
+ *
+ * Note that by providing the values for all child workflows, workers, and side effects, the test
+ * is extremely focused on the logic of the `render()` method. Everything else is essentially
+ * 'mocked'. If you do not have complex logic within `render()` that needs to be directly unit
+ * tested, then you may be better served by using a [WorkflowTurbine] and [renderForResult] as this
+ * will actually run your workflow (and any children, fake or not) in the runtime.
+ *
  * ## Examples
  *
  * ### Worker output

workflow-testing/src/main/java/com/squareup/workflow1/testing/WorkflowTestRuntime.kt

@@ -53,6 +53,7 @@ import kotlin.coroutines.EmptyCoroutineContext
  *  - [sendProps]
  *    - Send a new [PropsT] to the root workflow.
  */
+@Deprecated("Use renderForTest and WorkflowTurbine instead.")
 public class WorkflowTestRuntime<PropsT, OutputT, RenderingT> @TestOnly internal constructor(
   private val props: MutableStateFlow<PropsT>,
   private val renderingsAndSnapshotsFlow: Flow<RenderingAndSnapshot<RenderingT>>,
@@ -173,6 +174,7 @@ public class WorkflowTestRuntime<PropsT, OutputT, RenderingT> @TestOnly internal
  *
  * All workflow-related coroutines are cancelled when the block exits.
  */
+@Deprecated("Use renderForTest and WorkflowTurbine instead.")
 @TestOnly
 public fun <T, PropsT, OutputT, RenderingT>
   Workflow<PropsT, OutputT, RenderingT>.launchForTestingFromStartWith(
@@ -187,6 +189,7 @@ public fun <T, PropsT, OutputT, RenderingT>
  *
  * All workflow-related coroutines are cancelled when the block exits.
  */
+@Deprecated("Use renderForTest and WorkflowTurbine instead.")
 @TestOnly
 public fun <T, OutputT, RenderingT>
   Workflow<Unit, OutputT, RenderingT>.launchForTestingFromStartWith(
@@ -202,6 +205,7 @@ public fun <T, OutputT, RenderingT>
  *
  * All workflow-related coroutines are cancelled when the block exits.
  */
+@Deprecated("Use renderForTest and WorkflowTurbine instead.")
 @TestOnly
 public fun <T, PropsT, StateT, OutputT, RenderingT>
   StatefulWorkflow<PropsT, StateT, OutputT, RenderingT>.launchForTestingFromStateWith(
@@ -223,6 +227,7 @@ public fun <T, PropsT, StateT, OutputT, RenderingT>
  *
  * All workflow-related coroutines are cancelled when the block exits.
  */
+@Deprecated("Use renderForTest and WorkflowTurbine instead.")
 @TestOnly
 public fun <StateT, OutputT, RenderingT>
   StatefulWorkflow<Unit, StateT, OutputT, RenderingT>.launchForTestingFromStateWith(
@@ -236,6 +241,7 @@ public fun <StateT, OutputT, RenderingT>
  *
  * All workflow-related coroutines are cancelled when the block exits.
  */
+@Deprecated("Use renderForTest and WorkflowTurbine instead.")
 @TestOnly
 public fun <T, PropsT, StateT, OutputT, RenderingT>
   StatefulWorkflow<PropsT, StateT, OutputT, RenderingT>.launchForTestingWith(

workflow-testing/src/main/java/com/squareup/workflow1/testing/HeadlessIntegrationTest.kt renamed to workflow-testing/src/main/java/com/squareup/workflow1/testing/WorkflowTurbine.kt

@@ -3,9 +3,9 @@ package com.squareup.workflow1.testing
 import app.cash.turbine.ReceiveTurbine
 import app.cash.turbine.test
 import com.squareup.workflow1.RuntimeConfig
-import com.squareup.workflow1.RuntimeConfigOptions
 import com.squareup.workflow1.Workflow
 import com.squareup.workflow1.WorkflowInterceptor
+import com.squareup.workflow1.config.JvmTestRuntimeConfigTools
 import com.squareup.workflow1.renderWorkflowIn
 import com.squareup.workflow1.testing.WorkflowTurbine.Companion.WORKFLOW_TEST_DEFAULT_TIMEOUT_MS
 import kotlinx.coroutines.CoroutineScope
@@ -22,8 +22,8 @@ import kotlin.coroutines.CoroutineContext
 import kotlin.time.Duration.Companion.milliseconds
 
 /**
- * This is a test harness to run integration tests for a Workflow tree. The parameters passed here are
- * the same as those to start a Workflow runtime with [renderWorkflowIn] except for ignoring
+ * This is a test harness to run turbine like tests for a Workflow tree. The parameters passed here
+ * are the same as those to start a Workflow runtime with [renderWorkflowIn] except for ignoring
  * state persistence as that is not needed for this style of test.
  *
  * The [coroutineContext] rather than a [CoroutineScope] is passed so that this harness handles the
@@ -35,13 +35,15 @@ import kotlin.time.Duration.Companion.milliseconds
  * This will start the Workflow runtime (with params as passed) rooted at whatever Workflow
  * it is called on and then create a [WorkflowTurbine] for its renderings and run [testCase] on that.
  * [testCase] can thus drive the test scenario and assert against renderings.
+ *
+ * The default [RuntimeConfig] will be the one specified via [JvmTestRuntimeConfigTools].
  */
 @OptIn(ExperimentalCoroutinesApi::class)
-public fun <PropsT, OutputT, RenderingT> Workflow<PropsT, OutputT, RenderingT>.headlessIntegrationTest(
+public fun <PropsT, OutputT, RenderingT> Workflow<PropsT, OutputT, RenderingT>.renderForTest(
   props: StateFlow<PropsT>,
   coroutineContext: CoroutineContext = UnconfinedTestDispatcher(),
   interceptors: List<WorkflowInterceptor> = emptyList(),
-  runtimeConfig: RuntimeConfig = RuntimeConfigOptions.DEFAULT_CONFIG,
+  runtimeConfig: RuntimeConfig = JvmTestRuntimeConfigTools.getTestRuntimeConfig(),
   onOutput: suspend (OutputT) -> Unit = {},
   testTimeout: Long = WORKFLOW_TEST_DEFAULT_TIMEOUT_MS,
   testCase: suspend WorkflowTurbine<RenderingT>.() -> Unit
@@ -82,18 +84,18 @@ public fun <PropsT, OutputT, RenderingT> Workflow<PropsT, OutputT, RenderingT>.h
 }
 
 /**
- * Version of [headlessIntegrationTest] that does not require props. For Workflows that have [Unit]
+ * Version of [renderForTest] that does not require props. For Workflows that have [Unit]
  * props type.
  */
 @OptIn(ExperimentalCoroutinesApi::class)
-public fun <OutputT, RenderingT> Workflow<Unit, OutputT, RenderingT>.headlessIntegrationTest(
+public fun <OutputT, RenderingT> Workflow<Unit, OutputT, RenderingT>.renderForTest(
   coroutineContext: CoroutineContext = UnconfinedTestDispatcher(),
   interceptors: List<WorkflowInterceptor> = emptyList(),
-  runtimeConfig: RuntimeConfig = RuntimeConfigOptions.DEFAULT_CONFIG,
+  runtimeConfig: RuntimeConfig = JvmTestRuntimeConfigTools.getTestRuntimeConfig(),
   onOutput: suspend (OutputT) -> Unit = {},
   testTimeout: Long = WORKFLOW_TEST_DEFAULT_TIMEOUT_MS,
   testCase: suspend WorkflowTurbine<RenderingT>.() -> Unit
-): Unit = headlessIntegrationTest(
+): Unit = renderForTest(
   props = MutableStateFlow(Unit).asStateFlow(),
   coroutineContext = coroutineContext,
   interceptors = interceptors,

workflow-testing/src/test/java/com/squareup/workflow1/WorkflowsLifecycleTests.kt

@@ -7,7 +7,7 @@ import com.squareup.workflow1.RuntimeConfigOptions.CONFLATE_STALE_RENDERINGS
 import com.squareup.workflow1.RuntimeConfigOptions.Companion.RuntimeOptions
 import com.squareup.workflow1.RuntimeConfigOptions.Companion.RuntimeOptions.NONE
 import com.squareup.workflow1.RuntimeConfigOptions.DRAIN_EXCLUSIVE_ACTIONS
-import com.squareup.workflow1.testing.headlessIntegrationTest
+import com.squareup.workflow1.testing.renderForTest
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.awaitCancellation
@@ -84,7 +84,7 @@ class WorkflowsLifecycleTests(
   }
 
   @Test fun sideEffectsStartedWhenExpected() {
-    workflowWithSideEffects.headlessIntegrationTest(
+    workflowWithSideEffects.renderForTest(
       runtimeConfig = runtimeConfig
     ) {
       // One time starts but does not stop the side effect.
@@ -98,7 +98,7 @@ class WorkflowsLifecycleTests(
   }
 
   @Test fun sideEffectsStoppedWhenExpected() {
-    workflowWithSideEffects.headlessIntegrationTest(
+    workflowWithSideEffects.renderForTest(
       runtimeConfig = runtimeConfig
     ) {
       // Twice will start and stop the side effect.
@@ -112,7 +112,7 @@ class WorkflowsLifecycleTests(
   }
 
   @Test fun childSessionWorkflowStartedWhenExpected() {
-    workflowWithChildSession.headlessIntegrationTest(
+    workflowWithChildSession.renderForTest(
       runtimeConfig = runtimeConfig
     ) {
       // One time starts but does not stop the child session workflow.
@@ -139,7 +139,7 @@ class WorkflowsLifecycleTests(
   @Test
   fun sideEffectsStartAndStoppedWhenHandledSynchronously() {
     val dispatcher = UnconfinedTestDispatcher()
-    workflowWithSideEffects.headlessIntegrationTest(
+    workflowWithSideEffects.renderForTest(
       coroutineContext = dispatcher,
       runtimeConfig = runtimeConfig
     ) {
@@ -163,7 +163,7 @@ class WorkflowsLifecycleTests(
   }
 
   @Test fun childSessionWorkflowStoppedWhenExpected() {
-    workflowWithChildSession.headlessIntegrationTest(
+    workflowWithChildSession.renderForTest(
       runtimeConfig = runtimeConfig
     ) {
       // Twice will start and stop the child session workflow.
@@ -185,7 +185,7 @@ class WorkflowsLifecycleTests(
   @Test
   fun childSessionWorkflowStartAndStoppedWhenHandledSynchronously() {
     val dispatcher = UnconfinedTestDispatcher()
-    workflowWithChildSession.headlessIntegrationTest(
+    workflowWithChildSession.renderForTest(
       coroutineContext = dispatcher,
       runtimeConfig = runtimeConfig
     ) {