MouseInjectionScope

fun cancel(delayMillis: Long = eventPeriodMillis): Unit

Sends a cancel event delayMillis after the last sent event to cancel a stream of mouse events with pressed mouse buttons. All buttons will be released as a result. A mouse cancel event can only be sent when mouse buttons are pressed.

fun enter(
    position: Offset = currentPosition,
    delayMillis: Long = eventPeriodMillis
): Unit

Sends a hover enter event at the given position, delayMillis after the last sent event, without sending a hover move event.

An IllegalStateException will be thrown when mouse buttons are down, or if the mouse is already hovering.

The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Note: enter and exit events are already sent as a side effect of movement when necessary. Whether or not this is part of the contract of mouse events is platform dependent, so it is highly discouraged to manually send enter or exit events. Only use this method for tests that need to make assertions about a component's state in between the enter/exit and move event.

fun exit(position: Offset = currentPosition, delayMillis: Long = eventPeriodMillis): Unit

Sends a hover exit event at the given position, delayMillis after the last sent event, without sending a hover move event.

An IllegalStateException will be thrown if the mouse was not hovering.

The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Note: enter and exit events are already sent as a side effect of movement when necessary. Whether or not this is part of the contract of mouse events is platform dependent, so it is highly discouraged to manually send enter or exit events. Only use this method for tests that need to make assertions about a component's state in between the enter/exit and move event.

open fun moveBy(delta: Offset, delayMillis: Long = eventPeriodMillis): Unit

Sends a move event delayMillis after the last sent event on the associated node, with the position of the mouse moved by the given delta.

If no mouse buttons are pressed, a hover event will be sent instead of a move event. If the mouse wasn't hovering yet, a hover enter event is sent as well.

fun moveTo(position: Offset, delayMillis: Long = eventPeriodMillis): Unit

Sends a move event delayMillis after the last sent event on the associated node, with the position of the mouse 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 no mouse buttons are pressed, a hover event will be sent instead of a move event. If the mouse wasn't hovering yet, a hover enter event is sent as well.

fun press(button: MouseButton = MouseButton.Primary): Unit

Sends a down and button pressed event for the given button on the associated node. When no buttons were down yet, this will exit hovering mode before the button is pressed. All events will be sent at the current event time.

Throws an IllegalStateException if the button is already pressed.

fun release(button: MouseButton = MouseButton.Primary): Unit

Sends a button released and up event for the given button on the associated node. If this was the last button to be released, the mouse will enter hovering mode and send an accompanying mouse move event after the button has been released. All events will be sent at the current event time.

Throws an IllegalStateException if the button is not pressed.

open fun scroll(offset: Offset): Unit

Sends a scroll event with the given offset. The event will be sent at the current event time.

This is a 2 dimensional version of scroll and therefore will apply to a 2d plane. It combines the delta and the scrollWheel directionality in a single offset representation. A positive X component implies moving forward on the horizontal axis. A positive Y component implies moving forward on the vertical axis. A negative component means moving backwards. A combination of positive and negative components will yield an angled movement in a given quadrant of the 2d plane. For instance, moving with offset (100, -100) will move on the equivalent of 100 pixels forward on the horizontal axis and 100 pixels backward on the vertical axis.

Note that the correlation between scroll offset and pixels scrolled is platform specific. For example, on Android a scroll delta of 1f corresponds to a scroll of 64.dp. However, on any platform, this conversion factor could change in the future to improve the mouse scroll experience.

Example of how scroll could be used:

import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule
    .onNodeWithTag("verticalScrollable")
    // Scroll downwards while keeping a button pressed:
    .performMouseInput {
        // Presses the primary mouse button
        press()
        // Scroll the scroll wheel by 6 units
        repeat(6) {
            advanceEventTime()
            scroll(1f)
        }
        // And release the mouse button
        advanceEventTime()
        release()
    }

fun scroll(delta: Float, scrollWheel: ScrollWheel = ScrollWheel.Vertical): Unit

Sends a scroll event with the given delta on the given scrollWheel. The event will be sent at the current event time.

Positive delta values correspond to scrolling forward (new content appears at the bottom of a column, or at the end of a row), negative values correspond to scrolling backward (new content appears at the top of a column, or at the start of a row).

Note that the correlation between scroll delta and pixels scrolled is platform specific. For example, on Android a scroll delta of 1f corresponds to a scroll of 64.dp. However, on any platform, this conversion factor could change in the future to improve the mouse scroll experience.

Example of how scroll could be used:

import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule
    .onNodeWithTag("verticalScrollable")
    // Scroll downwards while keeping a button pressed:
    .performMouseInput {
        // Presses the primary mouse button
        press()
        // Scroll the scroll wheel by 6 units
        repeat(6) {
            advanceEventTime()
            scroll(1f)
        }
        // And release the mouse button
        advanceEventTime()
        release()
    }

