Skip to content
Back to skills

Compose Testing

ASecurity

Compose UI tests per Google's docs: test rules, semantics finders, merged trees, synchronization, state restoration, configuration overrides, accessibility checks. Use when writing or debugging Compose UI or component tests, including nodes not found or matched several times, children hidden by merging, off-screen lazy items, sleeps, and flaky waits for async data.

  • 5 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
developmentgokotlinnodetestingdebuggingapi

Works with

  • cli
  • api

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 18, 2026

npx -y skills add pablitoarango/android-skills --skill compose-testing --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Compose Testing?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Compose Testing
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/pablitoarango-compose-testing/badge)](https://www.skillsdirectory.com/skills/pablitoarango-compose-testing)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: compose-testing
description: "Compose UI tests per Google's docs: test rules, semantics finders, merged trees, synchronization, state restoration, configuration overrides, accessibility checks. Use when writing or debugging Compose UI or component tests, including nodes not found or matched several times, children hidden by merging, off-screen lazy items, sleeps, and flaky waits for async data."
---

# Compose UI Testing

Sources of truth: [Test your Compose layout](https://developer.android.com/develop/ui/compose/testing), [Testing APIs](https://developer.android.com/develop/ui/compose/testing/apis), [Synchronization](https://developer.android.com/develop/ui/compose/testing/synchronization), [Common patterns](https://developer.android.com/develop/ui/compose/testing/common-patterns), [Accessibility testing](https://developer.android.com/develop/ui/compose/accessibility/testing), [Migrate to v2 testing APIs](https://developer.android.com/develop/ui/compose/testing/migrate-v2), [Interoperability](https://developer.android.com/develop/ui/compose/testing/interoperability), [Robolectric](https://developer.android.com/training/testing/local-tests/robolectric).

If the project defines its own UI test conventions (for example page objects or a mocked HTTP layer for instrumented tests), follow those for that kind of test. For overall test strategy, ViewModel tests and screenshot tests, see `android-testing`.

## 1. Setup

```kotlin
androidTestImplementation("androidx.compose.ui:ui-test-junit4")
androidTestImplementation("androidx.compose.ui:ui-test-junit4-accessibility")
debugImplementation("androidx.compose.ui:ui-test-manifest")
testImplementation("androidx.compose.ui:ui-test-junit4")
testImplementation("org.robolectric:robolectric")

android {
    testOptions {
        unitTests {
            isIncludeAndroidResources = true
        }
    }
}
```

- The same test code runs as a local test with Robolectric or as an instrumented test. Robolectric tests need `isIncludeAndroidResources = true` to load resources.
- Import the rule factories from `androidx.compose.ui.test.junit4.v2`, and `runComposeUiTest` from `androidx.compose.ui.test.v2`. The v1 versions in `androidx.compose.ui.test.junit4` and `androidx.compose.ui.test` are deprecated; see [Migrate to v2 testing APIs](https://developer.android.com/develop/ui/compose/testing/migrate-v2).
- `createComposeRule()`: test composables in isolation; no Activity access needed.
- `createAndroidComposeRule<ComponentActivity>()`: when you also need Activity resources (`composeTestRule.activity.getString(...)`). Use `createAndroidComposeRule<YourActivity>()` for a real screen, including mixed View and Compose screens.

## 2. Test stateless composables in isolation

Test the stateless screen composable with fixed UI state and fake callbacks, not a composable that creates a ViewModel.

```kotlin
import androidx.compose.ui.test.junit4.v2.createAndroidComposeRule

class ArticleScreenTest {

    @get:Rule
    val composeTestRule = createAndroidComposeRule<ComponentActivity>()

    @Test
    fun bookmarkButton_whenClicked_reportsArticleId() {
        var bookmarkedId: String? = null
        composeTestRule.setContent {
            AppTheme {
                ArticleScreen(
                    uiState = ArticleUiState.Success(sampleArticle),
                    onBookmarkClick = { bookmarkedId = it },
                )
            }
        }

        val bookmarkLabel = composeTestRule.activity.getString(R.string.bookmark)
        composeTestRule.onNodeWithContentDescription(bookmarkLabel).performClick()

        composeTestRule.runOnIdle {
            assertEquals(sampleArticle.id, bookmarkedId)
        }
    }
}
```

## 3. Finding nodes

Compose tests query the **semantics tree**, not views.

- Prefer what users perceive: `onNodeWithText`, `onNodeWithContentDescription`, and role/state matchers. Load strings from resources rather than hardcoding them.
- Use `Modifier.testTag("...")` + `onNodeWithTag` when no user-visible property identifies the node uniquely.
- Combine matchers: `onNode(hasText("Save") and hasClickAction())`.
- Hierarchy: `hasParent`, `hasAnyAncestor`, `hasAnySibling`, `hasAnyDescendant`.
- Multiple nodes: `onAllNodes(matcher)`, `onAllNodesWithTag(...)`, then `.onFirst()`, `.filter(...)`, `.assertCountEquals(n)`, `.assertAll(...)`, `.assertAny(...)`.

### Merged vs unmerged tree

Clickable elements and `mergeDescendants` merge their children into one node, so by default a finder sees the merged node. To reach a child inside it, pass `useUnmergedTree = true`.

```kotlin
composeTestRule.onNodeWithText("World", useUnmergedTree = true).assertIsDisplayed()
```

Debug with `composeTestRule.onRoot().printToLog("TAG")` (add `useUnmergedTree = true` to see children).

## 4. Assertions and actions

- Assertions: `assertIsDisplayed()`, `assertExists()`, `assertDoesNotExist()`, `assertTextEquals(...)`, `assertIsEnabled()`, `assertIsSelected()`, `assert(matcher)`.
- Actions: `performClick()`, `performTextInput(...)`, `performTextClearance()`, `performScrollTo()`, `performScrollToIndex(n)` (lazy lists), `performTouchInput { swipeLeft() }`, `performSemanticsAction(...)`.
- Call each action separately; actions do not chain inside one `perform` call.
- Lazy lists compose only visible items: scroll to an item before asserting on it.

## 5. Synchronization

- Finders, assertions and actions wait until Compose is idle, advancing a **virtual clock** automatically. Do not add `Thread.sleep`.
- Changing state outside composition has no visible effect until the next synchronizing call.
- The v2 rules run composition coroutines on a `StandardTestDispatcher`: launched work is queued, not run at once. Before asserting on plain variables or ViewModel state after triggering work, call `composeTestRule.waitForIdle()` or wrap the assertion in `composeTestRule.runOnIdle { }`. With auto-advance off, run queued tasks without moving the clock using `composeTestRule.mainClock.scheduler.runCurrent()`.
- Do not combine a compose rule with `runTest`; that creates two separate clocks. For coroutine-based tests use `runComposeUiTest { }` from `androidx.compose.ui.test.v2`, whose body already runs in a `runTest` scope that shares the Compose clock.
- Work Compose cannot see (data loading, background threads) needs `waitUntil`:

```kotlin
composeTestRule.waitUntilAtLeastOneExists(hasText("Loaded"), timeoutMillis = 5_000)
composeTestRule.waitUntilDoesNotExist(hasTestTag("loading"), timeoutMillis = 5_000)
composeTestRule.waitUntilExactlyOneExists(hasTestTag("result"))
composeTestRule.waitUntilNodeCount(hasTestTag("row"), count = 3)
```

- Register long-running non-Compose work with `registerIdlingResource` / `unregisterIdlingResource`.
- Test animations frame by frame by turning off auto-advance:

```kotlin
composeTestRule.mainClock.autoAdvance = false
composeTestRule.onNodeWithText("Expand").performClick()
composeTestRule.mainClock.advanceTimeBy(150)
composeTestRule.onNodeWithTag("details").assertIsDisplayed()
```

## 6. State restoration and configurations

Verify `rememberSaveable` state survives recreation without recreating an Activity:

```kotlin
@Test
fun query_survivesRecreation() {
    val restorationTester = StateRestorationTester(composeTestRule)
    restorationTester.setContent { SearchBar() }

    composeTestRule.onNodeWithTag("query").performTextInput("yoga")
    restorationTester.emulateSavedInstanceStateRestore()

    composeTestRule.onNodeWithTag("query").assertTextEquals("yoga")
}
```

Test sizes, font scale, dark mode, locale and layout direction with `DeviceConfigurationOverride`:

```kotlin
composeTestRule.setContent {
    DeviceConfigurationOverride(
        DeviceConfigurationOverride.FontScale(2f) then
            DeviceConfigurationOverride.ForcedSize(DpSize(1280.dp, 800.dp)),
    ) {
        AppTheme { ArticleScreen(uiState = sampleUiState, onBookmarkClick = {}) }
    }
}
```

## 7. Accessibility checks

Run automated accessibility checks with `ui-test-junit4-accessibility` and an `AndroidComposeTestRule`, such as `createAndroidComposeRule<ComponentActivity>()`. Align Compose artifacts with the project's BOM; check the [Compose UI releases](https://developer.android.com/jetpack/androidx/releases/compose-ui) for API availability. Checks flag missing labels, small touch targets, low contrast and traversal problems.

```kotlin
composeTestRule.enableAccessibilityChecks()
composeTestRule.setContent { AppTheme { ArticleScreen(uiState = sampleUiState, onBookmarkClick = {}) } }
composeTestRule.onRoot().tryPerformAccessibilityChecks()
```

Once enabled, checks also run during actions such as `performClick()`. See `compose-accessibility`.

## 8. Custom semantics

Add a custom `SemanticsPropertyKey` only for values that are hard to match otherwise (for example a date picker's selected value), and never to expose visual details such as colors or font sizes.

## 9. Interop

- Espresso and Compose test APIs work together in the same test for mixed screens.
- When identical Compose content appears in several Views (RecyclerView rows, ViewPager pages), scope the search with `onRootWithViewInteraction(viewInteraction)` on the rule, passing an Espresso `ViewInteraction`, instead of adding test tags. This API is experimental.
- For UiAutomator, set `Modifier.semantics { testTagsAsResourceId = true }` near the root so test tags are exposed as resource IDs.

## 10. Checklist

- [ ] The stateless composable is tested with fixed UI state and fake lambdas.
- [ ] Nodes are found by text, content description or role first; `testTag` only when needed.
- [ ] Strings come from resources.
- [ ] No sleeps; external work uses `waitUntil*` or idling resources.
- [ ] `rememberSaveable` state is covered with `StateRestorationTester`.
- [ ] Large font scale and large screens are covered with `DeviceConfigurationOverride`.
- [ ] Accessibility checks are enabled.

Files in this skill

  • SKILL.md9.7 KB
  • agents/openai.yaml127 B

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in development →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.