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

ComposeUiTestKt

public final class ComposeUiTestKt


Summary

Public methods

static final @NonNull AndroidComposeUiTestEnvironment<@NonNull A>
@ExperimentalTestApi
<A extends ComponentActivity> AndroidComposeUiTestEnvironment(
    @NonNull CoroutineContext effectContext,
    @NonNull Function0<A> activityProvider
)

Creates an AndroidComposeUiTestEnvironment that retrieves the host Activity by delegating to the given activityProvider.

static final void

Variant of runComposeUiTest that allows you to specify which Activity should be launched.

static final void
@ExperimentalTestApi
<A extends ComponentActivity> runAndroidComposeUiTest(
    @NonNull Class<@NonNull A> activityClass,
    @NonNull CoroutineContext effectContext,
    @ExtensionFunctionType @NonNull Function1<@NonNull AndroidComposeUiTest<@NonNull A>, Unit> block
)

Variant of runComposeUiTest that allows you to specify which Activity should be launched.

static final void

Sets up the test environment, runs the given test and then tears down the test environment.

static final void

Variant of runComposeUiTest that does not launch an Activity to host Compose content in and thus acts as an "empty shell".

static final void
@ExperimentalTestApi
waitUntilAtLeastOneExists(
    @NonNull ComposeUiTest receiver,
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until at least one node matches the given matcher.

static final void
@ExperimentalTestApi
waitUntilDoesNotExist(
    @NonNull ComposeUiTest receiver,
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until no nodes match the given matcher.

static final void
@ExperimentalTestApi
waitUntilExactlyOneExists(
    @NonNull ComposeUiTest receiver,
    @NonNull SemanticsMatcher matcher,
    long timeoutMillis
)

Blocks until exactly one node matches the given matcher.

static final void
@ExperimentalTestApi
waitUntilNodeCount(
    @NonNull ComposeUiTest receiver,
    @NonNull SemanticsMatcher matcher,
    int count,
    long timeoutMillis
)

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

Public methods

AndroidComposeUiTestEnvironment

@ExperimentalTestApi
public static final @NonNull AndroidComposeUiTestEnvironment<@NonNull A> <A extends ComponentActivity> AndroidComposeUiTestEnvironment(
    @NonNull CoroutineContext effectContext,
    @NonNull Function0<A> activityProvider
)

Creates an AndroidComposeUiTestEnvironment that retrieves the host Activity by delegating to the given activityProvider. Use this if you need to launch an Activity in a way that is not compatible with any of the existing runComposeUiTest, runAndroidComposeUiTest, or runEmptyComposeUiTest methods.

Valid use cases include, but are not limited to, creating your own JUnit test rule that implements AndroidComposeUiTest by delegating to AndroidComposeUiTestEnvironment.test. See AndroidComposeTestRule for a reference implementation.

The activityProvider is called every time activity is called, which in turn is called when setContent is called.

The most common implementation of an activityProvider retrieves the activity from a backing ActivityScenario (that the caller launches within the lambda passed to runTest), but one is not limited to this pattern.

Parameters
<A extends ComponentActivity>

The Activity type to be interacted with, which typically (but not necessarily) is the activity that was launched and hosts the Compose content.

@NonNull CoroutineContext effectContext

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

@NonNull Function0<A> activityProvider

A lambda that should return the current Activity instance of type A, if it is available. If it is not available, it should return null.

runAndroidComposeUiTest

@ExperimentalTestApi
public static final void <A extends ComponentActivity> runAndroidComposeUiTest(
    @NonNull CoroutineContext effectContext,
    @ExtensionFunctionType @NonNull Function1<@NonNull AndroidComposeUiTest<@NonNull A>, Unit> block
)

Variant of runComposeUiTest that allows you to specify which Activity should be launched. Be aware that if the Activity androidx.activity.compose.setContent during its launch, you cannot use setContent on the ComposeUiTest anymore as this would override the content and can lead to subtle bugs.

Parameters
<A extends ComponentActivity>

The Activity type to be launched, which typically (but not necessarily) hosts the Compose content

@NonNull CoroutineContext effectContext

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

@ExtensionFunctionType @NonNull Function1<@NonNull AndroidComposeUiTest<@NonNull A>, Unit> block

The test function.

runAndroidComposeUiTest

@ExperimentalTestApi
public static final void <A extends ComponentActivity> runAndroidComposeUiTest(
    @NonNull Class<@NonNull A> activityClass,
    @NonNull CoroutineContext effectContext,
    @ExtensionFunctionType @NonNull Function1<@NonNull AndroidComposeUiTest<@NonNull A>, Unit> block
)

Variant of runComposeUiTest that allows you to specify which Activity should be launched. Be aware that if the Activity androidx.activity.compose.setContent during its launch, you cannot use setContent on the ComposeUiTest anymore as this would override the content and can lead to subtle bugs.

Parameters
<A extends ComponentActivity>

The Activity type to be launched, which typically (but not necessarily) hosts the Compose content

@NonNull Class<@NonNull A> activityClass

The Class of the Activity type to be launched, corresponding to A.

@NonNull CoroutineContext effectContext

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

@ExtensionFunctionType @NonNull Function1<@NonNull AndroidComposeUiTest<@NonNull A>, Unit> block

The test function.

runComposeUiTest

@ExperimentalTestApi
public static final void runComposeUiTest(
    @NonNull CoroutineContext effectContext,
    @ExtensionFunctionType @NonNull Function1<@NonNull ComposeUiTestUnit> block
)

Sets up the test environment, runs the given test and then tears down the test environment. Use the methods on ComposeUiTest in the test to find Compose content and make assertions on it. If you need access to platform specific elements (such as the Activity on Android), use one of the platform specific variants of this method, e.g. runAndroidComposeUiTest on Android.

Implementations of this method will launch a Compose host (such as an Activity on Android) for you. If your test needs to launch its own host, use a platform specific variant that doesn't launch anything for you (if available), e.g. runEmptyComposeUiTest on Android. Always make sure that the Compose content is set during execution of the test lambda so the test framework is aware of the content. Whether you need to launch the host from within the test lambda as well depends on the platform.

Keeping a reference to the ComposeUiTest outside of this function is an error.

Parameters
@NonNull CoroutineContext effectContext

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

@ExtensionFunctionType @NonNull Function1<@NonNull ComposeUiTestUnit> block

The test function.

runEmptyComposeUiTest

@ExperimentalTestApi
public static final void runEmptyComposeUiTest(
    @ExtensionFunctionType @NonNull Function1<@NonNull ComposeUiTestUnit> block
)

Variant of runComposeUiTest that does not launch an Activity to host Compose content in and thus acts as an "empty shell". Use this if you need to have control over the timing and method of launching the Activity, for example when you want to launch it with a custom Intent, or if you have a complex test setup.

When using this method, calling ComposeUiTest.setContent will throw an IllegalStateException. Instead, you'll have to set the content in the Activity that you have launched yourself, either directly on the Activity or on an androidx.compose.ui.platform.AbstractComposeView. You will need to do this from within the test lambda, or the test framework will not be able to find the content.

waitUntilAtLeastOneExists

@ExperimentalTestApi
public static final void waitUntilAtLeastOneExists(
    @NonNull ComposeUiTest receiver,
    @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 static final void waitUntilDoesNotExist(
    @NonNull ComposeUiTest receiver,
    @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 static final void waitUntilExactlyOneExists(
    @NonNull ComposeUiTest receiver,
    @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 static final void waitUntilNodeCount(
    @NonNull ComposeUiTest receiver,
    @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