open fun updatePointerBy(delta: Offset): Unit

Updates the position of the mouse by the given delta, but does not send a move or hover event. This can be useful to adjust the mouse position before sending for example a press event.

fun updatePointerTo(position: Offset): Unit

Updates the position of the mouse to the given position, but does not send a move or hover event. This can be useful to adjust the mouse position before sending for example a press event. The position is in the node's local coordinate system, where (0.px, 0.px) is the top left corner of the node.

val currentPosition: Offset

Returns the current position of the mouse. The position is returned in the local coordinate system of the node with which we're interacting. (0, 0) is the top left corner of the node. If none of the move or updatePointer methods have been used yet, the mouse's position will be (0, 0) in the Compose host's coordinate system, which will be -[topLeft] in the node's local coordinate system.

fun MouseInjectionScope.animateMoveAlong(
    curve: (timeMillis: Long) -> Offset,
    durationMillis: Long = DefaultMouseGestureDurationMillis
): Unit

Move the mouse along the given curve, sending a stream of move events to get an animated path of durationMillis milliseconds. The mouse will initially be moved to the start of the path, curve(0), if it is not already there. The positions defined by the curve are in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Example of moving the mouse along a curve:

import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.test.animateMoveAlong
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule.onNodeWithTag("myComponent").performMouseInput {
    // Hover over the node, making a full circle with a radius of 100px
    val r = 100f
    animateMoveAlong(
        curve = {
            val angle = 2 * PI * it / 1000
            center + Offset(r * cos(angle).toFloat(), r * sin(angle).toFloat())
        },
        durationMillis = 1000L,
    )
}

fun MouseInjectionScope.animateMoveBy(
    delta: Offset,
    durationMillis: Long = DefaultMouseGestureDurationMillis
): Unit

Move the mouse from the current position by the given delta, sending a stream of move events to get an animated path of durationMillis milliseconds.

fun MouseInjectionScope.animateMoveTo(
    position: Offset,
    durationMillis: Long = DefaultMouseGestureDurationMillis
): Unit

Move the mouse from the current position to the given position, sending a stream of move events to get an animated path of durationMillis milliseconds. Move the mouse to the desired start position if you want to start from a different position. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Example of moving the mouse along a line:

import androidx.compose.ui.test.animateMoveTo
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule.onNodeWithTag("myComponent").performMouseInput {
    // Hover over the node, making an X shape
    moveTo(topLeft)
    animateMoveTo(bottomRight)
    // Note that an actual user wouldn't be able to instantly
    // move from the bottom right to the top right
    moveTo(topRight)
    animateMoveTo(bottomLeft)
}

fun MouseInjectionScope.click(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to click on position, or on the current mouse position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button. There is a small 60ms delay between the press and release events to have a realistic simulation.

fun MouseInjectionScope.doubleClick(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to double-click on position, or on the current mouse position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button.

fun MouseInjectionScope.dragAndDrop(
    start: Offset,
    end: Offset,
    button: MouseButton = MouseButton.Primary,
    durationMillis: Long = DefaultMouseGestureDurationMillis
): Unit

Use button to drag and drop something from start to end in durationMillis milliseconds. The mouse position is updated to the start position before starting the gesture. The positions defined by the start and end are in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun MouseInjectionScope.longClick(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to long-click on position, or on the current mouse position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button.

fun MouseInjectionScope.rightClick(position: Offset = center): Unit

Secondary-click on position, or on the current mouse position if position is unspecified. While the secondary mouse button is not necessarily the right mouse button (e.g. on left-handed mice), this method is still called rightClick for it's widespread use. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun MouseInjectionScope.smoothScroll(
    scrollAmount: Float,
    durationMillis: Long = DefaultMouseGestureDurationMillis,
    scrollWheel: ScrollWheel = ScrollWheel.Vertical
): Unit

Rotate the mouse's scrollWheel by the given scrollAmount. The total scroll delta is linearly smoothed out over a stream of scroll events between each scroll event.

Positive scrollAmount values correspond to scrolling forward (new content appears at the bottom of a column, or at the end of a row), negative values correspond to scrolling backward (new content appears at the top of a column, or at the start of a row).

Example of a horizontal smooth scroll:

import androidx.compose.ui.test.ScrollWheel
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput
import androidx.compose.ui.test.smoothScroll

composeTestRule.onNodeWithTag("horizontalScrollable").performMouseInput {
    // Scroll forwards horizontally, which is rightwards
    // unless scroll direction is reversed
    smoothScroll(100f, durationMillis = 500L, ScrollWheel.Horizontal)
    // The 100f scroll delta is equally divided into smaller scrolls,
    // such that the time in between two scroll events is more or less
    // equal to the default time between events, 16ms.
}

fun MouseInjectionScope.tripleClick(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to triple-click on position, or on the current mouse position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button.