ComposeTestRule

Known direct subclasses
ComposeContentTestRule

A ComposeTestRule that allows you to set content without the necessity to provide a host for the content.


A TestRule that allows you to test and control composables and applications using Compose. Most of the functionality in this interface provides some form of test synchronization: the test will block until the app or composable is idle, to ensure the tests are deterministic.

For example, if you would perform a click on the center of the screen while a button is animation from left to right over the screen, without synchronization the test would sometimes click when the button is in the middle of the screen (button is clicked), and sometimes when the button is past the middle of the screen (button is not clicked). With synchronization, the app would not be idle until the animation is over, so the test will always click when the button is past the middle of the screen (and not click it). If you actually do want to click the button when it's in the middle of the animation, you can do so by controlling the clock. You'll have to disable automatic advancing, and manually advance the clock by the time necessary to position the button in the middle of the screen.

An instance of ComposeTestRule can be created with createComposeRule, which will also create a host for the compose content for you (see ComposeContentTestRule). If you need to specify which particular Activity is started on Android, you can use createAndroidComposeRule.

If you don't want any Activity to be started automatically by the test rule on Android, you can use createEmptyComposeRule. In such a case, you will have to set content using one of Compose UI's setters (like ComponentActivity.setContent).

Summary

Public functions

suspend Unit

Suspends until compose is idle.

android
Unit

Registers an IdlingResource in this test.

android
T
<T : Any?> runOnIdle(action: () -> T)

Executes the given action in the same way as runOnUiThread but also makes sure Compose is idle before executing it.

android
T
<T : Any?> runOnUiThread(action: () -> T)

Runs the given action on the UI thread.

android
Unit

Unregisters an IdlingResource from this test.

android
Unit

Waits for compose to be idle.

android
Unit
waitUntil(timeoutMillis: Long, condition: () -> Boolean)

Blocks until the given condition is satisfied.

android
open Unit
waitUntil(
    conditionDescription: String,
    timeoutMillis: Long,
    condition: () -> Boolean
)

Blocks until the given condition is satisfied.

android
Unit

Blocks until at least one node matches the given matcher.

android
Unit

Blocks until no nodes match the given matcher.

android
Unit

Blocks until exactly one node matches the given matcher.

android
Unit
@ExperimentalTestApi
waitUntilNodeCount(
    matcher: SemanticsMatcher,
    count: Int,
    timeoutMillis: Long
)

Blocks until the number of nodes matching the given matcher is equal to the given count.

android

Public properties

Density

Current device screen's density.

android
MainTestClock

Clock that drives frames and recompositions in compose tests.

android

Inherited functions

From androidx.compose.ui.test.SemanticsNodeInteractionsProvider
SemanticsNodeInteractionCollection
onAllNodes(matcher: SemanticsMatcher, useUnmergedTree: Boolean)

Finds all semantics nodes that match the given condition.

android
SemanticsNodeInteraction
onNode(matcher: SemanticsMatcher, useUnmergedTree: Boolean)

Finds a semantics node that matches the given condition.

android
From org.junit.rules.TestRule
Statement
android

Public functions

awaitIdle

suspend fun awaitIdle(): Unit

Suspends until compose is idle. Compose is idle if there are no pending compositions, no pending changes that could lead to another composition, and no pending draw calls.

In case the main clock auto advancement is enabled (by default is) this will also keep advancing the clock until it is idle (meaning there are no recompositions, animations, etc. pending). If not, this will wait only for other idling resources.

registerIdlingResource

fun registerIdlingResource(idlingResource: IdlingResource): Unit

Registers an IdlingResource in this test.

runOnIdle

fun <T : Any?> runOnIdle(action: () -> T): T

Executes the given action in the same way as runOnUiThread but also makes sure Compose is idle before executing it. This is great place for doing your assertions on shared variables.

This method is blocking until the action is complete.

In case the main clock auto advancement is enabled (by default is) this will also keep advancing the clock until it is idle (meaning there are no recompositions, animations, etc. pending). If not, this will wait only for other idling resources.

runOnUiThread

fun <T : Any?> runOnUiThread(action: () -> T): T

Runs the given action on the UI thread.

This method is blocking until the action is complete.

unregisterIdlingResource

fun unregisterIdlingResource(idlingResource: IdlingResource): Unit

Unregisters an IdlingResource from this test.

waitForIdle

fun waitForIdle(): Unit

Waits for compose to be idle.

This is a blocking call. Returns only after compose is idle.

In case the main clock auto advancement is enabled (by default is) this will also keep advancing the clock until it is idle (meaning there are no recompositions, animations, etc. pending). If not, this will wait only for other idling resources.

