androidx.ui.test

Classes

AnimationClockTestRule

A TestRule to monitor and take over the animation clock in the composition.

BaseGestureScope

CollectedSizes

Small utility class to provide convenient assertion for width and height for some Size.

DisableTransitions

This rule will disable all Transition animations for the test.

GestureScope

The receiver scope for injecting gestures on the semanticsNode identified by the corresponding SemanticsNodeInteraction.

PartialGestureScope

The receiver scope for injecting partial gestures on the semanticsNode identified by the corresponding SemanticsNodeInteraction.

SelectionResult

Result of SemanticsSelector projection.

SemanticsMatcher

Wrapper for semantics matcher lambdas that allows to build string explaining to the developer what conditions were being tested.

SemanticsNodeInteraction

Represents a semantics node and the path to fetch it from the semantics tree.

SemanticsNodeInteractionCollection

Represents a collection of semantics nodes and the path to fetch them from the semantics tree.

SemanticsSelector

Projects the given set of nodes to a new set of nodes.

StateRestorationTester

Helps to test the state restoration for your Composable component.

Annotations

ExperimentalTesting

Top-level functions summary

ComposeTestRule
createComposeRule(recomposer: Recomposer? = null, disableTransitions: Boolean = false, disableBlinkingCursor: Boolean = true)

Factory method to provide implementation of ComposeTestRule.

SemanticsNodeInteraction

Finds a component that matches the given condition.

SemanticsNodeInteractionCollection

Finds all components that match the given condition.

SemanticsNodeInteractionCollection
findAllByLabel(label: String, ignoreCase: Boolean = false)

Finds all components with the given label as AccessibilityLabel.

SemanticsNodeInteractionCollection
findAllByTag(testTag: String)

Finds all components identified by the given tag.

SemanticsNodeInteractionCollection
findAllByText(text: String, ignoreCase: Boolean = false)

Finds all components with the given text.

SemanticsNodeInteraction
findByLabel(label: String, ignoreCase: Boolean = false)

Finds a component with the given label as its accessibilityLabel.

SemanticsNodeInteraction
findBySubstring(text: String, ignoreCase: Boolean = false)

Finds a component with text that contains the given substring.

SemanticsNodeInteraction
findByTag(testTag: String)

Finds a component identified by the given tag.

SemanticsNodeInteraction
findByText(text: String, ignoreCase: Boolean = false)

Finds a component with the given text.

SemanticsNodeInteraction

Finds the root semantics node of the Compose tree.

SemanticsMatcher

Returns whether the component has at least one ancestor that satisfies the given matcher.

SemanticsMatcher

Returns whether the component has at least one child that satisfies the given matcher.

SemanticsMatcher

Returns whether the component has at least one descendant that satisfies the given matcher.

SemanticsMatcher

Returns whether the component has at least one sibling that satisfies the given matcher.

SemanticsMatcher

Return whether the component has a semantics click action defined.

SemanticsMatcher
hasImeAction(actionType: ImeAction)

Returns whether the component defines the given IME action.

SemanticsMatcher

Return whether the component supports input methods.

SemanticsMatcher
hasLabel(label: String, ignoreCase: Boolean = false)

Returns whether the component's label matches exactly to the given text.

SemanticsMatcher

Return whether the component has no semantics click action defined.

SemanticsMatcher

Return whether the component has no semantics scrollable action defined.

SemanticsMatcher

Returns whether the component's parent satisfies the given matcher.

SemanticsMatcher

Returns whether the component's range info matches exactly to the given accessibility range info.

SemanticsMatcher

Return whether the component has a semantics scrollable action defined.

SemanticsMatcher
hasSubstring(substring: String, ignoreCase: Boolean = false)

Returns whether the component's text contains the given substring.

SemanticsMatcher
hasTestTag(testTag: String)

Returns whether the component is annotated by the given test tag.

SemanticsMatcher
hasText(text: String, ignoreCase: Boolean = false)

Returns whether the component's text matches exactly to the given text.

SemanticsMatcher
hasValue(value: String)

Returns whether the component's value matches exactly to the given accessibility value.

SemanticsMatcher

Returns whether the component is a dialog.

SemanticsMatcher

Returns whether the component is enabled.

SemanticsMatcher

Returns whether the component is hidden.

SemanticsMatcher

Verifies that the component is in a mutually exclusive group - that is, that FoundationSemanticsProperties.InMutuallyExclusiveGroup is set to true

SemanticsMatcher

Returns whether the component is not enabled.

SemanticsMatcher

Returns whether the component is not hidden.

SemanticsMatcher

Returns whether the component is not toggled.

SemanticsMatcher

Returns whether the component is toggled.

SemanticsMatcher

Returns whether the component is a popup.

SemanticsMatcher

SemanticsMatcher

Return whether the component is selectable.

SemanticsMatcher

Returns whether the component is selected.

SemanticsMatcher

Return whether the component is checkable.

SemanticsMatcher

Returns whether the component is not selected.

T
runOnIdleCompose(action: () -> T)

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

T
runOnUiThread(action: () -> T)

Runs the given action on the UI thread.

Unit

Waits for compose to be idle.

Top-level properties summary

DpConstraints

Constant to emulate very big but finite constraints

Extension functions summary

For android.graphics.Bitmap
Unit
Bitmap.assertPixelColor(expected: Color, x: Int, y: Int, error: (Color) -> String = { color -> "Pixel($x, $y) expected to be $expected, but was $color" })

Asserts that the color at a specific pixel in the bitmap at (x, y) is expected.

Unit
Bitmap.assertPixels(expectedSize: IntSize? = null, expectedColorProvider: (pos: IntOffset) -> Color?)

A helper function to run asserts on Bitmap.

Unit
Bitmap.assertShape(density: Density, shape: Shape, shapeColor: Color, backgroundColor: Color, backgroundShape: Shape = RectangleShape, sizeX: Float = width.toFloat(), sizeY: Float = height.toFloat(), shapeSizeX: Float = sizeX, shapeSizeY: Float = sizeY, centerX: Float = width / 2f, centerY: Float = height / 2f, shapeOverlapPixelCount: Float = 1.0f)

Asserts that the given shape is drawn within the bitmap with the size the dimensions shapeSizeX x shapeSizeY, centered at (centerX, centerY) with the color shapeColor.

Unit
Bitmap.assertShape(density: Density, horizontalPadding: Dp, verticalPadding: Dp, backgroundColor: Color, shapeColor: Color, shape: Shape = RectangleShape, shapeOverlapPixelCount: Float = 1.0f)

Asserts that the bitmap is fully occupied by the given shape with the color shapeColor without horizontalPadding and verticalPadding from the sides.

For android.view.View
Bitmap

Captures the underlying view's surface into bitmap.

For SemanticsNodeInteraction
SemanticsNodeInteractionCollection

Returns all the ancestors of this node.

SemanticsNodeInteraction
SemanticsNodeInteraction.assert(matcher: SemanticsMatcher, messagePrefixOnError: () -> String = null)

Asserts that the provided matcher is satisfied for this node.

SemanticsNodeInteraction

Asserts that the current component has a click action.

SemanticsNodeInteraction

Asserts that the current component doesn't have a click action.

SemanticsNodeInteraction

Asserts that the current component is displayed on screen.

