Google berkomitmen untuk mendorong terwujudnya keadilan rasial bagi komunitas Kulit Hitam. Lihat caranya.

androidx.ui.test

Interfaces

ComposeBenchmarkScope

Test scope accessible from benchmarks.

ComposeExecutionControl

Test scope accessible from execution controlled tests to test compose.

ComposeTestCase

To be implemented to provide a test case that is then executed by ComposeTestRule or can be used in benchmarks.

ComposeTestCaseSetup

Helper interface to run execution-controlled test via ComposeTestRule.

ComposeTestRule

Enables to run tests of individual composables without having to do manual setup.

LayeredComposeTestCase

To be implemented to provide a test case that is then executed in benchmarks.

TestAnimationClock

Interface for animation clocks that can report their idleness and can switch between ticking automatically (e.

Classes

AnimationClockTestRule

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

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.

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(disableTransitions: Boolean = false, disableBlinkingCursor: Boolean = true)

Factory method to provide implementation of ComposeTestRule.

SemanticsNodeInteraction
find(matcher: SemanticsMatcher, useUnmergedTree: Boolean = false)

Finds a component that matches the given condition.

SemanticsNodeInteractionCollection
findAll(matcher: SemanticsMatcher, useUnmergedTree: Boolean = false)

Finds all components that match the given condition.

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

Finds all components with the given label as AccessibilityLabel.

SemanticsNodeInteractionCollection
findAllByTag(testTag: String, useUnmergedTree: Boolean = false)

Finds all components identified by the given tag.

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

Finds all components with the given text.

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

Finds a component with the given label as its accessibilityLabel.

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

Finds a component with text that contains the given substring.

SemanticsNodeInteraction
findByTag(testTag: String, useUnmergedTree: Boolean = false)

Finds a component identified by the given tag.

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

Finds a component with the given text.

SemanticsNodeInteraction
findRoot(useUnmergedTree: Boolean = false)

Finds the root semantics node of the Compose tree.

SemanticsMatcher

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

SemanticsMatcher

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

SemanticsMatcher

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

SemanticsMatcher

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

SemanticsMatcher

Return whether the node has a semantics click action defined.

SemanticsMatcher
hasImeAction(actionType: ImeAction)

Returns whether the node defines the given IME action.

SemanticsMatcher

Return whether the node supports input methods.

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

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

SemanticsMatcher

Return whether the node has no semantics click action defined.

SemanticsMatcher

Return whether the node has no semantics scrollable action defined.

SemanticsMatcher

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

SemanticsMatcher

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

SemanticsMatcher

Return whether the node has a semantics scrollable action defined.

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

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

SemanticsMatcher
hasTestTag(testTag: String)

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

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

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

SemanticsMatcher
hasValue(value: String)

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

SemanticsMatcher

Returns whether the node is a dialog.

SemanticsMatcher

Returns whether the node is enabled.

SemanticsMatcher

Returns whether the node is focused.

SemanticsMatcher

Returns whether the node is hidden.

SemanticsMatcher

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

SemanticsMatcher

Returns whether the node is not enabled.

SemanticsMatcher

Returns whether the node is not focused.

SemanticsMatcher

Returns whether the node is not hidden.

SemanticsMatcher

Returns whether the node is not selected.

SemanticsMatcher

Returns whether the node is not toggled.

SemanticsMatcher

Returns whether the node is toggled.

SemanticsMatcher

Returns whether the node is a popup.

SemanticsMatcher

Return whether the node is the root semantics node.

SemanticsMatcher

Return whether the node is selectable.

SemanticsMatcher

Returns whether the node is selected.

SemanticsMatcher

Return whether the node is checkable.

SemanticsNodeInteractionCollection
onAllNodes(matcher: SemanticsMatcher, useUnmergedTree: Boolean = false)

Finds all semantics nodes that match the given condition.

SemanticsNodeInteractionCollection
onAllNodesWithLabel(label: String, ignoreCase: Boolean = false, useUnmergedTree: Boolean = false)

Finds all semantics nodes with the given label as AccessibilityLabel.

SemanticsNodeInteractionCollection
onAllNodesWithTag(testTag: String, useUnmergedTree: Boolean = false)

Finds all semantics nodes identified by the given tag.

SemanticsNodeInteractionCollection
onAllNodesWithText(text: String, ignoreCase: Boolean = false, useUnmergedTree: Boolean = false)

Finds all semantics nodes with the given text.

SemanticsNodeInteraction
onNode(matcher: SemanticsMatcher, useUnmergedTree: Boolean = false)

Finds a semantics node that matches the given condition.

SemanticsNodeInteraction
onNodeWithLabel(label: String, ignoreCase: Boolean = false, useUnmergedTree: Boolean = false)

Finds a semantics node with the given label as its accessibilityLabel.

SemanticsNodeInteraction
onNodeWithSubstring(text: String, ignoreCase: Boolean = false, useUnmergedTree: Boolean = false)

Finds a semantics node with text that contains the given substring.

SemanticsNodeInteraction
onNodeWithTag(testTag: String, useUnmergedTree: Boolean = false)

Finds a semantics node identified by the given tag.

SemanticsNodeInteraction
onNodeWithText(text: String, ignoreCase: Boolean = false, useUnmergedTree: Boolean = false)

Finds a semantincs node with the given text.

SemanticsNodeInteraction
onRoot(useUnmergedTree: Boolean = false)

Finds the root semantics node of the Compose tree.

T
runOnIdle(action: () -> T)

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

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.

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
SemanticsNodeInteraction
SemanticsNodeInteraction.assert(matcher: SemanticsMatcher, messagePrefixOnError: () -> String = null)

Asserts that the provided matcher is satisfied for this node.

SemanticsNodeInteraction

Asserts that the current semantics node has a click action.

SemanticsNodeInteraction

Asserts that the current semantics node has doesn't have a click action.

SemanticsNodeInteraction

Asserts that the layout of this node has height that is greater ot equal to expectedMinHeight.

SemanticsNodeInteraction

Asserts that the layout of this node has height equal to expectedHeight.

SemanticsNodeInteraction

Asserts that the current semantics node is displayed on screen.

SemanticsNodeInteraction

Asserts that the current semantics node is enabled.

SemanticsNodeInteraction

Asserts that the current semantics node has hidden property set to true.

SemanticsNodeInteraction

Asserts the semantics node is in a mutually exclusive group.

SemanticsNodeInteraction

Asserts that the current semantics node is not displayed on screen.

SemanticsNodeInteraction

Asserts that the current semantics node is not enabled.

SemanticsNodeInteraction

Asserts that the current semantics node has hidden property set to false.

SemanticsNodeInteraction

Asserts that the current semantics node is not selected.

SemanticsNodeInteraction

Asserts that the current semantics node is unchecked.

SemanticsNodeInteraction

Asserts that the current semantics node is checked.

SemanticsNodeInteraction

Asserts that the current semantics node is selectable.

SemanticsNodeInteraction

Asserts that the current semantics node is selected.

SemanticsNodeInteraction

Asserts that the current semantics node is toggleable.

SemanticsNodeInteraction

Asserts the node's label equals the given String.

SemanticsNodeInteraction

Asserts that the layout of this node has the left position in the root composable that is equal to the given position.

SemanticsNodeInteraction

Asserts that the layout of this node has position in the root composable that is equal to the given position.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

Asserts the node's text equals the given String.

SemanticsNodeInteraction

Asserts that the layout of this node has the top position in the root composable that is equal to the given position.

SemanticsNodeInteraction

Asserts the node's value equals the given value.

SemanticsNodeInteraction

Asserts that the layout of this node has width that is greater ot equal to expectedMinWidth.

SemanticsNodeInteraction

Asserts that the layout of this node has width equal to expectedWidth.

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 semantics node's surface into bitmap.

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.

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

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

Dp

Returns the position of an alignment line, or Dp.Unspecified if the line is not provided.

Bounds

Returns the bounds of the layout of this node.

Bounds

Returns the bounds of the layout of this node.

SemanticsNodeInteractionCollection

Returns all the ancestors of this node.

SemanticsNodeInteraction

Returns exactly one child of this node.

SemanticsNodeInteraction

Returns child of this node at the given index.

SemanticsNodeInteractionCollection

Returns children of this node.

SemanticsNodeInteraction

Returns a parent of this node.

SemanticsNodeInteraction

Returns exactly one sibling of this node.

SemanticsNodeInteractionCollection

Returns all siblings of this node.

SemanticsNodeInteraction

Performs a click action on the element represented by the given semantics node.

SemanticsNodeInteraction

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

Unit

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

Boolean

Send the specified KeyEvent to the focused component.

SemanticsNodeInteraction

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

SemanticsNodeInteraction

Scrolls to a node using SemanticsActions.

Unit

Provides support to call custom semantics actions on this node.

Unit

Provides support to call custom semantics actions on this node.

Unit

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

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

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

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

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

Unit
SemanticsNodeInteraction.printToLog(tag: String, @IntRange(0) maxDepth: Int = Int.MAX_VALUE)

Prints all the semantics nodes information into logs (as debug level).

String
SemanticsNodeInteraction.printToString(@IntRange(0) maxDepth: Int = Int.MAX_VALUE)

Prints all the semantics nodes information it holds into string.

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.

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.

Unit
SemanticsNodeInteractionCollection.printToLog(tag: String, @IntRange(0) maxDepth: Int = 0)

Prints all the semantics nodes information into logs (as debug level).

String

Prints all the semantics nodes information it holds into string.

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 Dp
Unit
Dp.assertIsEqualTo(expected: Dp, subject: String = "", tolerance: Dp = Dp(.5f))

Asserts that this value is equal to the given expected value.

Unit
Dp.assertIsNotEqualTo(unexpected: Dp, subject: String = "", tolerance: Dp = Dp(.5f))

Asserts that this value is not equal to the given unexpected value.

For GestureScope
Unit

Sends a cancel event to cancel the current partial gesture.

Unit
GestureScope.click(position: Offset = center)

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

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

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

Unit
GestureScope.down(pointerId: Int, position: Offset)

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

Unit

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

Offset

Transforms the position to global coordinates, as defined by LayoutCoordinates.localToGlobal

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

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

Unit

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

Unit
GestureScope.moveBy(pointerId: Int, delta: Offset)

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

Unit

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

Unit
GestureScope.movePointerBy(pointerId: Int, delta: Offset)

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

Unit
GestureScope.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
GestureScope.moveTo(pointerId: Int, position: Offset)

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

Unit

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

Offset
GestureScope.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 node we're interacting with.

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

Performs a pinch gesture on the associated node.

Unit

Sends a cancel event to cancel the current partial gesture.

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

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

Unit
GestureScope.sendMoveBy(pointerId: Int, delta: Offset)

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
GestureScope.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
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, 3.4E38) 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.

