AndroidComposeTestRule


Summary

Nested types

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

Public constructors

<R : TestRule, A : ComponentActivity> AndroidComposeTestRule(
    activityRule: R,
    activityProvider: (R) -> A
)

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

android
@ExperimentalTestApi
<R : TestRule, A : ComponentActivity> AndroidComposeTestRule(
    activityRule: R,
    effectContext: CoroutineContext,
    activityProvider: (R) -> A
)

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

android

Public functions

open Statement
apply(base: Statement, description: Description)
android
open suspend Unit

Suspends until compose is idle.

android
Unit
android
open SemanticsNodeInteractionCollection
onAllNodes(matcher: SemanticsMatcher, useUnmergedTree: Boolean)

Finds all semantics nodes that match the given condition.

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

Finds a semantics node that matches the given condition.

android
open Unit

Registers an IdlingResource in this test.

android
open 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
open T
<T : Any?> runOnUiThread(action: () -> T)

Runs the given action on the UI thread.

android
open Unit
setContent(composable: @Composable () -> Unit)

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

android
open Unit

Unregisters an IdlingResource from this test.

android
open Unit

Waits for compose to be idle.

android
open 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
open Unit

Blocks until at least one node matches the given matcher.

android
open Unit

Blocks until no nodes match the given matcher.

android
open Unit

Blocks until exactly one node matches the given matcher.

android
open 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

A

Provides the current activity.

android
R
android
open Density

Current device screen's density.

android
open MainTestClock

Clock that drives frames and recompositions in compose tests.

android

Public constructors

AndroidComposeTestRule

<R : TestRule, A : ComponentActivity> AndroidComposeTestRule(
    activityRule: R,
    activityProvider: (R) -> A
)

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
activityRule: R

Test rule to use to launch the Activity.

activityProvider: (R) -> A

Function to retrieve the Activity from the given activityRule.

AndroidComposeTestRule

@ExperimentalTestApi
<R : TestRule, A : ComponentActivity> AndroidComposeTestRule(
    activityRule: R,
    effectContext: CoroutineContext = EmptyCoroutineContext,
    activityProvider: (R) -> A
)

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
activityRule: R

Test rule to use to launch the Activity.

effectContext: CoroutineContext = EmptyCoroutineContext

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

activityProvider: (R) -> A

Function to retrieve the Activity from the given activityRule.

Public functions

apply

open fun apply(base: Statement, description: Description): Statement

awaitIdle

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

cancelAndRecreateRecomposer

fun cancelAndRecreateRecomposer(): Unit

onAllNodes

open fun onAllNodes(matcher: SemanticsMatcher, useUnmergedTree: Boolean): SemanticsNodeInteractionCollection

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
matcher: SemanticsMatcher

Matcher used for filtering.

useUnmergedTree: Boolean

Find within merged composables like Buttons.

See also
onNode

onNode

open fun onNode(matcher: SemanticsMatcher, useUnmergedTree: Boolean): SemanticsNodeInteraction

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
matcher: SemanticsMatcher

Matcher used for filtering

useUnmergedTree: Boolean

Find within merged composables like Buttons.

See also
onAllNodes

to work with multiple elements

registerIdlingResource

open fun registerIdlingResource(idlingResource: IdlingResource): Unit

Registers an IdlingResource in this test.

runOnIdle

open 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

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

Runs the given action on the UI thread.

This method is blocking until the action is complete.

setContent

open fun setContent(composable: @Composable () -> Unit): Unit

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

open fun unregisterIdlingResource(idlingResource: IdlingResource): Unit

Unregisters an IdlingResource from this test.

waitForIdle

open 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

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

activity

val activity: A

Provides the current activity.

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

activityRule

val activityRule: R

density

open val densityDensity

Current device screen's density.

mainClock

open val mainClockMainTestClock

Clock that drives frames and recompositions in compose tests.