Choosing Test Rule Vs Runtest

Choosing Test Rule vs runComposeUiTest — One Entry Point Per Test

Compose ships two parallel test entry points: a JUnit4 TestRule (createComposeRule() and friends) and a multiplatform suspending lambda (runComposeUiTest { }). Each one independently sets up the recomposer, MainTestClock, and IdlingResource. Mixing them in a single test produces double-environment bugs that are hard to diagnose. This skill picks the right one and surfaces the v1 → v2 deprecation that bites every existing codebase.

When to use this skill

• The user is starting a new Compose UI test and is choosing between createComposeRule() and runComposeUiTest { }.
• The IDE shows a deprecation WARNING on import androidx.compose.ui.test.junit4.createComposeRule or import androidx.compose.ui.test.runComposeUiTest.
• The user reports tests passing on v1 entry points but breaking after migrating because LaunchedEffects no longer run synchronously.
• The user has a custom ComponentActivity subclass and is unsure between createAndroidComposeRule and createEmptyComposeRule.
• The user reports IllegalStateException: setContent can only be called once per ComposeTestRule or "the launched Activity already calls setContent".
• The user is writing Compose Multiplatform (KMP) tests and needs the suspending entry point.

When NOT to use this skill

• The dependencies do not yet compile — start with ./configuring-test-dependencies/SKILL.md.
• The choice is host vs device, not rule vs lambda — see ./setting-up-host-vs-device-tests/SKILL.md.
• The test compiles and runs but flakes on idle/animation — see ../../synchronization/synchronizing-with-idle/SKILL.md and ../../synchronization/testing-animations-deterministically/SKILL.md.

Prerequisites

• androidx.compose.ui:ui-test, androidx.compose.ui:ui-test-junit4, and (for createComposeRule() / runComposeUiTest { }) androidx.compose.ui:ui-test-manifest on the right configurations — see ./configuring-test-dependencies/SKILL.md.
• A test class with JUnit4 on the classpath if the developer chooses the rule path.
• Working knowledge that MainTestClock and the recomposer share one kotlinx.coroutines.test.TestCoroutineScheduler.

Workflow

• 1. Decide JUnit4 rule vs suspending lambda.

  Path	Choose when
  createComposeRule() / createAndroidComposeRule<A>()	The codebase already uses JUnit4 rules; the developer wants one rule chained with RuleChain (e.g. HiltAndroidRule); the test is Android-only.
  runComposeUiTest { } / runAndroidComposeUiTest<A> { }	Compose Multiplatform; the developer wants effectContext: CoroutineContext to inject a TestDispatcher; the test is suspending end-to-end.

  Both surfaces expose the same matchers, finders, actions, and MainTestClock. The rule path is more familiar to existing Android engineers; the lambda path is the long-term recommendation for multiplatform.

• 2. Pick the right rule constructor for the JUnit4 path.

  Constructor	Returns	Hosts	setContent available?
  createComposeRule()	ComposeContentTestRule	androidx.activity.ComponentActivity (from ui-test-manifest)	Yes
  createAndroidComposeRule<A : ComponentActivity>()	AndroidComposeTestRule<ActivityScenarioRule<A>, A>	Custom Activity A (developer-declared in test manifest)	Yes
  createEmptyComposeRule()	ComposeTestRule (NOT ComposeContentTestRule)	None — developer launches their own scenario	No

  Source: compose/ui/ui-test-junit4/src/jvmAndAndroidMain/kotlin/androidx/compose/ui/test/junit4/ComposeTestRule.jvmAndAndroid.kt declares interface ComposeContentTestRule : ComposeTestRule { fun setContent(...) }; createEmptyComposeRule() returns the parent type only.

