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

AndroidComposeTestRule

public final class AndroidComposeTestRule<R extends TestRule, A extends ComponentActivity> implements ComposeContentTestRule


Summary

Nested types

This class is deprecated. Do not instantiate this Statement, use AndroidComposeTestRule instead

Public constructors

<R extends TestRule, A extends ComponentActivity> AndroidComposeTestRule(
    @NonNull R activityRule,
    @NonNull Function1<@NonNull R, @NonNull A> activityProvider
)

Android specific implementation of ComposeContentTestRule, where compose content is hosted by an Activity.

@ExperimentalTestApi
<R extends TestRule, A extends ComponentActivity> AndroidComposeTestRule(
    @NonNull R activityRule,
    @NonNull CoroutineContext effectContext,
    @NonNull Function1<@NonNull R, @NonNull A> activityProvider
)

Android specific implementation of ComposeContentTestRule, where compose content is hosted by an Activity.

Public methods

@NonNull Statement
apply(@NonNull Statement base, @NonNull Description description)
void

Suspends until compose is idle.

final @NonNull A

Provides the current activity.

final @NonNull R
@NonNull Density

Current device screen's density.

@NonNull MainTestClock

Clock that drives frames and recompositions in compose tests.

@NonNull SemanticsNodeInteractionCollection
onAllNodes(@NonNull SemanticsMatcher matcher, boolean useUnmergedTree)

Finds all semantics nodes that match the given condition.

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

Finds a semantics node that matches the given condition.

void

Registers an IdlingResource in this test.

@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.

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

Runs the given action on the UI thread.

void
setContent(@Composable @NonNull Function0<Unit> composable)

Sets the given composable as a content of the current screen.

void

Unregisters an IdlingResource from this test.

void

Waits for compose to be idle.

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

Blocks until the given condition is satisfied.

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

Blocks until at least one node matches the given matcher.

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

Blocks until no nodes match the given matcher.

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

Blocks until exactly one node matches the given matcher.

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.

Public constructors

AndroidComposeTestRule

public <R extends TestRule, A extends ComponentActivity> AndroidComposeTestRule(
    @NonNull R activityRule,
    @NonNull Function1<@NonNull R, @NonNull A> activityProvider
)

Android specific implementation of ComposeContentTestRule, where compose content is hosted by an Activity.

The Activity is normally launched by the given activityRule before the test starts, but it is possible to pass a test rule that chooses to launch an Activity on a later time. The Activity is retrieved from the activityRule by means of the activityProvider, which can be thought of as a getter for the Activity on the activityRule. If you use an activityRule that launches an Activity on a later time, you should make sure that the Activity is launched by the time or while the activityProvider is called.

The AndroidComposeTestRule wraps around the given activityRule to make sure the Activity is launched after the AndroidComposeTestRule has completed all necessary steps to control and monitor the compose content.

Parameters
@NonNull R activityRule

Test rule to use to launch the Activity.

@NonNull Function1<@NonNull R, @NonNull A> activityProvider

Function to retrieve the Activity from the given activityRule.

AndroidComposeTestRule

@ExperimentalTestApi
public <R extends TestRule, A extends ComponentActivity> AndroidComposeTestRule(
    @NonNull R activityRule,
    @NonNull CoroutineContext effectContext,
    @NonNull Function1<@NonNull R, @NonNull A> activityProvider
)

Android specific implementation of ComposeContentTestRule, where compose content is hosted by an Activity.

The Activity is normally launched by the given activityRule before the test starts, but it is possible to pass a test rule that chooses to launch an Activity on a later time. The Activity is retrieved from the activityRule by means of the activityProvider, which can be thought of as a getter for the Activity on the activityRule. If you use an activityRule that launches an Activity on a later time, you should make sure that the Activity is launched by the time or while the activityProvider is called.

The AndroidComposeTestRule wraps around the given activityRule to make sure the Activity is launched after the AndroidComposeTestRule has completed all necessary steps to control and monitor the compose content.

Parameters
@NonNull R activityRule

Test rule to use to launch the Activity.

@NonNull CoroutineContext effectContext

The CoroutineContext used to run the composition. The context for LaunchedEffects and rememberCoroutineScope will be derived from this context.

@NonNull Function1<@NonNull R, @NonNull A> activityProvider

Function to retrieve the Activity from the given activityRule.

Public methods

apply

public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)

awaitIdle

public 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.

getActivity

public final @NonNullgetActivity()

Provides the current activity.

Avoid calling often as it can involve synchronization and can be slow.

getActivityRule

public final @NonNullgetActivityRule()

getDensity

public @NonNull Density getDensity()

Current device screen's density.

getMainClock

public @NonNull MainTestClock getMainClock()

Clock that drives frames and recompositions in compose tests.

onAllNodes

public @NonNull SemanticsNodeInteractionCollection onAllNodes(@NonNull SemanticsMatcher matcher, boolean useUnmergedTree)

Finds all semantics nodes that match the given condition.

If you are working with elements that are not supposed to occur multiple times use onNode instead.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
@NonNull SemanticsMatcher matcher

Matcher used for filtering.

boolean useUnmergedTree

Find within merged composables like Buttons.

See also
onNode

onNode

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

Finds a semantics node that matches the given condition.

Any subsequent operation on its result will expect exactly one element found (unless SemanticsNodeInteraction.assertDoesNotExist is used) and will throw AssertionError if none or more than one element is found.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
@NonNull SemanticsMatcher matcher

Matcher used for filtering

boolean useUnmergedTree

Find within merged composables like Buttons.

See also
onAllNodes

to work with multiple elements

registerIdlingResource

public void registerIdlingResource(@NonNull IdlingResource idlingResource)

Registers an IdlingResource in this test.

runOnIdle

public @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

public @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.

setContent

public void setContent(@Composable @NonNull Function0<Unit> composable)

Sets the given composable as a content of the current screen.

Use this in your tests to setup the UI content to be tested. This should be called exactly once per test.

Throws
kotlin.IllegalStateException

if called more than once per test.

unregisterIdlingResource

public void unregisterIdlingResource(@NonNull IdlingResource idlingResource)

Unregisters an IdlingResource from this test.

waitForIdle

public 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

public 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
public 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
public 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
public 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
public 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