SemanticsNodeInteraction

Asserts that the current component is enabled.

SemanticsNodeInteraction

Asserts that the current component has hidden property set to true.

SemanticsNodeInteraction

Asserts the component is in a mutually exclusive group.

SemanticsNodeInteraction

Asserts that the current component is not displayed on screen.

SemanticsNodeInteraction

Asserts that the current component is not enabled.

SemanticsNodeInteraction

Asserts that the current component has hidden property set to false.

SemanticsNodeInteraction

Asserts that the current component is unchecked.

SemanticsNodeInteraction

Asserts that the current component is checked.

SemanticsNodeInteraction

Asserts that the current component is selectable.

SemanticsNodeInteraction

Asserts that the current component is selected.

SemanticsNodeInteraction

Asserts that the current component is toggleable.

SemanticsNodeInteraction

Asserts that the current component is unselected.

SemanticsNodeInteraction

Asserts the component's label equals the given String.

SemanticsNodeInteraction

Asserts the component's range info equals the given value.

SemanticsNodeInteraction

Asserts the component's text equals the given String.

SemanticsNodeInteraction

Asserts the component's value equals the given value.

Unit

Provides support to call custom semantics actions on this node.

Unit

Provides support to call custom semantics actions on this node.

Bitmap

Captures the underlying component's surface into bitmap.

SemanticsNodeInteraction

Returns exactly one child of this node.

SemanticsNodeInteraction

Returns child of this node at the given index.

SemanticsNodeInteractionCollection

Returns children of this node.

Unit
SemanticsNodeInteraction.doClearText(alreadyHasFocus: Boolean = false)

Clears the text in this node in similar way to IME.

SemanticsNodeInteraction

Performs a click action on the given component.

SemanticsNodeInteraction

Executes the gestures specified in the given block.

SemanticsNodeInteraction

Executes the (partial) gesture specified in the given block.

Unit
SemanticsNodeInteraction.doReplaceText(text: String, alreadyHasFocus: Boolean = false)

Replaces existing text with the given text in this node in similar way to IME.

SemanticsNodeInteraction

Scrolls to a component using SemanticsActions.

Unit
SemanticsNodeInteraction.doSendImeAction(alreadyHasFocus: Boolean = false)

Sends to this node the IME action associated with it in similar way to IME.

Boolean

Send the specified KeyEvent to the focused component.

Unit
SemanticsNodeInteraction.doSendText(text: String, alreadyHasFocus: Boolean = false)

Sends the given text to this node in similar way to IME.

String

Dumps all the semantics nodes information it holds into string.

SemanticsNodeInteraction

Returns a parent of this node.

SemanticsNodeInteraction

Returns exactly one sibling of this node.

SemanticsNodeInteractionCollection

Returns all siblings of this node.

For SemanticsNodeInteractionCollection
SemanticsNodeInteractionCollection

Asserts that all the nodes in this collection satisfy the given matcher.

SemanticsNodeInteractionCollection

Asserts that this collection contains at least one element that satisfies the given matcher.

SemanticsNodeInteractionCollection

Asserts that this collection of nodes is equal to the given expectedSize.

String

Dumps all the semantics nodes information it holds into string.

SemanticsNodeInteractionCollection

Returns all the nodes matching the given matcher.

SemanticsNodeInteraction

Expects to return exactly one node matching the given matcher.

SemanticsNodeInteraction

Returns the first node in this collection.

SemanticsNodeInteraction

Returns the last node in this collection.

For ComposeExecutionControl
Unit

Performs recomposition and asserts that there were some pending changes.

Unit

Asserts that last recomposition had some changes.

Unit

Asserts that last recomposition had no some changes.

Unit

Assert that the underlying view under test has a positive size.

Unit

Performs recomposition and asserts that there were some pending changes.

Unit

Performs the given amount of frames and asserts that there are no changes pending afterwards.

Int

Runs frames until there are no changes pending.

Unit

Performs recomposition and asserts that there were some pending changes.

For Path
Boolean
Path.contains(offset: Offset)

Tests to see if the given point is within the path.

For BaseGestureScope
Offset

Transforms the position to global coordinates, as defined by globalBounds

Offset
BaseGestureScope.percentOffset(@FloatRange(-1.0, 1.0) x: Float = 0f, @FloatRange(-1.0, 1.0) y: Float = 0f)

Creates an Offset relative to the size of the component we're interacting with.

For PartialGestureScope
Unit

Moves the position of the pointer with the given pointerId by the given delta, but does not send a move event.

Unit
PartialGestureScope.movePointerTo(pointerId: Int, position: Offset)

Updates the position of the pointer with the given pointerId to the given position, but does not send a move event.

Unit

Sends a cancel event to cancel the current partial gesture.

Unit
PartialGestureScope.sendDown(pointerId: Int, position: Offset)

Sends a down event for the pointer with the given pointerId at position on the associated component.

Unit

Sends a down event for the default pointer at position on the associated component.

Unit

Sends a move event without updating any of the pointer positions.

Unit

Sends a move event on the associated component, with the position of the pointer with the given pointerId moved by the given delta.

Unit

Sends a move event on the associated component, with the position of the default pointer moved by the given delta.

Unit
PartialGestureScope.sendMoveTo(pointerId: Int, position: Offset)

Sends a move event on the associated component, with the position of the pointer with the given pointerId updated to position.

Unit

Sends a move event on the associated component, with the position of the default pointer updated to position.

Unit
PartialGestureScope.sendUp(pointerId: Int = 0)

Sends an up event for the pointer with the given pointerId, or the default pointer if pointerId is omitted, on the associated component.

For GestureScope
Unit
GestureScope.sendClick(position: Offset = center)

Performs a click gesture at the given position on the associated component, or in the center if the position is omitted.

Unit
GestureScope.sendDoubleClick(position: Offset = center, delay: Duration = doubleClickDelay)

Performs a double click gesture at the given position on the associated component, or in the center if the position is omitted.

Unit
GestureScope.sendLongClick(position: Offset = center, duration: Duration = LongPressTimeout + 100.milliseconds)

Performs a long click gesture at the given position on the associated component, or in the center if the position is omitted.

Unit
GestureScope.sendPinch(start0: Offset, end0: Offset, start1: Offset, end1: Offset, duration: Duration = 400.milliseconds)

Performs a pinch gesture on the associated component.

Unit
GestureScope.sendSwipe(start: Offset, end: Offset, duration: Duration = 200.milliseconds)

Performs the swipe gesture on the associated component.

Unit

Performs a swipe down gesture on the associated component.

Unit

Performs a swipe left gesture on the associated component.

Unit

Performs a swipe right gesture on the associated component.

Unit

Performs a swipe up gesture on the associated component.

Unit
GestureScope.sendSwipeWithVelocity(start: Offset, end: Offset, @FloatRange(0.0) endVelocity: Float, duration: Duration = 200.milliseconds)

Performs the swipe gesture on the associated component, such that the velocity when the gesture is finished is roughly equal to endVelocity.

For ComposeTestRule
CollectedSizes
ComposeTestRule.setContentAndCollectSizes(parentConstraints: DpConstraints = BigTestConstraints, children: () -> Unit)

Set content as with ComposeTestRule.setContent, but return CollectedSizes to assert width and height of this content

