{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

ComposeTestRule

public interface ComposeTestRule extends TestRule, SemanticsNodeInteractionsProvider

Known direct subclasses
ComposeContentTestRule

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

Known indirect subclasses

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 methods

abstract void

Suspends until compose is idle.

abstract @NonNull Density

Current device screen's density.

abstract @NonNull MainTestClock

Clock that drives frames and recompositions in compose tests.

abstract void

Registers an IdlingResource in this test.

abstract @NonNull T
<T extends Object> runOnIdle(@NonNull Function0<@NonNull T> action)

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

abstract @NonNull T
<T extends Object> runOnUiThread(@NonNull Function0<@NonNull T> action)

Runs the given action on the UI thread.

abstract void

Unregisters an IdlingResource from this test.

abstract void

Waits for compose to be idle.

abstract void
waitUntil(
    long timeoutMillis,
    @NonNull Function0<@NonNull Boolean> condition
)

Blocks until the given condition is satisfied.

abstract void
@ExperimentalTestApi
waitUntilAtLeastOneExists(
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until at least one node matches the given matcher.

abstract void
@ExperimentalTestApi
waitUntilDoesNotExist(
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until no nodes match the given matcher.

abstract void
@ExperimentalTestApi
waitUntilExactlyOneExists(
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until exactly one node matches the given matcher.

abstract void
@ExperimentalTestApi
waitUntilNodeCount(
    @NonNull SemanticsMatcher matcher,
    int count,
    long timeoutMillis
)

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

Inherited methods

From androidx.compose.ui.test.SemanticsNodeInteractionsProvider
abstract @NonNull SemanticsNodeInteractionCollection
onAllNodes(@NonNull SemanticsMatcher matcher, boolean useUnmergedTree)

Finds all semantics nodes that match the given condition.

abstract @NonNull SemanticsNodeInteraction
onNode(@NonNull SemanticsMatcher matcher, boolean useUnmergedTree)

Finds a semantics node that matches the given condition.

From org.junit.rules.TestRule

Public methods

awaitIdle

abstract void awaitIdle()

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.

getDensity

abstract @NonNull Density getDensity()

Current device screen's density.

getMainClock

abstract @NonNull MainTestClock getMainClock()

Clock that drives frames and recompositions in compose tests.

registerIdlingResource

abstract void registerIdlingResource(@NonNull IdlingResource idlingResource)

Registers an IdlingResource in this test.

runOnIdle

abstract @NonNull T <T extends Object> runOnIdle(@NonNull Function0<@NonNull T> action)

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

abstract @NonNull T <T extends Object> runOnUiThread(@NonNull Function0<@NonNull T> action)

Runs the given action on the UI thread.

This method is blocking until the action is complete.

unregisterIdlingResource

abstract void unregisterIdlingResource(@NonNull IdlingResource idlingResource)

Unregisters an IdlingResource from this test.

waitForIdle

abstract void waitForIdle()

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

abstract void waitUntil(
    long timeoutMillis,
    @NonNull Function0<@NonNull Boolean> condition
)

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
long timeoutMillis

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.

@NonNull Function0<@NonNull Boolean> condition

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
abstract void waitUntilAtLeastOneExists(
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until at least one node matches the given matcher.

Parameters
@NonNull SemanticsMatcher matcher

The matcher that will be used to filter nodes.

long timeoutMillis

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
abstract void waitUntilDoesNotExist(
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until no nodes match the given matcher.

Parameters
@NonNull SemanticsMatcher matcher

The matcher that will be used to filter nodes.

long timeoutMillis

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
abstract void waitUntilExactlyOneExists(
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until exactly one node matches the given matcher.

Parameters
@NonNull SemanticsMatcher matcher

The matcher that will be used to filter nodes.

long timeoutMillis

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
abstract void waitUntilNodeCount(
    @NonNull SemanticsMatcher matcher,
    int count,
    long timeoutMillis
)

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

Parameters
@NonNull SemanticsMatcher matcher

The matcher that will be used to filter nodes.

int count

The number of nodes that are expected to

long timeoutMillis

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