Injecting Mouse And Keyboard

Injecting Mouse and Keyboard — performMouseInput, performKeyInput, performMultiModalInput

Mouse and keyboard input are first-class modalities in Compose tests. Each has its own injection scope and entry point, plus a shared performMultiModalInput that combines all of them inside one batched gesture (touch, mouse, key, rotary, trackpad, indirect pointer). Coordinates remain node-local — the same rules as touch — and the entire injection state survives across perform.*Input blocks on the same node.

When to use this skill

• The test exercises a desktop or Compose Multiplatform UI that responds to clicks, hover, right-click, scroll wheel, or modifier keys.
• The test must drive a keyboard shortcut (e.g. Ctrl+S, Shift+Tab, arrow-key navigation).
• The test must verify hover-only behaviour: tooltip pop, color change on Modifier.hoverable, mouse-only ripple state.
• The test simulates a drag-and-drop with a mouse pointer.
• The test must combine modalities — for example "hover at (x, y) then click and hold while pressing Shift".

When NOT to use this skill

• The interaction is a finger tap or drag — use ../injecting-touch-gestures/SKILL.md. Mouse is not interchangeable with touch on Android device tests.
• A simple performClick() already routes through the right modality per platform — use ../clicking-and-scrolling/SKILL.md.
• The test types into a TextField — use ../entering-text/SKILL.md. Key input here is for shortcuts, not text entry.
• The test waits for a hover-driven animation to settle — pause the clock first per ../../synchronization/testing-animations-deterministically/SKILL.md.

Prerequisites

• androidx.compose.ui:ui-test-junit4 (or ui-test for runComposeUiTest) configured per ../../setup/configuring-test-dependencies/SKILL.md.
• For mouse hover events on Android: API level that supports hover (typically API 23+) — Robolectric host tests work but check @Config(minSdk = …).
• For key input that targets a focusable node: the node must be focusable (e.g. wrapped in Modifier.focusable() or Modifier.focusRequester(...)). Otherwise key events route to the focused root.

Workflow

Mouse: performMouseInput

1. Open a mouse scope — performMouseInput(block: MouseInjectionScope.() -> Unit) (Actions.kt:448-461). Like touch, events are batched and flushed when the block returns; recomposition cannot interleave inside the block.

2. Use node-local coordinates. (0, 0) is the node's top-left, identical to TouchInjectionScope. MouseInjectionScope extends InjectionScope so center, topLeft, bottomRight, percentOffset(...) are all available (InjectionScope.kt:34-206).

3. Pick the right helper. All in MouseInjectionScope.kt:

4. Drop to low-level events when needed:

   • press(button: MouseButton = Primary) / release(button: MouseButton = Primary).
   • moveTo(position, delayMillis = eventPeriodMillis) / moveBy(delta, delayMillis = eventPeriodMillis).
   • updatePointerTo(position) / updatePointerBy(delta) — adjust position without sending an event.
   • enter(position) / exit(position) — explicit hover-enter / hover-exit.
   • scroll(delta, scrollWheel = Vertical) — single wheel tick.
   • cancel(delayMillis) — emit an ACTION_CANCEL.
   • currentPosition: Offset — last known mouse position.

5. Reference MouseButton and ScrollWheel from Mouse.kt:

   • MouseButton.Primary, MouseButton.Secondary, MouseButton.Tertiary — expect value class MouseButton.
   • ScrollWheel.Vertical, ScrollWheel.Horizontal — value class ScrollWheel.

Keyboard: performKeyInput

1. Open a key scope — performKeyInput(block: KeyInjectionScope.() -> Unit) (Actions.kt:532-545).

2. Send key events. Core surface (KeyInjectionScope.kt:55-107):

   • keyDown(key: Key) / keyUp(key: Key) — primitives. Throw IllegalStateException if state is invalid (already-down, already-up).
   • isKeyDown(key: Key): Boolean — query injection state.
   • Modifier-state vals: isCtrlDown, isAltDown, isShiftDown, isMetaDown, isFnDown (KeyInjectionScope.kt:236-269), isCapsLockOn, isNumLockOn, isScrollLockOn (KeyInjectionScope.kt:64-81). These reflect the injected state, not the host machine.

3. Use the helpers (KeyInjectionScope.kt:146-229):

   • pressKey(key, pressDurationMillis = 50L) — keyDown(key); advanceEventTime(50); keyUp(key).
   • withKeyDown(key) { … } — runs block while key is held; auto-releases in finally. The held key MUST NOT be used inside block.
   • withKeysDown(listOf(key1, key2)) { … } — same but multiple keys held simultaneously.
   • withKeyToggled(key) { … } / withKeysToggled(keys) { … } — pressKey before and after block. Useful for CapsLock, NumLock, ScrollLock.

4. Repeat-key behavior. Holding a key down and advancing the event time (via advanceEventTime from InjectionScope) produces repeat events: the first repeat fires after 500 ms, then every 50 ms (KeyInjectionScope.kt:43-50). This is NOT triggered by MainTestClock.advanceTimeBy — that one advances the test clock, not the injection event time.

5. Direct KeyEvent injection — SemanticsNodeInteraction.performKeyPress(KeyEvent): Boolean from KeyInputHelpers.kt:27. Returns true if the event was consumed. Use it when you already have a KeyEvent (e.g. constructed via KeyEvent(NativeKeyEvent(...)) for fine-grained source/scancode control); otherwise prefer the DSL.

Multi-modal: performMultiModalInput

1. Open a multi-modal scope — performMultiModalInput(block: MultiModalInjectionScope.() -> Unit) (Actions.kt:582-594).

2. Dispatch into sub-scopes — touch { … }, mouse { … }, key { … }, rotary { … }, trackpad { … }, indirectPointer(...) (MultiModalInjectionScope.kt:51-90). All sub-scopes share the same injection state, so a finger left "down" in touch is still down when mouse runs next.

3. Pick this entry point when a single test step combines modalities — e.g. hover-while-shift-held — instead of stitching together two separate perform.*Input calls.

Patterns

Pattern: Right-click menu

// RIGHT
rule.onNodeWithTag(RowTag).performMouseInput {
    rightClick(center)
}
rule.onNodeWithText("Delete").assertIsDisplayed()

rightClick is shorthand for click(position, MouseButton.Secondary) (MouseInjectionScope.kt:356-357). The label says "right" for familiarity, but it actually triggers the secondary button — correct on left-handed mice as well.

Pattern: Hover-driven tooltip

From CombinedClickableTest.kt:3415-3422:

rule.onNodeWithTag("myClickable").performMouseInput { enter(center) }

rule.runOnIdle {
    assertThat(interactions).hasSize(1)
    assertThat(interactions.first()).isInstanceOf(HoverInteraction.Enter::class.java)
}

rule.onNodeWithTag("myClickable").performMouseInput { exit(Offset(-1f, -1f)) }

enter(position) emits a hover-enter; exit(position) emits a hover-exit. Pass an off-node Offset(-1f, -1f) to exit to mimic the cursor leaving the surface.