Size
ComposeTestRule.setContentAndGetPixelSize(parentConstraints: DpConstraints = BigTestConstraints, performSetContent: (() -> Unit) -> Unit = { setContent(it) }, children: () -> Unit)

Set content as with ComposeTestRule.setContent, but return sizes of this content

For ComposeBenchmarkScope
Unit

Sets up the content.

Extension properties summary

For BaseGestureScope
Float

Returns the y-coordinate for the bottom of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the center of the bottom edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the bottom left corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the bottom right corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the center of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the center of the left edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the center of the right edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Float

Returns the x-coordinate for the center of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Float

Returns the y-coordinate for the center of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

PxBounds

Returns the global bounds of the component we're interacting with

Int

Shorthand for size.height

Float

Returns the x-coordinate for the left edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Float

Returns the x-coordinate for the right edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

IntSize

Returns the size of the component we're interacting with

Float

Returns the y-coordinate for the bottom of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the center of the top edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the top left corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Offset

Returns the top right corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Int

Shorthand for size.width

Top-level functions

createComposeRule

fun createComposeRule(
    recomposer: Recomposer? = null,
    disableTransitions: Boolean = false,
    disableBlinkingCursor: Boolean = true
): ComposeTestRule

Factory method to provide implementation of ComposeTestRule.

This method is useful for tests in compose libraries where no custom Activity is usually needed. For app tests or launching custom activities, see AndroidComposeTestRule.

For Android this will use the default Activity (android.app.Activity). You need to add a reference to this activity into the manifest file of the corresponding tests (usually in androidTest/AndroidManifest.xml).

find

fun find(matcher: SemanticsMatcher): SemanticsNodeInteraction

Finds a component 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 see SemanticsNodeInteraction

See Also

findAll

fun findAll(matcher: SemanticsMatcher): SemanticsNodeInteractionCollection

Finds all components that match the given condition.

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

See Also

findAllByLabel

fun findAllByLabel(
    label: String,
    ignoreCase: Boolean = false
): SemanticsNodeInteractionCollection

Finds all components with the given label as AccessibilityLabel.

For usage patterns see SemanticsNodeInteraction

findAllByTag

fun findAllByTag(testTag: String): SemanticsNodeInteractionCollection

Finds all components identified by the given tag.

For usage patterns see SemanticsNodeInteraction

findAllByText

fun findAllByText(
    text: String,
    ignoreCase: Boolean = false
): SemanticsNodeInteractionCollection

Finds all components with the given text.

For usage patterns see SemanticsNodeInteraction

findByLabel

fun findByLabel(
    label: String,
    ignoreCase: Boolean = false
): SemanticsNodeInteraction

Finds a component with the given label as its accessibilityLabel.

For usage patterns see SemanticsNodeInteraction

See Also

findBySubstring

fun findBySubstring(
    text: String,
    ignoreCase: Boolean = false
): SemanticsNodeInteraction

Finds a component with text that contains the given substring.

For usage patterns see SemanticsNodeInteraction

See Also

findByTag

fun findByTag(testTag: String): SemanticsNodeInteraction

Finds a component identified by the given tag.

For usage patterns see SemanticsNodeInteraction

See Also

findByText

fun findByText(
    text: String,
    ignoreCase: Boolean = false
): SemanticsNodeInteraction

Finds a component with the given text.

For usage patterns see SemanticsNodeInteraction

findRoot

fun findRoot(): SemanticsNodeInteraction

Finds the root semantics node of the Compose tree. Useful for example for screenshot tests of the entire scene.

For usage patterns see SemanticsNodeInteraction

hasAnyAncestorThat