• 3. Pick the right suspending entry point for the lambda path.

  Function	Receiver	Hosts
  runComposeUiTest { }	ComposeUiTest	ComponentActivity
  runAndroidComposeUiTest<A> { }	AndroidComposeUiTest<A> (adds val activity: A?)	Custom Activity A
  runEmptyComposeUiTest { }	ComposeUiTest	None — setContent throws IllegalStateException

  runComposeUiTest and runAndroidComposeUiTest accept effectContext: CoroutineContext = EmptyCoroutineContext, runTestContext: CoroutineContext = EmptyCoroutineContext, and testTimeout: Duration = 60.seconds. runEmptyComposeUiTest is the exception — it accepts only block: ComposeUiTest.() -> Unit (no scheduling parameters); its purpose is to let the test launch its own ActivityScenario inside the block. Source: compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeUiTest.android.kt:184, 232, 352 (v1) and the v2 actuals at …/v2/ComposeUiTest.android.kt:75, 122, 238.

• 4. Prefer the v2 entry points over v1. This is non-negotiable for new code. The v1 forms (androidx.compose.ui.test.junit4.createComposeRule, androidx.compose.ui.test.runComposeUiTest) carry @Deprecated(level = DeprecationLevel.WARNING). The deprecation message on runComposeUiTest (verbatim from ComposeUiTest.android.kt) is:

"Use `androidx.compose.ui.test.v2.runComposeUiTest` instead. The v2 APIs align with
 standard coroutine behavior by queuing tasks rather than executing them
 immediately. Tests relying on immediate execution may require explicit
 synchronization. Please refer to the migration guide for more details."

createComposeRule() carries an analogous but separate deprecation message (in ComposeTestRule.jvmAndAndroid.kt:347-355) pointing at androidx.compose.ui.test.junit4.v2.createComposeRule. The two messages are NOT byte-identical — quote whichever applies to the API the developer is actually migrating.

Migration mapping:

Behavior delta: v1 uses UnconfinedTestDispatcher (eager), v2 uses StandardTestDispatcher (queued). After migration, tests that relied on a LaunchedEffect / rememberCoroutineScope block running synchronously may need an explicit mainClock.advanceTimeBy(0) or runCurrent() to drain queued work. This is the only common breaking change.

• 5. NEVER mix the two surfaces in the same test. Both manage independent test environments. The KDoc on runComposeUiTest (lines 157-160 of ComposeUiTest.android.kt) is explicit:

"Keeping a reference to the [ComposeUiTest] outside of this function is an error. Also avoid
 using [androidx.compose.ui.test.junit4.ComposeTestRule] (e.g., createComposeRule) inside
 [runComposeUiTest][block] or any of their respective variants. Since these APIs independently
 manage the test environment, mixing them may lead to unexpected behavior."

Symptoms of accidental mixing: doubled setContent calls, recompositions running on the wrong scheduler, MainTestClock advancing in one environment but not the other, waitForIdle returning instantly because it queries the wrong recomposer.

• 6. Call setContent exactly once per test. Both ComposeContentTestRule.setContent and ComposeUiTest.setContent throw IllegalStateException on the second call. Recompose with state mutations, do NOT re-call setContent.

• 7. If the launched Activity calls setContent itself, do NOT call composeTestRule.setContent. The Activity has already installed Compose content; the rule call would override and orphan the previous tree. Use createAndroidComposeRule<MyActivity>() and read the existing tree directly via finders. The KDoc at line 200-204 of ComposeUiTest.android.kt warns: "if the Activity sets content during its launch, you cannot use setContent on the ComposeUiTest anymore as this would override the content and can lead to subtle bugs."

• 8. When custom coroutine semantics are needed, use effectContext. The lambda path takes a CoroutineContext that becomes the parent of LaunchedEffects and rememberCoroutineScope scopes. From ComposeUiTest.android.kt: "If this context contains a TestDispatcher or TestCoroutineScheduler (in that order), it will be used for composition and the MainTestClock." Pass a shared TestDispatcher to coordinate the test body's coroutine scheduler with composition's scheduler. The JUnit4 rule has no equivalent first-class hook — that is a real reason to prefer the lambda path when the production code does heavy LaunchedEffect work.

• 9. Default testTimeout is 60 seconds. From the same file, testTimeout: Duration = 60.seconds. Tests that exceed it throw AndroidComposeUiTestTimeoutException. Override per-test only; never globally raise it to mask flakes.