Can crash in case there is a time out. This is not supposed to be handled as it surfaces only in incorrect tests.

waitUntil

fun waitUntil(timeoutMillis: Long, condition: () -> Boolean): Unit

Blocks until the given condition is satisfied.

In case the main clock auto advancement is enabled (by default is), this will also keep advancing the clock on a frame by frame basis and yield for other async work at the end of each frame. If the advancement of the main clock is not enabled this will work as a countdown latch without any other advancements.

There is also MainTestClock.advanceTimeUntil which is faster as it does not yield back the UI thread.

This method should be used in cases where MainTestClock.advanceTimeUntil is not enough.

Parameters
timeoutMillis: Long

The time after which this method throws an exception if the given condition is not satisfied. This is the wall clock time not the main clock one.

condition: () -> Boolean

Condition that must be satisfied in order for this method to successfully finish.

Throws
androidx.compose.ui.test.ComposeTimeoutException

If the condition is not satisfied after timeoutMillis.

waitUntil

open fun waitUntil(
    conditionDescription: String,
    timeoutMillis: Long,
    condition: () -> Boolean
): Unit

Blocks until the given condition is satisfied.

In case the main clock auto advancement is enabled (by default is), this will also keep advancing the clock on a frame by frame basis and yield for other async work at the end of each frame. If the advancement of the main clock is not enabled this will work as a countdown latch without any other advancements.

There is also MainTestClock.advanceTimeUntil which is faster as it does not yield back the UI thread.

This method should be used in cases where MainTestClock.advanceTimeUntil is not enough.

Parameters
conditionDescription: String

A human-readable description of condition that will be included in the timeout exception if thrown.

timeoutMillis: Long

The time after which this method throws an exception if the given condition is not satisfied. This is the wall clock time not the main clock one.

condition: () -> Boolean

Condition that must be satisfied in order for this method to successfully finish.

Throws
androidx.compose.ui.test.ComposeTimeoutException

If the condition is not satisfied after timeoutMillis.

waitUntilAtLeastOneExists

@ExperimentalTestApi
fun waitUntilAtLeastOneExists(matcher: SemanticsMatcher, timeoutMillis: Long): Unit

Blocks until at least one node matches the given matcher.

Parameters
matcher: SemanticsMatcher

The matcher that will be used to filter nodes.

timeoutMillis: Long

The time after which this method throws an exception if no nodes match the given matcher. This observes wall clock time, not frame time.

Throws
androidx.compose.ui.test.ComposeTimeoutException

If no nodes match the given matcher after timeoutMillis (in wall clock time).

See also
waitUntil

waitUntilDoesNotExist

@ExperimentalTestApi
fun waitUntilDoesNotExist(matcher: SemanticsMatcher, timeoutMillis: Long): Unit

Blocks until no nodes match the given matcher.

Parameters
matcher: SemanticsMatcher

The matcher that will be used to filter nodes.

timeoutMillis: Long

The time after which this method throws an exception if any nodes match the given matcher. This observes wall clock time, not frame time.

Throws
androidx.compose.ui.test.ComposeTimeoutException

If any nodes match the given matcher after timeoutMillis (in wall clock time).

See also
waitUntil

waitUntilExactlyOneExists

@ExperimentalTestApi
fun waitUntilExactlyOneExists(matcher: SemanticsMatcher, timeoutMillis: Long): Unit

Blocks until exactly one node matches the given matcher.

Parameters
matcher: SemanticsMatcher

The matcher that will be used to filter nodes.

timeoutMillis: Long

The time after which this method throws an exception if exactly one node does not match the given matcher. This observes wall clock time, not frame time.

Throws
androidx.compose.ui.test.ComposeTimeoutException

If exactly one node does not match the given matcher after timeoutMillis (in wall clock time).

See also
waitUntil

waitUntilNodeCount

@ExperimentalTestApi
fun waitUntilNodeCount(
    matcher: SemanticsMatcher,
    count: Int,
    timeoutMillis: Long
): Unit

Blocks until the number of nodes matching the given matcher is equal to the given count.

Parameters
matcher: SemanticsMatcher

The matcher that will be used to filter nodes.

count: Int

The number of nodes that are expected to

timeoutMillis: Long

The time after which this method throws an exception if the number of nodes that match the matcher is not count. This observes wall clock time, not frame time.

Throws
androidx.compose.ui.test.ComposeTimeoutException

If the number of nodes that match the matcher is not count after timeoutMillis (in wall clock time).

See also
waitUntil

Public properties

density

val densityDensity

Current device screen's density.

mainClock

val mainClockMainTestClock

Clock that drives frames and recompositions in compose tests.