fun hasAnyAncestorThat(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the component has at least one ancestor that satisfies the given matcher.

Example: For the following tree |-X |-A |-B |-C1 |-C2 In case of C1, we would check the matcher against A and B

hasAnyChildThat

fun hasAnyChildThat(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the component has at least one child that satisfies the given matcher.

hasAnyDescendantThat

fun hasAnyDescendantThat(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the component has at least one descendant that satisfies the given matcher.

Example: For the following tree |-X |-A |-B |-C1 |-C2 In case of A, we would check the matcher against B,C1 and C2

hasAnySiblingThat

fun hasAnySiblingThat(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the component has at least one sibling that satisfies the given matcher.

Sibling is defined as a any other node that shares the same parent.

hasClickAction

fun hasClickAction(): SemanticsMatcher

Return whether the component has a semantics click action defined.

hasImeAction

fun hasImeAction(actionType: ImeAction): SemanticsMatcher

Returns whether the component defines the given IME action.

Parameters
actionType: ImeAction the action to match.

hasInputMethodsSupport

fun hasInputMethodsSupport(): SemanticsMatcher

Return whether the component supports input methods.

Supporting input methods means that the component provides a connection to IME (keyboard) and is able to accept input from it. This is however not enforced and relies on the components to properly add this to semantics when they provide input. Note that this is not related to gestures input but only to IME. This can be used to for instance filter out all text fields.

hasLabel

fun hasLabel(
    label: String,
    ignoreCase: Boolean = false
): SemanticsMatcher

Returns whether the component's label matches exactly to the given text.

Parameters
label: String Text to match.
ignoreCase: Boolean = false Whether case should be ignored.

hasNoClickAction

fun hasNoClickAction(): SemanticsMatcher

Return whether the component has no semantics click action defined.

hasNoScrollAction

fun hasNoScrollAction(): SemanticsMatcher

Return whether the component has no semantics scrollable action defined.

hasParentThat

fun hasParentThat(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the component's parent satisfies the given matcher.

Returns false if no parent exists.

hasRangeInfo

fun hasRangeInfo(rangeInfo: AccessibilityRangeInfo): SemanticsMatcher

Returns whether the component's range info matches exactly to the given accessibility range info.

Parameters
rangeInfo: AccessibilityRangeInfo range info to match.

hasScrollAction

fun hasScrollAction(): SemanticsMatcher

Return whether the component has a semantics scrollable action defined.

hasSubstring

fun hasSubstring(
    substring: String,
    ignoreCase: Boolean = false
): SemanticsMatcher

Returns whether the component's text contains the given substring.

Parameters
substring: String Substring to check.
ignoreCase: Boolean = false Whether case should be ignored.

hasTestTag

fun hasTestTag(testTag: String): SemanticsMatcher

Returns whether the component is annotated by the given test tag.

Parameters
testTag: String Value to match.

hasText

fun hasText(
    text: String,
    ignoreCase: Boolean = false
): SemanticsMatcher

Returns whether the component's text matches exactly to the given text.

Parameters
text: String Text to match.
ignoreCase: Boolean = false Whether case should be ignored.

hasValue

fun hasValue(value: String): SemanticsMatcher

Returns whether the component's value matches exactly to the given accessibility value.

Parameters
value: String Value to match.

isDialog

fun isDialog(): SemanticsMatcher

Returns whether the component is a dialog.

This only checks if the component itself is a dialog, not if it is part of a dialog. Use hasAnyAncestorThat(isDialog()) for that.

isEnabled

fun isEnabled(): SemanticsMatcher

Returns whether the component is enabled.

isHidden

fun isHidden(): SemanticsMatcher

Returns whether the component is hidden.

This checks only the property of the component itself. Ignoring parents visibility.

isInMutuallyExclusiveGroup

fun isInMutuallyExclusiveGroup(): SemanticsMatcher

Verifies that the component is in a mutually exclusive group - that is, that FoundationSemanticsProperties.InMutuallyExclusiveGroup is set to true

isNotEnabled

fun isNotEnabled(): SemanticsMatcher

Returns whether the component is not enabled.

isNotHidden

fun isNotHidden(): SemanticsMatcher

Returns whether the component is not hidden.

This checks only the property of the component itself. Ignoring parents visibility.

isOff

fun isOff(): SemanticsMatcher

Returns whether the component is not toggled.

isOn

fun isOn(): SemanticsMatcher

Returns whether the component is toggled.

isPopup

fun isPopup(): SemanticsMatcher

Returns whether the component is a popup.

This only checks if the component itself is a popup, not if it is part of a popup. Use hasAnyAncestorThat(isPopup()) for that.

isRoot

fun isRoot(): SemanticsMatcher

isSelectable

fun isSelectable(): SemanticsMatcher

Return whether the component is selectable.

isSelected

fun isSelected(): SemanticsMatcher

Returns whether the component is selected.

isToggleable

fun isToggleable(): SemanticsMatcher

Return whether the component is checkable.

isUnselected

fun isUnselected(): SemanticsMatcher

Returns whether the component is not selected.

runOnIdleCompose

fun <T> runOnIdleCompose(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.

runOnUiThread

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

Runs the given action on the UI thread.

This method is blocking until the action is complete.

waitForIdle

fun waitForIdle(): Unit

Waits for compose to be idle.

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

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

Top-level properties

BigTestConstraints

val BigTestConstraints: DpConstraints

Constant to emulate very big but finite constraints

Extension functions

ancestors

fun SemanticsNodeInteraction.ancestors(): SemanticsNodeInteractionCollection

Returns all the ancestors of this node.

Example: For the following tree

|-A
  |-B
    |-C <- this node
Returns B, A

assert

fun SemanticsNodeInteraction.assert(
    matcher: SemanticsMatcher,
    messagePrefixOnError: () -> String = null
): SemanticsNodeInteraction

Asserts that the provided matcher is satisfied for this node.

Parameters
matcher: SemanticsMatcher Matcher to verify.
messagePrefixOnError: () -> String = null Prefix to be put in front of an error that gets thrown in case this assert fails. This can be helpful in situations where this assert fails as part of a bigger operation that used this assert as a precondition check.
Exceptions
AssertionError if the matcher does not match or the node can no longer be found.

assertAll

fun SemanticsNodeInteractionCollection.assertAll(matcher: SemanticsMatcher): SemanticsNodeInteractionCollection

Asserts that all the nodes in this collection satisfy the given matcher.

This passes also for empty collections.

Parameters
matcher: SemanticsMatcher Matcher that has to be satisfied by all the nodes in the collection.
Exceptions
AssertionError if the collection contains at least one element that does not satisfy the given matcher.

assertAny

fun SemanticsNodeInteractionCollection.assertAny(matcher: SemanticsMatcher): SemanticsNodeInteractionCollection

Asserts that this collection contains at least one element that satisfies the given matcher.

Parameters
matcher: SemanticsMatcher Matcher that has to be satisfied by at least one of the nodes in the collection.
Exceptions
AssertionError if not at least one matching node was node.

assertCountEquals

fun SemanticsNodeInteractionCollection.assertCountEquals(expectedSize: Int): SemanticsNodeInteractionCollection

Asserts that this collection of nodes is equal to the given expectedSize.

Provides a detailed error message on failure.

Exceptions
AssertionError if the size is not equal to expectedSize

assertHasClickAction

fun SemanticsNodeInteraction.assertHasClickAction(): SemanticsNodeInteraction

Asserts that the current component has a click action.

Throws AssertionError if the component is doesn't have a click action.

assertHasNoClickAction

fun SemanticsNodeInteraction.assertHasNoClickAction(): SemanticsNodeInteraction

Asserts that the current component doesn't have a click action.

Throws AssertionError if the component has a click action.

assertHasPendingChanges

fun ComposeExecutionControl.assertHasPendingChanges(): Unit

Performs recomposition and asserts that there were some pending changes.

Exceptions
AssertionError if recomposition has no pending changes.

assertIsDisplayed

fun SemanticsNodeInteraction.assertIsDisplayed(): SemanticsNodeInteraction

Asserts that the current component is displayed on screen.

Throws AssertionError if the component is not displayed.

assertIsEnabled

fun SemanticsNodeInteraction.assertIsEnabled(): SemanticsNodeInteraction

Asserts that the current component is enabled.

Throws AssertionError if the component is not enabled or does not define the property at all.

assertIsHidden

fun SemanticsNodeInteraction.assertIsHidden(): SemanticsNodeInteraction

Asserts that the current component has hidden property set to true.

Note that this does not verify parents of the component. For stronger guarantees of visibility see assertIsNotDisplayed. If you want to assert that the component is not even in the hierarchy use SemanticsNodeInteraction.assertDoesNotExist.

Throws AssertionError if the component is not hidden.

assertIsInMutuallyExclusiveGroup

fun SemanticsNodeInteraction.assertIsInMutuallyExclusiveGroup(): SemanticsNodeInteraction

Asserts the component is in a mutually exclusive group. This is used by radio groups to assert only one is selected at a given time.

assertIsNotDisplayed

fun SemanticsNodeInteraction.assertIsNotDisplayed(): SemanticsNodeInteraction

Asserts that the current component is not displayed on screen.

Throws AssertionError if the component is displayed.

assertIsNotEnabled

fun SemanticsNodeInteraction.assertIsNotEnabled(): SemanticsNodeInteraction

Asserts that the current component is not enabled.

Throws AssertionError if the component is enabled or does not defined the property at all.

assertIsNotHidden

fun SemanticsNodeInteraction.assertIsNotHidden(): SemanticsNodeInteraction

Asserts that the current component has hidden property set to false.

Note that this does not verify parents of the component. For stronger guarantees of visibility see assertIsDisplayed. If you only want to assert that the component is in the hierarchy use SemanticsNodeInteraction.assertExists

Throws AssertionError if the component is hidden.

assertIsOff

fun SemanticsNodeInteraction.assertIsOff(): SemanticsNodeInteraction

Asserts that the current component is unchecked.

Throws AssertionError if the component is checked, indeterminate, or not toggleable.

assertIsOn

fun SemanticsNodeInteraction.assertIsOn(): SemanticsNodeInteraction

Asserts that the current component is checked.

Throws AssertionError if the component is not unchecked, indeterminate, or not toggleable.

assertIsSelectable

fun SemanticsNodeInteraction.assertIsSelectable(): SemanticsNodeInteraction

Asserts that the current component is selectable.

Throws AssertionError if the component is not selectable.

assertIsSelected

fun SemanticsNodeInteraction.assertIsSelected(): SemanticsNodeInteraction

Asserts that the current component is selected.

Throws AssertionError if the component is unselected or not selectable.

assertIsToggleable

fun SemanticsNodeInteraction.assertIsToggleable(): SemanticsNodeInteraction

Asserts that the current component is toggleable.

Throws AssertionError if the component is not toggleable.

assertIsUnselected

fun SemanticsNodeInteraction.assertIsUnselected(): SemanticsNodeInteraction

Asserts that the current component is unselected.

Throws AssertionError if the component is selected or not selectable.

assertLabelEquals

fun SemanticsNodeInteraction.assertLabelEquals(value: String): SemanticsNodeInteraction

Asserts the component's label equals the given String. For further details please check SemanticsProperties.AccessibilityLabel. Throws AssertionError if the node's value is not equal to value, or if the node has no value

assertLastRecomposeHadChanges

fun ComposeExecutionControl.assertLastRecomposeHadChanges(): Unit

Asserts that last recomposition had some changes.

assertLastRecomposeHadNoChanges

fun ComposeExecutionControl.assertLastRecomposeHadNoChanges(): Unit

Asserts that last recomposition had no some changes.

assertMeasureSizeIsPositive

fun ComposeExecutionControl.assertMeasureSizeIsPositive(): Unit

Assert that the underlying view under test has a positive size.

Useful to assert that the test case has some content.

Exceptions
AssertionError if the underlying view has zero measured size.

assertNoPendingChanges

fun ComposeExecutionControl.assertNoPendingChanges(): Unit

Performs recomposition and asserts that there were some pending changes.

Exceptions
AssertionError if recomposition has pending changes.

assertPixelColor

fun Bitmap.assertPixelColor(
    expected: Color,
    x: Int,
    y: Int,
    error: (Color) -> String = { color -> "Pixel($x, $y) expected to be $expected, but was $color" }
): Unit

Asserts that the color at a specific pixel in the bitmap at (x, y) is expected.

assertPixels

fun Bitmap.assertPixels(
    expectedSize: IntSize? = null,
    expectedColorProvider: (pos: IntOffset) -> Color?
): Unit

A helper function to run asserts on Bitmap.

Parameters
expectedSize: IntSize? = null The expected size of the bitmap. Leave null to skip the check.
expectedColorProvider: (pos: IntOffset) -> Color? Returns the expected color for the provided pixel position. The returned color is then asserted as the expected one on the given bitmap.
Exceptions
AssertionError if size or colors don't match.

assertRangeInfoEquals

fun SemanticsNodeInteraction.assertRangeInfoEquals(value: AccessibilityRangeInfo): SemanticsNodeInteraction

Asserts the component's range info equals the given value.

For further details please check SemanticsProperties.AccessibilityRangeInfo. Throws AssertionError if the node's value is not equal to value, or if the node has no value

assertShape

fun Bitmap.assertShape(
    density: Density,
    shape: Shape,
    shapeColor: Color,
    backgroundColor: Color,
    backgroundShape: Shape = RectangleShape,
    sizeX: Float = width.toFloat(),
    sizeY: Float = height.toFloat(),
    shapeSizeX: Float = sizeX,
    shapeSizeY: Float = sizeY,
    centerX: Float = width / 2f,
    centerY: Float = height / 2f,
    shapeOverlapPixelCount: Float = 1.0f
): Unit

Asserts that the given shape is drawn within the bitmap with the size the dimensions shapeSizeX x shapeSizeY, centered at (centerX, centerY) with the color shapeColor. The bitmap area examined is sizeX x sizeY, centered at (centerX, centerY) and everything outside the shape is expected to be color backgroundColor.

Parameters
density: Density current Density or the screen
shape: Shape defines the Shape
shapeColor: Color the color of the shape
backgroundColor: Color the color of the background
backgroundShape: Shape = RectangleShape defines the Shape of the background
sizeX: Float = width.toFloat() width of the area filled with the backgroundShape
sizeY: Float = height.toFloat() height of the area filled with the backgroundShape
shapeSizeX: Float = sizeX width of the area filled with the shape
shapeSizeY: Float = sizeY height of the area filled with the shape
centerX: Float = width / 2f the X position of the center of the shape inside the sizeX
centerY: Float = height / 2f the Y position of the center of the shape inside the sizeY
shapeOverlapPixelCount: Float = 1.0f The size of the border area from the shape outline to leave it untested as it is likely anti-aliased. The default is 1 pixel

assertShape

fun Bitmap.assertShape(
    density: Density,
    horizontalPadding: Dp,
    verticalPadding: Dp,
    backgroundColor: Color,
    shapeColor: Color,
    shape: Shape = RectangleShape,
    shapeOverlapPixelCount: Float = 1.0f
): Unit

Asserts that the bitmap is fully occupied by the given shape with the color shapeColor without horizontalPadding and verticalPadding from the sides. The padded area is expected to have backgroundColor.

Parameters
density: Density current Density or the screen
horizontalPadding: Dp the symmetrical padding to be applied from both left and right sides
verticalPadding: Dp the symmetrical padding to be applied from both top and bottom sides
backgroundColor: Color the color of the background
shapeColor: Color the color of the shape
shape: Shape = RectangleShape defines the Shape
shapeOverlapPixelCount: Float = 1.0f The size of the border area from the shape outline to leave it untested as it is likely anti-aliased. The default is 1 pixel

assertTextEquals

fun SemanticsNodeInteraction.assertTextEquals(value: String): SemanticsNodeInteraction

Asserts the component's text equals the given String. For further details please check SemanticsProperties.Text. Throws AssertionError if the node's value is not equal to value, or if the node has no value

assertValueEquals

fun SemanticsNodeInteraction.assertValueEquals(value: String): SemanticsNodeInteraction

Asserts the component's value equals the given value.

For further details please check SemanticsProperties.AccessibilityValue. Throws AssertionError if the node's value is not equal to value, or if the node has no value

callSemanticsAction

fun <T : Function<Boolean>> SemanticsNodeInteraction.callSemanticsAction(
    key: SemanticsPropertyKey<AccessibilityAction<T>>,
    invocation: (T) -> Unit
): Unit

Provides support to call custom semantics actions on this node.

This method is supposed to be used for actions with parameters.

This will properly verify that the actions exists and provide clear error message in case it does not. It also handle synchronization and performing the action on the UI thread. This call is blocking until the action is performed

Parameters
key: SemanticsPropertyKey<AccessibilityAction<T>> Key of the action to be performed.
invocation: (T) -> Unit Place where you call your action. In the argument is provided the underlying action from the given Semantics action.
Exceptions
AssertionError If the semantics action is not defined on this node.

callSemanticsAction

fun SemanticsNodeInteraction.callSemanticsAction(key: SemanticsPropertyKey<AccessibilityAction<() -> Boolean>>): Unit

Provides support to call custom semantics actions on this node.

This method is for calling actions that have no parameters.

This will properly verify that the actions exists and provide clear error message in case it does not. It also handle synchronization and performing the action on the UI thread. This call is blocking until the action is performed

Parameters
key: SemanticsPropertyKey<AccessibilityAction<() -> Boolean>> Key of the action to be performed.
Exceptions
AssertionError If the semantics action is not defined on this node.

captureToBitmap

@RequiresApi(26) fun View.captureToBitmap(): Bitmap

Captures the underlying view's surface into bitmap.

This has currently several limitations. Currently we assume that the view is hosted in Activity's window. Also if there is another window covering part of the component if won't occur in the bitmap as this is taken from the component's window surface.

captureToBitmap

@RequiresApi(26) fun SemanticsNodeInteraction.captureToBitmap(): Bitmap

Captures the underlying component's surface into bitmap.

This has a limitation that if there is another window covering part of this component, such a window won't occur in this bitmap.

child

fun SemanticsNodeInteraction.child(): SemanticsNodeInteraction

Returns exactly one child of this node.

Use this only if this node has exactly one child.

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.

childAt

fun SemanticsNodeInteraction.childAt(index: Int): SemanticsNodeInteraction

Returns child of this node at the given index.

This is just a shortcut for "childrenindex".

children

fun SemanticsNodeInteraction.children(): SemanticsNodeInteractionCollection

Returns children of this node.

contains

fun Path.contains(offset: Offset): Boolean

Tests to see if the given point is within the path. (That is, whether the point would be in the visible portion of the path if the path was used with Canvas.clipPath.)

The point argument is interpreted as an offset from the origin.

Returns true if the point is in the path, and false otherwise.

doClearText

fun SemanticsNodeInteraction.doClearText(alreadyHasFocus: Boolean = false): Unit

Clears the text in this node in similar way to IME.

Note performing this operation requires to get a focus.

Parameters
alreadyHasFocus: Boolean = false Whether the node already has a focus and thus does not need to be clicked on.

doClick

fun SemanticsNodeInteraction.doClick(): SemanticsNodeInteraction

Performs a click action on the given component.

doFramesAssertAllHadChangesExceptLastOne

fun ComposeExecutionControl.doFramesAssertAllHadChangesExceptLastOne(numberOfFramesToBeStable: Int): Unit

Performs the given amount of frames and asserts that there are no changes pending afterwards. Also asserts that all the frames (except the last one) had changes to recompose.

Exceptions
AssertionError if any frame before numberOfFramesToBeStable frame had no pending changes or the last frame had pending changes.

doFramesUntilNoChangesPending

fun ComposeExecutionControl.doFramesUntilNoChangesPending(maxAmountOfFrames: Int = 10): Int

Runs frames until there are no changes pending.

Parameters
maxAmountOfFrames: Int = 10 Max amount of frames to perform before giving up and throwing exception.
Exceptions
AssertionError if there are still pending changes after maxAmountOfFrames executed.

doGesture

fun SemanticsNodeInteraction.doGesture(block: GestureScope.() -> Unit): SemanticsNodeInteraction

Executes the gestures specified in the given block.

Example usage:

findByTag("myWidget")
   .doGesture {
       sendSwipeUp()
   }

doPartialGesture

fun SemanticsNodeInteraction.doPartialGesture(block: PartialGestureScope.() -> Unit): SemanticsNodeInteraction

Executes the (partial) gesture specified in the given block. The gesture doesn't need to be complete and can be resumed later. It is the responsibility of the caller to make sure partial gestures don't leave the test in an inconsistent state.

When sending the down event, a token is returned which needs to be used in all subsequent events of this gesture.

Example usage:

val position = Offset(10f, 10f)
findByTag("myWidget")
   .doPartialGesture { sendDown(position) }
   .assertHasClickAction()
   .doPartialGesture { sendUp(position) }

doReplaceText

fun SemanticsNodeInteraction.doReplaceText(
    text: String,
    alreadyHasFocus: Boolean = false
): Unit

Replaces existing text with the given text in this node in similar way to IME.

This does not reflect text selection. All the text gets cleared out and new inserted.

Parameters
text: String Text to send.
alreadyHasFocus: Boolean = false Whether the node already has a focus and thus does not need to be clicked on.

doScrollTo

fun SemanticsNodeInteraction.doScrollTo(): SemanticsNodeInteraction

Scrolls to a component using SemanticsActions. It first identifies a parent component with a Semantics ScrollTo action, then it retrieves the location of the current element and computes the relative coordinates that will be used by the scroller.

Throws AssertionError if there is no parent component with ScrollTo SemanticsAction, the current semantics component doesn't have a bounding rectangle set or if a layout node used to compute the relative coordinates to be fed to the ScrollTo action can't be found.

doSendImeAction

fun SemanticsNodeInteraction.doSendImeAction(alreadyHasFocus: Boolean = false): Unit

Sends to this node the IME action associated with it in similar way to IME.

The node needs to define its IME action in semantics.

Parameters
alreadyHasFocus: Boolean = false Whether the node already has a focus and thus does not need to be clicked on.
Exceptions
AssertionError if the node does not support input or does not define IME action.
IllegalStateException if tne node did not establish input connection (e.g. is not focused)

doSendKeyEvent

fun SemanticsNodeInteraction.doSendKeyEvent(keyEvent: KeyEvent): Boolean

Send the specified KeyEvent to the focused component.

Return
true if the event was consumed. False otherwise.

doSendText

fun SemanticsNodeInteraction.doSendText(
    text: String,
    alreadyHasFocus: Boolean = false
): Unit

Sends the given text to this node in similar way to IME.

Parameters
text: String Text to send.
alreadyHasFocus: Boolean = false Whether the node already has a focus and thus does not need to be clicked on.

dumpToString

fun SemanticsNodeInteraction.dumpToString(): String

Dumps all the semantics nodes information it holds into string.

Note that this will fetch the latest snapshot of nodes it sees in the hierarchy for the IDs it collected before. So the output can change over time if the tree changes.

dumpToString

fun SemanticsNodeInteractionCollection.dumpToString(): String

Dumps all the semantics nodes information it holds into string.

Note that this will fetch the latest snapshot of nodes it sees in the hierarchy for the IDs it collected before. So the output can change over time if the tree changes.

filter

fun SemanticsNodeInteractionCollection.filter(matcher: SemanticsMatcher): SemanticsNodeInteractionCollection

Returns all the nodes matching the given matcher.

Parameters
matcher: SemanticsMatcher Matcher to use for the filtering.

filterToOne

fun SemanticsNodeInteractionCollection.filterToOne(matcher: SemanticsMatcher): SemanticsNodeInteraction

Expects to return exactly one node matching the given matcher.

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

Parameters
matcher: SemanticsMatcher Matcher to use for the filtering.

first

fun SemanticsNodeInteractionCollection.first(): SemanticsNodeInteraction

Returns the first node in this collection.

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

last

fun SemanticsNodeInteractionCollection.last(): SemanticsNodeInteraction

Returns the last node in this collection.

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

localToGlobal

fun BaseGestureScope.localToGlobal(position: Offset): Offset

Transforms the position to global coordinates, as defined by globalBounds

Parameters
position: Offset A position in local coordinates

movePointerBy

fun PartialGestureScope.movePointerBy(
    pointerId: Int,
    delta: Offset
): Unit

Moves the position of the pointer with the given pointerId by the given delta, but does not send a move event. The move event can be sent with sendMove.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

Parameters
pointerId: Int The id of the pointer to move, as supplied in sendDown
delta: Offset The position for this move event, relative to the last sent position of the pointer. For example, `delta = Offset(10.px, -10.px) will add 10.px to the pointer's last x-position, and subtract 10.px from the pointer's last y-position.

movePointerTo

fun PartialGestureScope.movePointerTo(
    pointerId: Int,
    position: Offset
): Unit

Updates the position of the pointer with the given pointerId to the given position, but does not send a move event. The move event can be sent with sendMove. The position is in the component's local coordinate system, where (0.px, 0.px) is the top left corner of the component.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

Parameters
pointerId: Int The id of the pointer to move, as supplied in sendDown
position: Offset The new position of the pointer, in the component's local coordinate system

parent

fun SemanticsNodeInteraction.parent(): SemanticsNodeInteraction

Returns a parent of this node.

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.

percentOffset

fun BaseGestureScope.percentOffset(
    @FloatRange(-1.0, 1.0) x: Float = 0f,
    @FloatRange(-1.0, 1.0) y: Float = 0f
): Offset

Creates an Offset relative to the size of the component we're interacting with. x and y are fractions of the width and height. Note that percentOffset(1f, 1f) != bottomRight, see right and bottom.

For example: percentOffset(.5f, .5f) is the same as the center; centerLeft + percentOffset(.1f, 0f) is a point 10% inward from the middle of the left edge; and bottomRight - percentOffset(.2f, .1f) is a point 20% to the left and 10% to the top of the bottom right corner.

recomposeAssertHadChanges

fun ComposeExecutionControl.recomposeAssertHadChanges(): Unit

Performs recomposition and asserts that there were some pending changes.

Exceptions
AssertionError if last recomposition had no changes.

sendCancel

fun PartialGestureScope.sendCancel(): Unit

Sends a cancel event to cancel the current partial gesture. The cancel event contains the current position of all active pointers.

sendClick

fun GestureScope.sendClick(position: Offset = center): Unit

Performs a click gesture at the given position on the associated component, or in the center if the position is omitted. The position is in the component's local coordinate system, where (0, 0) is the top left corner of the component. The default position is the center of the component.

Parameters
position: Offset = center The position where to click, in the component's local coordinate system. If omitted, the center position will be used.

sendDoubleClick

fun GestureScope.sendDoubleClick(
    position: Offset = center,
    delay: Duration = doubleClickDelay
): Unit

Performs a double click gesture at the given position on the associated component, or in the center if the position is omitted. By default, the delay between the first and the second click is 145 milliseconds (empirically established). The position is in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Parameters
position: Offset = center The position of the double click, in the component's local coordinate system. If omitted, the center position will be used.
delay: Duration = doubleClickDelay The time between the up event of the first click and the down event of the second click

sendDown

fun PartialGestureScope.sendDown(
    pointerId: Int,
    position: Offset
): Unit

Sends a down event for the pointer with the given pointerId at position on the associated component. The position is in the component's local coordinate system, where (0, 0) is the top left corner of the component.

If no pointers are down yet, this will start a new partial gesture. If a partial gesture is already in progress, this event is sent with at the same timestamp as the last event. If the given pointer is already down, an IllegalArgumentException will be thrown.

This gesture is considered partial, because the entire gesture can be spread over several invocations of doPartialGesture. An entire gesture starts with a down event, followed by several down, move or up events, and ends with an up or a cancel event. Movement can be expressed with sendMoveTo and sendMoveBy to move a single pointer at a time, or movePointerTo and movePointerBy to move multiple pointers at a time. The movePointer[To|By] methods do not send the move event directly, use sendMove to send the move event. Some other methods can send a move event as well. All events, regardless the method used, will always contain the current position of all pointers.

Down and up events are sent at the same time as the previous event, but will send an extra move event just before the down or up event if movePointerTo or movePointerBy has been called and no move event has been sent yet. This does not happen for cancel events, but the cancel event will contain the up to date position of all pointers. Move and cancel events will advance the event time by 10 milliseconds.

Because partial gestures don't have to be defined all in the same doPartialGesture block, keep in mind that while the gesture is not complete, all code you execute in between blocks that progress the gesture, will be executed while imaginary fingers are actively touching the screen.

In the context of testing, it is not necessary to complete a gesture with an up or cancel event, if the test ends before it expects the finger to be lifted from the screen.

Parameters
pointerId: Int The id of the pointer, can be any number not yet in use by another pointer
position: Offset The position of the down event, in the component's local coordinate system

sendDown

fun PartialGestureScope.sendDown(position: Offset): Unit

Sends a down event for the default pointer at position on the associated component. The position is in the component's local coordinate system, where (0, 0) is the top left corner of the component. The default pointer has pointerId = 0.

If no pointers are down yet, this will start a new partial gesture. If a partial gesture is already in progress, this event is sent with at the same timestamp as the last event. If the default pointer is already down, an IllegalArgumentException will be thrown.

Parameters
position: Offset The position of the down event, in the component's local coordinate system

sendLongClick

fun GestureScope.sendLongClick(
    position: Offset = center,
    duration: Duration = LongPressTimeout + 100.milliseconds
): Unit

Performs a long click gesture at the given position on the associated component, or in the center if the position is omitted. By default, the duration of the press is LongPressTimeout + 100 milliseconds. The position is in the component's local coordinate system, where (0, 0) is the top left corner of the component.

Parameters
position: Offset = center The position of the long click, in the component's local coordinate system. If omitted, the center position will be used.
duration: Duration = LongPressTimeout + 100.milliseconds The time between the down and the up event

sendMove

fun PartialGestureScope.sendMove(): Unit

Sends a move event without updating any of the pointer positions. This can be useful when batching movement of multiple pointers together, which can be done with movePointerTo and movePointerBy.

sendMoveBy

fun PartialGestureScope.sendMoveBy(
    pointerId: Int,
    delta: Offset
): Unit

Sends a move event on the associated component, with the position of the pointer with the given pointerId moved by the given delta.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

Parameters
pointerId: Int The id of the pointer to move, as supplied in sendDown
delta: Offset The position for this move event, relative to the last sent position of the pointer. For example, `delta = Offset(10.px, -10.px) will add 10.px to the pointer's last x-position, and subtract 10.px from the pointer's last y-position.

sendMoveBy

fun PartialGestureScope.sendMoveBy(delta: Offset): Unit

Sends a move event on the associated component, with the position of the default pointer moved by the given delta. The default pointer has pointerId = 0.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

Parameters
delta: Offset The position for this move event, relative to the last sent position of the pointer. For example, `delta = Offset(10.px, -10.px) will add 10.px to the pointer's last x-position, and subtract 10.px from the pointer's last y-position.

sendMoveTo

fun PartialGestureScope.sendMoveTo(
    pointerId: Int,
    position: Offset
): Unit

Sends a move event on the associated component, with the position of the pointer with the given pointerId updated to position. The position is in the component's local coordinate system, where (0, 0) is the top left corner of the component.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

Parameters
pointerId: Int The id of the pointer to move, as supplied in sendDown
position: Offset The new position of the pointer, in the component's local coordinate system

sendMoveTo

fun PartialGestureScope.sendMoveTo(position: Offset): Unit

Sends a move event on the associated component, with the position of the default pointer updated to position. The position is in the component's local coordinate system, where (0, 0) is the top left corner of the component. The default pointer has pointerId = 0.

If the default pointer is not yet down, an IllegalArgumentException will be thrown.

Parameters
position: Offset The new position of the pointer, in the component's local coordinate system

sendPinch

fun GestureScope.sendPinch(
    start0: Offset,
    end0: Offset,
    start1: Offset,
    end1: Offset,
    duration: Duration = 400.milliseconds
): Unit

Performs a pinch gesture on the associated component.

For each pair of start and end Offsets, the motion events are linearly interpolated. The coordinates are in the component's local coordinate system where (0, 0) is the top left corner of the component. The default duration is 400 milliseconds.

Parameters
start0: Offset The start position of the first gesture in the component's local coordinate system
end0: Offset The end position of the first gesture in the component's local coordinate system
start1: Offset The start position of the second gesture in the component's local coordinate system
end1: Offset The end position of the second gesture in the component's local coordinate system
duration: Duration = 400.milliseconds the duration of the gesture

sendSwipe

fun GestureScope.sendSwipe(
    start: Offset,
    end: Offset,
    duration: Duration = 200.milliseconds
): Unit

Performs the swipe gesture on the associated component. The motion events are linearly interpolated between start and end. The coordinates are in the component's local coordinate system, where (0, 0) is the top left corner of the component. The default duration is 200 milliseconds.

Parameters
start: Offset The start position of the gesture, in the component's local coordinate system
end: Offset The end position of the gesture, in the component's local coordinate system
duration: Duration = 200.milliseconds The duration of the gesture

sendSwipeDown

fun GestureScope.sendSwipeDown(): Unit

Performs a swipe down gesture on the associated component. The gesture starts slightly below the top of the component and ends at the bottom.

sendSwipeLeft

fun GestureScope.sendSwipeLeft(): Unit

Performs a swipe left gesture on the associated component. The gesture starts slightly left of the right side of the component and ends at the left side.

sendSwipeRight

fun GestureScope.sendSwipeRight(): Unit

Performs a swipe right gesture on the associated component. The gesture starts slightly right of the left side of the component and ends at the right side.

sendSwipeUp

fun GestureScope.sendSwipeUp(): Unit

Performs a swipe up gesture on the associated component. The gesture starts slightly above the bottom of the component and ends at the top.

sendSwipeWithVelocity

fun GestureScope.sendSwipeWithVelocity(
    start: Offset,
    end: Offset,
    @FloatRange(0.0) endVelocity: Float,
    duration: Duration = 200.milliseconds
): Unit

Performs the swipe gesture on the associated component, such that the velocity when the gesture is finished is roughly equal to endVelocity. The MotionEvents are linearly interpolated between start and end. The coordinates are in the component's local coordinate system, where (0, 0) is the top left corner of the component. The default duration is 200 milliseconds.

Note that due to imprecisions, no guarantees can be made on the precision of the actual velocity at the end of the gesture, but generally it is within 0.1% of the desired velocity.

Parameters
start: Offset The start position of the gesture, in the component's local coordinate system
end: Offset The end position of the gesture, in the component's local coordinate system
endVelocity: Float The velocity of the gesture at the moment it ends. Must be positive.
duration: Duration = 200.milliseconds The duration of the gesture. Must be long enough that at least 3 input events are generated, which happens with a duration of 25ms or more.

sendUp

fun PartialGestureScope.sendUp(pointerId: Int = 0): Unit

Sends an up event for the pointer with the given pointerId, or the default pointer if pointerId is omitted, on the associated component. If any pointers have been moved with movePointerTo or movePointerBy and no move event has been sent yet, a move event will be sent right before the up event.

Parameters
pointerId: Int = 0 The id of the pointer to lift up, as supplied in sendDown

setContentAndCollectSizes

fun ComposeTestRule.setContentAndCollectSizes(
    parentConstraints: DpConstraints = BigTestConstraints,
    children: () -> Unit
): CollectedSizes

Set content as with ComposeTestRule.setContent, but return CollectedSizes to assert width and height of this content

Parameters
parentConstraints: DpConstraints = BigTestConstraints desired parent constraints for content
children: () -> Unit content to set

setContentAndGetPixelSize

fun ComposeTestRule.setContentAndGetPixelSize(
    parentConstraints: DpConstraints = BigTestConstraints,
    performSetContent: (() -> Unit) -> Unit = { setContent(it) },
    children: () -> Unit
): Size

Set content as with ComposeTestRule.setContent, but return sizes of this content

Parameters
parentConstraints: DpConstraints = BigTestConstraints desired parent constraints for content
performSetContent: (() -> Unit) -> Unit = { setContent(it) } lambda that should be performed to set content. Defaults to ComposeTestRule.setContent and usually don't need to be changed
children: () -> Unit content to set

setupContent

fun <T> ComposeBenchmarkScope<T>.setupContent(): Unit

Sets up the content. This is by default called by first invocation of ComposeBenchmarkScope.doFrame.

If you want to call this multiple times, make sure you call ComposeBenchmarkScope.disposeContent in between.

sibling

fun SemanticsNodeInteraction.sibling(): SemanticsNodeInteraction

Returns exactly one sibling of this node.

Use this only if this node has exactly one sibling.

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.

siblings

fun SemanticsNodeInteraction.siblings(): SemanticsNodeInteractionCollection

Returns all siblings of this node.

Example: For the following tree

|-A
  |-B1
  |-B2 <- this node
  |-B3
Returns B1, B3

Extension properties

bottom

inline val BaseGestureScope.bottom: Float

Returns the y-coordinate for the bottom of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component. Note that, unless height == 0, bottom != height. In particular, bottom == height - 1f, because pixels are 0-based. If height == 0, bottom == 0 too.

bottomCenter

val BaseGestureScope.bottomCenter: Offset

Returns the center of the bottom edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component. Note that bottomCenter.y != height, see bottom.

bottomLeft

val BaseGestureScope.bottomLeft: Offset

Returns the bottom left corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component. Note that bottomLeft.y != height, see bottom.

bottomRight

val BaseGestureScope.bottomRight: Offset

Returns the bottom right corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component. Note that bottomRight.x != width and bottomRight.y != height, see right and bottom.

center

val BaseGestureScope.center: Offset

Returns the center of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

centerLeft

val BaseGestureScope.centerLeft: Offset

Returns the center of the left edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

centerRight

val BaseGestureScope.centerRight: Offset

Returns the center of the right edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component. Note that centerRight.x != width, see right.

centerX

inline val BaseGestureScope.centerX: Float

Returns the x-coordinate for the center of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

centerY

inline val BaseGestureScope.centerY: Float

Returns the y-coordinate for the center of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

globalBounds

val BaseGestureScope.globalBounds: PxBounds

Returns the global bounds of the component we're interacting with

height

inline val BaseGestureScope.height: Int

Shorthand for size.height

left

inline val BaseGestureScope.left: Float

Returns the x-coordinate for the left edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

inline val BaseGestureScope.right: Float

Returns the x-coordinate for the right edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component. Note that, unless width == 0, right != width. In particular, right == width - 1f, because pixels are 0-based. If width == 0, right == 0 too.

size

val BaseGestureScope.size: IntSize

Returns the size of the component we're interacting with

top

inline val BaseGestureScope.top: Float

Returns the y-coordinate for the bottom of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

topCenter

val BaseGestureScope.topCenter: Offset

Returns the center of the top edge of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

topLeft

val BaseGestureScope.topLeft: Offset

Returns the top left corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component.

topRight

val BaseGestureScope.topRight: Offset

Returns the top right corner of the component we're interacting with, in the component's local coordinate system, where (0, 0) is the top left corner of the component. Note that topRight.x != width, see right.

width

inline val BaseGestureScope.width: Int

Shorthand for size.width