Use this skill to pick the correct Compose UI test entry point. Compares `createComposeRule()`, `createAndroidComposeRule<A>()`, `createEmptyComposeRule()`, `runComposeUiTest { }`, and `runAndroidComposeUiTest<A> { }`, plus the v1 vs v2 split (`UnconfinedTestDispatcher` vs `StandardTestDispatcher`). Encodes the rule that mixing `runComposeUiTest { }` and a `ComposeTestRule` in the same test is forbidden, that `setContent` may only run once, and that `createEmptyComposeRule()` returns `ComposeTestRule` (no `setContent`). Use when the user asks "ComposeTestRule vs ComposeUiTest", reports `IllegalStateException: setContent can only be called once`, mentions `runComposeUiTest`, the v2 deprecation warning, `effectContext`, custom `ComponentActivity`, or "host tests need a coroutine scope".
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Use this skill to pick the correct Compose UI test entry point. Compares `createComposeRule()`, `createAndroidComposeRule<A>()`, `createEmptyComposeRule()`, `runComposeUiTest { }`, and `runAndroidComposeUiTest<A> { }`, plus the v1 vs v2 split (`UnconfinedTestDispatcher` vs `StandardTestDispatcher`). Encodes the rule that mixing `runComposeUiTest { }` and a `ComposeTestRule` in the same test is forbidden, that `setContent` may only run once, and that `createEmptyComposeRule()` returns `ComposeTestRule` (no `setContent`). Use when the user asks "ComposeTestRule vs ComposeUiTest", reports `IllegalStateException: setContent can only be called once`, mentions `runComposeUiTest`, the v2 deprecation warning, `effectContext`, custom `ComponentActivity`, or "host tests need a coroutine scope".
license
Apache-2.0. See LICENSE for complete terms.
metadata
{"author":"Jaewoong Eum (skydoves)","keywords":["jetpack-compose","ui-testing","createComposeRule","createAndroidComposeRule","createEmptyComposeRule","runComposeUiTest","ComposeTestRule","ComposeUiTest","v2-test-api","StandardTestDispatcher","effect-context"]}
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.
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.
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.
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.
Patterns
Pattern: WRONG vs RIGHT — v1 vs v2 import
// WRONG — emits @Deprecated WARNING and uses UnconfinedTestDispatcherimport androidx.compose.ui.test.junit4.createComposeRule
classMyTest {
@get:Ruleval rule = createComposeRule()
}
// WRONG because: v1 dispatches LaunchedEffect work eagerly. After bumping// kotlinx-coroutines-test the same test will produce different observable// behavior than runTest { } in the rest of the codebase.
// RIGHT — v2, StandardTestDispatcher, no deprecation warningimport androidx.compose.ui.test.junit4.v2.createComposeRule
classMyTest {
@get:Ruleval rule = createComposeRule()
}
Pattern: WRONG vs RIGHT — mixing rule and lambda
// WRONGclassMyTest {
@get:Ruleval rule = createComposeRule() // env #1@Testfunbad() = runComposeUiTest { // env #2 — independent recomposer + clock
rule.setContent { App() } // sets content in env #1
onNodeWithTag("save").performClick() // queries env #2 — finds nothing
}
}
// WRONG because: each environment owns its own test scheduler and idling resource.// The KDoc forbids this configuration explicitly.
Pattern: WRONG vs RIGHT — createEmptyComposeRule misuse
// WRONG@get:Ruleval rule = createEmptyComposeRule()
@Testfunbroken() {
rule.setContent { App() } // compile error — ComposeTestRule has no setContent
}
// WRONG because: createEmptyComposeRule() returns ComposeTestRule, not ComposeContentTestRule.// It is for tests that launch their own ActivityScenario.
// RIGHT — launch your own scenario, then query@get:Ruleval rule = createEmptyComposeRule()
@Testfunok() {
ActivityScenario.launch(MyActivity::class.java).use {
// MyActivity.onCreate calls setContent { App() }
rule.onNodeWithTag("save").performClick()
}
}
Pattern: WRONG vs RIGHT — Activity already sets content
@get:Rule(order = 0) val hilt = HiltAndroidRule(this)
@get:Rule(order = 1) val compose = createAndroidComposeRule<HiltTestActivity>()
@Testfunfeed() {
hilt.inject()
compose.onNodeWithTag("feed_list").assertIsDisplayed()
}
This is the canonical reason to keep the JUnit4 rule path: RuleChain ordering. The lambda path has no equivalent — the developer has to manage Hilt initialization manually inside the suspending block.
Mandatory rules
MUST prefer v2 imports (androidx.compose.ui.test.junit4.v2.*, androidx.compose.ui.test.v2.*) over v1 for new code. The v1 forms are @Deprecated(level = WARNING).
MUST NOT mix runComposeUiTest { } and a @get:RuleComposeTestRule in the same test class. They manage independent test environments.
MUST NOT call setContent more than once per test. Both surfaces throw on the second call.
MUST NOT call composeTestRule.setContent when the launched Activity has already called setContent itself. Use createAndroidComposeRule<A>() and query the existing tree.
MUST match the rule constructor to the host requirements: createComposeRule() for ComponentActivity, createAndroidComposeRule<A>() for a custom Activity, createEmptyComposeRule() only when the test launches its own ActivityScenario.
MUST declare any custom Activity used by createAndroidComposeRule<A>() in src/androidTest/AndroidManifest.xml (or src/debug/AndroidManifest.xml) — see ./configuring-test-dependencies/SKILL.md.
PREFERRED: when production code uses heavy LaunchedEffects or rememberCoroutineScope, use the lambda path with effectContext = StandardTestDispatcher() so composition and the test body share one scheduler.
PREFERRED: rely on mainClock.advanceTimeBy(0) (test clock) rather than runOnIdle { } (wall clock + idle wait) to drain v2 queued work — see ../../synchronization/testing-animations-deterministically/SKILL.md for the autoAdvance contract.
Verification
No import androidx.compose.ui.test.junit4.createComposeRule (v1) remains in new code; v2 path imported instead.
No @DeprecatedWARNING from the IDE on the test entry point.
The test class either uses a @get:RuleComposeTestRule OR a runComposeUiTest { } block, never both.
setContent is called exactly once per test method (zero times when the Activity sets content itself).
createEmptyComposeRule() only appears in tests that explicitly launch their own ActivityScenario.
If effectContext is passed, the test compiles with @OptIn(ExperimentalTestApi::class) (or the v2 equivalent) and mainClock.advanceTimeBy(0) is added where queued work needs draining.