Unit
GestureScope.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.

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

Performs the swipe gesture on the associated node.

Unit

Performs a swipe down gesture on the associated node.

Unit

Performs a swipe left gesture on the associated node.

Unit

Performs a swipe right gesture on the associated node.

Unit

Performs a swipe up gesture on the associated node.

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

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

Unit
GestureScope.up(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 node.

For Path
Boolean
Path.contains(offset: Offset)

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

For ComposeBenchmarkScope
Unit

Sets up the content.

Extension properties summary

For GestureScope
Float

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

Offset

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

Offset

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

Offset

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

Offset

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

Offset

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

Offset

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

Float

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

Float

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

Int

Shorthand for size.height

Float

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

Float

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

IntSize

Returns the size of the node we're interacting with

Float

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

Offset

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

Offset

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

Offset

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

Int

Shorthand for size.width

Top-level functions

createComposeRule

fun createComposeRule(
    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 createAndroidComposeRule.

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,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteraction

Deprecated.

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 and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

findAll

fun findAll(
    matcher: SemanticsMatcher,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteractionCollection

Deprecated.

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.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

findAllByLabel

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

Deprecated.

Finds all components with the given label as AccessibilityLabel.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

findAllByTag

fun findAllByTag(
    testTag: String,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteractionCollection

Deprecated.

Finds all components identified by the given tag.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

findAllByText

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

Deprecated.

Finds all components with the given text.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

findByLabel

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

Deprecated.

Finds a component with the given label as its accessibilityLabel.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

findBySubstring

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

Deprecated.

Finds a component with text that contains the given substring.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

findByTag

fun findByTag(
    testTag: String,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteraction

Deprecated.

Finds a component identified by the given tag.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

findByText

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

Deprecated.

Finds a component with the given text.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

findRoot

fun findRoot(useUnmergedTree: Boolean = false): SemanticsNodeInteraction

Deprecated.

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

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

hasAnyAncestor

fun hasAnyAncestor(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the node 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

hasAnyChild

fun hasAnyChild(matcher: SemanticsMatcher): SemanticsMatcher

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

hasAnyDescendant

fun hasAnyDescendant(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the node 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

hasAnySibling

fun hasAnySibling(matcher: SemanticsMatcher): SemanticsMatcher

Returns whether the node 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 node has a semantics click action defined.

hasImeAction

fun hasImeAction(actionType: ImeAction): SemanticsMatcher

Returns whether the node defines the given IME action.

Parameters
actionType: ImeAction the action to match.

hasInputMethodsSupport

fun hasInputMethodsSupport(): SemanticsMatcher

Return whether the node supports input methods.

Supporting input methods means that the node provides a connection to IME (keyboard) and is able to accept input from it. This is however not enforced and relies on the nodes 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 node'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 node has no semantics click action defined.

hasNoScrollAction

fun hasNoScrollAction(): SemanticsMatcher

Return whether the node has no semantics scrollable action defined.

hasParent

fun hasParent(matcher: SemanticsMatcher): SemanticsMatcher

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

Returns false if no parent exists.

hasRangeInfo

fun hasRangeInfo(rangeInfo: AccessibilityRangeInfo): SemanticsMatcher

Returns whether the node'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 node has a semantics scrollable action defined.

hasSubstring

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

Returns whether the node'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 node 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 node'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 node's value matches exactly to the given accessibility value.

Parameters
value: String Value to match.

isDialog

fun isDialog(): SemanticsMatcher

Returns whether the node is a dialog.

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

isEnabled

fun isEnabled(): SemanticsMatcher

Returns whether the node is enabled.

isFocused

fun isFocused(): SemanticsMatcher

Returns whether the node is focused.

isHidden

fun isHidden(): SemanticsMatcher

Returns whether the node is hidden.

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

isInMutuallyExclusiveGroup

fun isInMutuallyExclusiveGroup(): SemanticsMatcher

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

isNotEnabled

fun isNotEnabled(): SemanticsMatcher

Returns whether the node is not enabled.

isNotFocused

fun isNotFocused(): SemanticsMatcher

Returns whether the node is not focused.

isNotHidden

fun isNotHidden(): SemanticsMatcher

Returns whether the node is not hidden.

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

isNotSelected

fun isNotSelected(): SemanticsMatcher

Returns whether the node is not selected.

isOff

fun isOff(): SemanticsMatcher

Returns whether the node is not toggled.

isOn

fun isOn(): SemanticsMatcher

Returns whether the node is toggled.

isPopup

fun isPopup(): SemanticsMatcher

Returns whether the node is a popup.

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

isRoot

fun isRoot(): SemanticsMatcher

Return whether the node is the root semantics node.

There is always one root in every node tree, added implicitly by Compose.

isSelectable

fun isSelectable(): SemanticsMatcher

Return whether the node is selectable.

isSelected

fun isSelected(): SemanticsMatcher

Returns whether the node is selected.

isToggleable

fun isToggleable(): SemanticsMatcher

Return whether the node is checkable.

onAllNodes

fun onAllNodes(
    matcher: SemanticsMatcher,
    useUnmergedTree: Boolean = false
): 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
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

onAllNodesWithLabel

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

Finds all semantics nodes with the given label as AccessibilityLabel.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

onAllNodesWithTag

fun onAllNodesWithTag(
    testTag: String,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteractionCollection

Finds all semantics nodes identified by the given tag.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

onAllNodesWithText

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

Finds all semantics nodes with the given text.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

onNode

fun onNode(
    matcher: SemanticsMatcher,
    useUnmergedTree: Boolean = false
): 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
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

onNodeWithLabel

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

Finds a semantics node with the given label as its accessibilityLabel.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

onNodeWithSubstring

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

Finds a semantics node with text that contains the given substring.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

onNodeWithTag

fun onNodeWithTag(
    testTag: String,
    useUnmergedTree: Boolean = false
): SemanticsNodeInteraction

Finds a semantics node identified by the given tag.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

See Also

onNodeWithText

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

Finds a semantincs node with the given text.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

onRoot

fun onRoot(useUnmergedTree: Boolean = false): SemanticsNodeInteraction

Finds the root semantics node of the Compose tree.

Useful for example for screenshot tests of the entire scene.

For usage patterns and semantics concepts see SemanticsNodeInteraction

Parameters
useUnmergedTree: Boolean = false Find within merged composables like Buttons.

runOnIdle

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

runOnIdleCompose

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

Deprecated.

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.

Extension functions

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 semantics node has a click action.

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

assertHasNoClickAction

fun SemanticsNodeInteraction.assertHasNoClickAction(): SemanticsNodeInteraction

Asserts that the current semantics node has doesn't have a click action.

Throws AssertionError if the node 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.

assertHeightIsAtLeast

fun SemanticsNodeInteraction.assertHeightIsAtLeast(expectedMinHeight: Dp): SemanticsNodeInteraction

Asserts that the layout of this node has height that is greater ot equal to expectedMinHeight.

Exceptions
AssertionError if comparison fails.

assertHeightIsEqualTo

fun SemanticsNodeInteraction.assertHeightIsEqualTo(expectedHeight: Dp): SemanticsNodeInteraction

Asserts that the layout of this node has height equal to expectedHeight.

Exceptions
AssertionError if comparison fails.

assertIsDisplayed

fun SemanticsNodeInteraction.assertIsDisplayed(): SemanticsNodeInteraction

Asserts that the current semantics node is displayed on screen.

Throws AssertionError if the node is not displayed.

assertIsEnabled

fun SemanticsNodeInteraction.assertIsEnabled(): SemanticsNodeInteraction

Asserts that the current semantics node is enabled.

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

assertIsEqualTo

fun Dp.assertIsEqualTo(
    expected: Dp,
    subject: String = "",
    tolerance: Dp = Dp(.5f)
): Unit

Asserts that this value is equal to the given expected value.

Performs the comparison with the given tolerance or the default one if none is provided. It is recommended to use tolerance when comparing positions and size coming from the framework as there can be rounding operation performed by individual layouts so the values can be slightly off from the expected ones.

Parameters
expected: Dp The expected value to which this one should be equal to.
subject: String = "" Used in the error message to identify which item this assertion failed on.
tolerance: Dp = Dp(.5f) The tolerance within which the values should be treated as equal.
Exceptions
AssertionError if comparison fails.

assertIsHidden

fun SemanticsNodeInteraction.assertIsHidden(): SemanticsNodeInteraction

Asserts that the current semantics node has hidden property set to true.

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

Throws AssertionError if the node is not hidden.

assertIsInMutuallyExclusiveGroup

fun SemanticsNodeInteraction.assertIsInMutuallyExclusiveGroup(): SemanticsNodeInteraction

Asserts the semantics node 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 semantics node is not displayed on screen.

Throws AssertionError if the node is displayed.

assertIsNotEnabled

fun SemanticsNodeInteraction.assertIsNotEnabled(): SemanticsNodeInteraction

Asserts that the current semantics node is not enabled.

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

assertIsNotEqualTo

fun Dp.assertIsNotEqualTo(
    unexpected: Dp,
    subject: String = "",
    tolerance: Dp = Dp(.5f)
): Unit

Asserts that this value is not equal to the given unexpected value.

Performs the comparison with the given tolerance or the default one if none is provided. It is recommended to use tolerance when comparing positions and size coming from the framework as there can be rounding operation performed by individual layouts so the values can be slightly off from the expected ones.

Parameters
unexpected: Dp The value to which this one should not be equal to.
subject: String = "" Used in the error message to identify which item this assertion failed on.
tolerance: Dp = Dp(.5f) The tolerance that is expected to be greater than the difference between the given values to treat them as non-equal.
Exceptions
AssertionError if comparison fails.

assertIsNotHidden

fun SemanticsNodeInteraction.assertIsNotHidden(): SemanticsNodeInteraction

Asserts that the current semantics node has hidden property set to false.

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

Throws AssertionError if the node is hidden.

assertIsNotSelected

fun SemanticsNodeInteraction.assertIsNotSelected(): SemanticsNodeInteraction

Asserts that the current semantics node is not selected.

Throws AssertionError if the node is selected or not selectable.

assertIsOff

fun SemanticsNodeInteraction.assertIsOff(): SemanticsNodeInteraction

Asserts that the current semantics node is unchecked.

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

assertIsOn

fun SemanticsNodeInteraction.assertIsOn(): SemanticsNodeInteraction

Asserts that the current semantics node is checked.

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

assertIsSelectable

fun SemanticsNodeInteraction.assertIsSelectable(): SemanticsNodeInteraction

Asserts that the current semantics node is selectable.

Throws AssertionError if the node is not selectable.

assertIsSelected

fun SemanticsNodeInteraction.assertIsSelected(): SemanticsNodeInteraction

Asserts that the current semantics node is selected.

Throws AssertionError if the node is unselected or not selectable.

assertIsToggleable

fun SemanticsNodeInteraction.assertIsToggleable(): SemanticsNodeInteraction

Asserts that the current semantics node is toggleable.

Throws AssertionError if the node is not toggleable.

assertLabelEquals

fun SemanticsNodeInteraction.assertLabelEquals(value: String): SemanticsNodeInteraction

Asserts the node'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.

assertLeftPositionInRootIsEqualTo

fun SemanticsNodeInteraction.assertLeftPositionInRootIsEqualTo(expectedTop: Dp): SemanticsNodeInteraction

Asserts that the layout of this node has the left position in the root composable that is equal to the given position.

Parameters
expectedTop: Dp The left (x) position to assert.
Exceptions
AssertionError if comparison fails.

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.

assertPositionInRootIsEqualTo

fun SemanticsNodeInteraction.assertPositionInRootIsEqualTo(
    expectedLeft: Dp,
    expectedTop: Dp
): SemanticsNodeInteraction

Asserts that the layout of this node has position in the root composable that is equal to the given position.

Parameters
expectedLeft: Dp The left (x) position to assert.
expectedTop: Dp The top (y) position to assert.
Exceptions
AssertionError if comparison fails.

assertRangeInfoEquals

fun SemanticsNodeInteraction.assertRangeInfoEquals(value: AccessibilityRangeInfo): SemanticsNodeInteraction

Asserts the node'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 node'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

assertTopPositionInRootIsEqualTo

fun SemanticsNodeInteraction.assertTopPositionInRootIsEqualTo(expectedTop: Dp): SemanticsNodeInteraction

Asserts that the layout of this node has the top position in the root composable that is equal to the given position.

Parameters
expectedTop: Dp The top (y) position to assert.
Exceptions
AssertionError if comparison fails.

assertValueEquals

fun SemanticsNodeInteraction.assertValueEquals(value: String): SemanticsNodeInteraction

Asserts the node'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

assertWidthIsAtLeast

fun SemanticsNodeInteraction.assertWidthIsAtLeast(expectedMinWidth: Dp): SemanticsNodeInteraction

Asserts that the layout of this node has width that is greater ot equal to expectedMinWidth.

Exceptions
AssertionError if comparison fails.

assertWidthIsEqualTo

fun SemanticsNodeInteraction.assertWidthIsEqualTo(expectedWidth: Dp): SemanticsNodeInteraction

Asserts that the layout of this node has width equal to expectedWidth.

Exceptions
AssertionError if comparison fails.

callSemanticsAction

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

Deprecated.

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

Deprecated.

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.

cancel

fun GestureScope.cancel(): Unit

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

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 semantics node's surface into bitmap.

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

click

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

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

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

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

Deprecated.

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

Deprecated.

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

Deprecated.

Executes the gestures specified in the given block.

Example usage:

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

doPartialGesture

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

Deprecated.

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)
onNodeWithTag("myWidget")
   .doPartialGesture { sendDown(position) }
   .assertHasClickAction()
   .doPartialGesture { sendUp(position) }

doReplaceText

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

Deprecated.

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

Deprecated.

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

Deprecated.

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)

doSendText

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

Deprecated.

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.

doubleClick

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

Performs a double click gesture at the given position on the associated node, 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 node's local coordinate system, where (0, 0) is the top left corner of the node.

Parameters
position: Offset = center The position of the double click, in the node'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

down

fun GestureScope.down(
    pointerId: Int,
    position: Offset
): Unit

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

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 performGesture. 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 moveTo and moveBy 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 move 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 performGesture 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 node's local coordinate system

down

fun GestureScope.down(position: Offset): Unit

Sends a down event for the default pointer at position on the associated node. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. 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 node's local coordinate system

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.

getAlignmentLinePosition

fun SemanticsNodeInteraction.getAlignmentLinePosition(line: AlignmentLine): Dp

Returns the position of an alignment line, or Dp.Unspecified if the line is not provided.

getBoundsInRoot

fun SemanticsNodeInteraction.getBoundsInRoot(): Bounds

Deprecated.

Returns the bounds of the layout of this node. The bounds are relative to the root composable.

getUnclippedBoundsInRoot

fun SemanticsNodeInteraction.getUnclippedBoundsInRoot(): Bounds

Returns the bounds of the layout of this node. The bounds are relative to the root composable.

localToGlobal

fun GestureScope.localToGlobal(position: Offset): Offset

Transforms the position to global coordinates, as defined by LayoutCoordinates.localToGlobal

Parameters
position: Offset A position in local coordinates

longClick

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

Performs a long click gesture at the given position on the associated node, 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 node's local coordinate system, where (0, 0) is the top left corner of the node.

Parameters
position: Offset = center The position of the long click, in the node'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

move

fun GestureScope.move(): 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.

moveBy

fun GestureScope.moveBy(
    pointerId: Int,
    delta: Offset
): Unit

Sends a move event on the associated node, 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 down
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.

moveBy

fun GestureScope.moveBy(delta: Offset): Unit

Sends a move event on the associated node, 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.

movePointerBy

fun GestureScope.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 move.

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 down
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 GestureScope.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 move. The position is in the node's local coordinate system, where (0.px, 0.px) is the top left corner of the node.

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 down
position: Offset The new position of the pointer, in the node's local coordinate system

moveTo

fun GestureScope.moveTo(
    pointerId: Int,
    position: Offset
): Unit

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

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 down
position: Offset The new position of the pointer, in the node's local coordinate system

moveTo

fun GestureScope.moveTo(position: Offset): Unit

Sends a move event on the associated node, with the position of the default pointer updated to position. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. 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 node's local coordinate system

onAncestors

fun SemanticsNodeInteraction.onAncestors(): SemanticsNodeInteractionCollection

Returns all the ancestors of this node.

Example: For the following tree

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

onChild

fun SemanticsNodeInteraction.onChild(): 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.

onChildAt

fun SemanticsNodeInteraction.onChildAt(index: Int): SemanticsNodeInteraction

Returns child of this node at the given index.

This is just a shortcut for "childrenindex".

onChildren

fun SemanticsNodeInteraction.onChildren(): SemanticsNodeInteractionCollection

Returns children of this node.

onFirst

fun SemanticsNodeInteractionCollection.onFirst(): 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.

onLast

fun SemanticsNodeInteractionCollection.onLast(): 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.

onParent

fun SemanticsNodeInteraction.onParent(): 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.

onSibling

fun SemanticsNodeInteraction.onSibling(): 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.

onSiblings

fun SemanticsNodeInteraction.onSiblings(): SemanticsNodeInteractionCollection

Returns all siblings of this node.

Example: For the following tree

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

percentOffset

fun GestureScope.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 node 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.

performClick

fun SemanticsNodeInteraction.performClick(): SemanticsNodeInteraction

Performs a click action on the element represented by the given semantics node.

performGesture

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

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

This method must not be called from the main thread. The block will be executed on the same thread as the caller.

Example usage:

onNodeWithTag("myWidget")
    .performGesture { swipeUp() }

onNodeWithTag("myWidget")
    .performGesture { click(center) }

onNodeWithTag("myWidget")
    .performGesture { down(topLeft) }
    .assertHasClickAction()
    .performGesture { up(topLeft) }

performImeAction

fun SemanticsNodeInteraction.performImeAction(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)

performKeyPress

fun SemanticsNodeInteraction.performKeyPress(keyEvent: KeyEvent): Boolean

Send the specified KeyEvent to the focused component.

Return
true if the event was consumed. False otherwise.

performPartialGesture

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

Deprecated.

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.

Example usage:

onNodeWithTag("myWidget")
   .performPartialGesture { down(topLeft) }
   .assertHasClickAction()
   .performPartialGesture { up(topLeft) }

performScrollTo

fun SemanticsNodeInteraction.performScrollTo(): SemanticsNodeInteraction

Scrolls to a node using SemanticsActions. It first identifies a parent semantics node with a Semantics ScrollBy 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 node with ScrollBy SemanticsAction, the current semantics node doesn't have a bounding rectangle set or if a layout node used to compute the relative coordinates to be fed to the ScrollBy action can't be found.

performSemanticsAction

fun <T : Function<Boolean>> SemanticsNodeInteraction.performSemanticsAction(
    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.

performSemanticsAction

fun SemanticsNodeInteraction.performSemanticsAction(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.

performTextClearance

fun SemanticsNodeInteraction.performTextClearance(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.

performTextInput

fun SemanticsNodeInteraction.performTextInput(
    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.

performTextReplacement

fun SemanticsNodeInteraction.performTextReplacement(
    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.

pinch

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

Performs a pinch gesture on the associated node.

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

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

printToLog

fun SemanticsNodeInteraction.printToLog(
    tag: String,
    @IntRange(0) maxDepth: Int = Int.MAX_VALUE
): Unit

Prints all the semantics nodes information into logs (as debug level).

By default this also prints all the sub-hierarchy. This can be changed by setting a custom max depth in maxDepth.

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.

Parameters
tag: String The tag to be used in the log messages.
maxDepth: Int = Int.MAX_VALUE Max depth of the nodes in hierarchy to print. Zero will print just this node.

printToLog

fun SemanticsNodeInteractionCollection.printToLog(
    tag: String,
    @IntRange(0) maxDepth: Int = 0
): Unit

Prints all the semantics nodes information into logs (as debug level).

By default this does not print nodes sub-hierarchies. This can be changed by setting a custom max depth in maxDepth.

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.

Parameters
tag: String The tag to be used in the log messages.
maxDepth: Int = 0 Max depth of the nodes in hierarchy to print. Zero will print nodes in this collection only.

printToString

fun SemanticsNodeInteraction.printToString(@IntRange(0) maxDepth: Int = Int.MAX_VALUE): String

Prints all the semantics nodes information it holds into string.

By default this also prints all the sub-hierarchy. This can be changed by setting a custom max depth in maxDepth.

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.

Parameters
maxDepth: Int = Int.MAX_VALUE Max depth of the nodes in hierarchy to print. Zero will print just this node.

printToString

fun SemanticsNodeInteractionCollection.printToString(@IntRange(0) maxDepth: Int = 0): String

Prints all the semantics nodes information it holds into string.

By default this does not print nodes sub-hierarchies. This can be changed by setting a custom max depth in maxDepth.

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.

Parameters
maxDepth: Int = 0 Max depth of the nodes in hierarchy to print. Zero will print nodes in this collection only.

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 GestureScope.sendCancel(): Unit

Deprecated.

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

Deprecated.

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

Deprecated.

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 GestureScope.sendDown(
    pointerId: Int,
    position: Offset
): Unit

Deprecated.

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 performGesture. 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 performGesture 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 GestureScope.sendDown(position: Offset): Unit

Deprecated.

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

Deprecated.

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 GestureScope.sendMove(): Unit

Deprecated.

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 GestureScope.sendMoveBy(
    pointerId: Int,
    delta: Offset
): Unit

Deprecated.

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 GestureScope.sendMoveBy(delta: Offset): Unit

Deprecated.

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 GestureScope.sendMoveTo(
    pointerId: Int,
    position: Offset
): Unit

Deprecated.

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 GestureScope.sendMoveTo(position: Offset): Unit

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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

Deprecated.

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, 3.4E38) endVelocity: Float,
    duration: Duration = 200.milliseconds
): Unit

Deprecated.

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 GestureScope.sendUp(pointerId: Int = 0): Unit

Deprecated.

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

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.

swipe

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

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

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

swipeDown

fun GestureScope.swipeDown(): Unit

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

swipeLeft

fun GestureScope.swipeLeft(): Unit

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

swipeRight

fun GestureScope.swipeRight(): Unit

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

swipeUp

fun GestureScope.swipeUp(): Unit

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

swipeWithVelocity

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

Performs the swipe gesture on the associated node, 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 node's local coordinate system, where (0, 0) is the top left corner of the node. 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 node's local coordinate system
end: Offset The end position of the gesture, in the node'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.

up

fun GestureScope.up(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 node. 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 down

Extension properties

bottom

inline val GestureScope.bottom: Float

Returns the y-coordinate for the bottom of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. 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 GestureScope.bottomCenter: Offset

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

bottomLeft

val GestureScope.bottomLeft: Offset

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

bottomRight

val GestureScope.bottomRight: Offset

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

center

val GestureScope.center: Offset

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

centerLeft

val GestureScope.centerLeft: Offset

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

centerRight

val GestureScope.centerRight: Offset

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

centerX

inline val GestureScope.centerX: Float

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

centerY

inline val GestureScope.centerY: Float

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

height

inline val GestureScope.height: Int

Shorthand for size.height

left

inline val GestureScope.left: Float

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

inline val GestureScope.right: Float

Returns the x-coordinate for the right edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. 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 GestureScope.size: IntSize

Returns the size of the node we're interacting with

top

inline val GestureScope.top: Float

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

topCenter

val GestureScope.topCenter: Offset

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

topLeft

val GestureScope.topLeft: Offset

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

topRight

val GestureScope.topRight: Offset

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

width

inline val GestureScope.width: Int

Shorthand for size.width