injecting-mouse-and-keyboard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Injecting Mouse and Keyboard — performMouseInput, performKeyInput, performMultiModalInput

注入鼠标和键盘——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.
在 Compose 测试中,鼠标和键盘输入都是一等输入模态。它们各自拥有独立的注入作用域和入口点,并共享一个
performMultiModalInput
,用于在一次批处理手势中组合所有输入方式(触摸、鼠标、按键、旋钮、触控板、间接指针)。坐标仍然是节点本地坐标——与触摸输入遵循相同规则——并且在同一节点的各个
perform.*Input
块之间,整个注入状态都会持续保留。

When to use this skill

何时使用此 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
    ".
  • 测试操作的是会响应点击、悬停、右键、滚轮或修饰键的桌面端或 Compose Multiplatform UI。
  • 测试必须驱动键盘快捷键(例如
    Ctrl+S
    、
    Shift+Tab
    、方向键导航)。
  • 测试必须验证仅由 hover 触发的行为:tooltip 弹出、
    Modifier.hoverable
    的颜色变化、仅由鼠标触发的 ripple 状态。
  • 测试模拟使用鼠标指针进行拖放。
  • 测试必须组合多种模态,例如“在 (x, y) 位置悬停,然后按住
    Shift
    的同时点击并保持”。

When NOT to use this skill

何时不应使用此 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
    .
  • 交互是手指点按或拖动——使用
    ../injecting-touch-gestures/SKILL.md
    。在 Android 设备测试中,鼠标不能与触摸等同看待。
  • 简单的
    performClick()
    已经会按平台选择正确的输入方式——使用
    ../clicking-and-scrolling/SKILL.md
    。
  • 测试需要向
    TextField
    输入文本——使用
    ../entering-text/SKILL.md
    。这里的按键输入用于快捷键,而不是文本输入。
  • 测试需要等待由 hover 驱动的动画结束——先按照
    ../../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.
  • 已按照
    ../../setup/configuring-test-dependencies/SKILL.md
    配置
    androidx.compose.ui:ui-test-junit4
    (或用于
    runComposeUiTest
    的
    ui-test
    )。
  • 对于 Android 上的鼠标 hover 事件:需要支持 hover 的 API level(通常为 API 23+)——Robolectric 宿主测试可用,但需检查
    @Config(minSdk = …)
    。
  • 对于目标是可聚焦节点的按键输入:节点必须可聚焦(例如使用
    Modifier.focusable()
    或
    Modifier.focusRequester(...)
    包装)。否则,按键事件会被路由到当前获得焦点的根节点。

Workflow

工作流

Mouse: performMouseInput

鼠标: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
    :
HelperDefaultWhat it does
click(position = center, button = MouseButton.Primary)
primary click at centerpress → 60 ms wait → release
rightClick(position = center)
secondary click at centershorthand for
click(position, MouseButton.Secondary)
doubleClick(position = center, button = Primary)
midway between min/max double-tap window
click(); advanceEventTime(delay); click()
tripleClick(position = center, button = Primary)
same delays as doublethree sequential clicks
longClick(position = center, button = Primary)
longPressTimeoutMillis + 100
ms hold
press, hold, release
animateMoveTo(position, durationMillis = 300)
300 msstreams move events along a linear path
animateMoveBy(delta, durationMillis = 300)
relative form—
animateMoveAlong(curve, durationMillis = 300)
arbitrary curve—
dragAndDrop(start, end, button = Primary, durationMillis = 300)
primary drag
updatePointerTo(start); press; animateMoveTo(end); release
smoothScroll(scrollAmount, durationMillis = 300, scrollWheel = Vertical)
verticalstreams scroll events
  1. 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.
  2. Reference
    MouseButton
    and
    ScrollWheel
    from
    Mouse.kt
    :
    • MouseButton.Primary
      ,
      MouseButton.Secondary
      ,
      MouseButton.Tertiary
      —
      expect value class MouseButton
      .
    • ScrollWheel.Vertical
      ,
      ScrollWheel.Horizontal
      —
      value class ScrollWheel
      .
  1. 打开鼠标作用域——
    performMouseInput(block: MouseInjectionScope.() -> Unit)
    (Actions.kt:448-461)。与触摸输入一样,事件会被批处理,并在块返回时统一提交;重组无法在块内部穿插执行。
  2. 使用节点本地坐标。
    (0, 0)
    是节点的左上角,与
    TouchInjectionScope
    完全相同。
    MouseInjectionScope
    继承
    InjectionScope
    ,因此可以使用
    center
    、
    topLeft
    、
    bottomRight
    、
    percentOffset(...)
    等全部能力(InjectionScope.kt:34-206)。
  3. 选择正确的辅助方法。 均位于
    MouseInjectionScope.kt
    中:
辅助方法默认行为作用
click(position = center, button = MouseButton.Primary)
在中心执行主键点击按下 → 等待 60 ms → 释放
rightClick(position = center)
在中心执行次键点击
click(position, MouseButton.Secondary)
的简写
doubleClick(position = center, button = Primary)
位于双击时间窗口最小值与最大值的中点
click(); advanceEventTime(delay); click()
tripleClick(position = center, button = Primary)
与双击使用相同的延迟连续执行三次点击
longClick(position = center, button = Primary)
按住
longPressTimeoutMillis + 100
ms
按下、保持、释放
animateMoveTo(position, durationMillis = 300)
300 ms沿线性路径流式发送移动事件
animateMoveBy(delta, durationMillis = 300)
相对位移形式—
animateMoveAlong(curve, durationMillis = 300)
任意曲线—
dragAndDrop(start, end, button = Primary, durationMillis = 300)
主键拖放
updatePointerTo(start); press; animateMoveTo(end); release
smoothScroll(scrollAmount, durationMillis = 300, scrollWheel = Vertical)
垂直滚动流式发送滚动事件
  1. 需要时下沉到低层级事件:
    • press(button: MouseButton = Primary)
      /
      release(button: MouseButton = Primary)
      。
    • moveTo(position, delayMillis = eventPeriodMillis)
      /
      moveBy(delta, delayMillis = eventPeriodMillis)
      。
    • updatePointerTo(position)
      /
      updatePointerBy(delta)
      ——仅调整位置,不发送事件。
    • enter(position)
      /
      exit(position)
      ——显式触发 hover 进入/退出。
    • scroll(delta, scrollWheel = Vertical)
      ——发送一次滚轮刻度事件。
    • cancel(delayMillis)
      ——发出一个
      ACTION_CANCEL
      。
    • currentPosition: Offset
      ——最后一个已知的鼠标位置。
  2. 从
    Mouse.kt
    引用
    MouseButton
    和
    ScrollWheel
    :
    • MouseButton.Primary
      、
      MouseButton.Secondary
      、
      MouseButton.Tertiary
      ——
      expect value class MouseButton
      。
    • ScrollWheel.Vertical
      、
      ScrollWheel.Horizontal
      ——
      value class ScrollWheel
      。

Keyboard: performKeyInput

键盘: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.
  1. 打开按键作用域——
    performKeyInput(block: KeyInjectionScope.() -> Unit)
    (Actions.kt:532-545)。
  2. 发送按键事件。 核心 API(KeyInjectionScope.kt:55-107):
    • keyDown(key: Key)
      /
      keyUp(key: Key)
      ——基础操作。如果状态无效(按键已按下或已释放),会抛出
      IllegalStateException
      。
    • isKeyDown(key: Key): Boolean
      ——查询注入状态。
    • 修饰键状态属性:
      isCtrlDown
      、
      isAltDown
      、
      isShiftDown
      、
      isMetaDown
      、
      isFnDown
      (KeyInjectionScope.kt:236-269),以及
      isCapsLockOn
      、
      isNumLockOn
      、
      isScrollLockOn
      (KeyInjectionScope.kt:64-81)。这些属性反映的是注入状态,而不是宿主机器的状态。
  3. 使用辅助方法(KeyInjectionScope.kt:146-229):
    • pressKey(key, pressDurationMillis = 50L)
      ——
      keyDown(key); advanceEventTime(50); keyUp(key)
      。
    • withKeyDown(key) { … }
      ——在按住
      key
      的同时运行
      block
      ;会在
      finally
      中自动释放。在
      block
      内不得再次使用这个处于按住状态的按键。
    • withKeysDown(listOf(key1, key2)) { … }
      ——与前者相同,但可同时按住多个按键。
    • withKeyToggled(key) { … }
      /
      withKeysToggled(keys) { … }
      ——在
      block
      前后各执行一次
      pressKey
      。适用于
      CapsLock
      、
      NumLock
      、
      ScrollLock
      。
  4. 按键重复行为。 按住某个键并推进事件时间(通过
    InjectionScope
    的
    advanceEventTime
    )会生成重复事件:首次重复在 500 ms 后触发,随后每 50 ms 触发一次(KeyInjectionScope.kt:43-50)。这不会由
    MainTestClock.advanceTimeBy
    触发——后者推进的是测试时钟,而不是注入事件时间。
  5. 直接注入 KeyEvent——
    SemanticsNodeInteraction.performKeyPress(KeyEvent): Boolean
    (KeyInputHelpers.kt:27)。如果事件已被消费则返回
    true
    。当已经拥有
    KeyEvent
    时使用它(例如通过
    KeyEvent(NativeKeyEvent(...))
    构造,以便精细控制 source/scancode);否则优先使用 DSL。

Multi-modal: performMultiModalInput

多模态: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.
  1. 打开多模态作用域——
    performMultiModalInput(block: MultiModalInjectionScope.() -> Unit)
    (Actions.kt:582-594)。
  2. 分发到子作用域——
    touch { … }
    、
    mouse { … }
    、
    key { … }
    、
    rotary { … }
    、
    trackpad { … }
    、
    indirectPointer(...)
    (MultiModalInjectionScope.kt:51-90)。所有子作用域共享同一注入状态,因此如果
    touch
    中有手指仍处于“按下”状态,那么随后执行
    mouse
    时它依然处于按下状态。
  3. 选择此入口点。 当单个测试步骤需要组合多种模态时,例如在按住 Shift 的同时进行 hover,应使用该入口点,而不是拼接两个独立的
    perform.*Input
    调用。

Patterns

模式

Pattern: Right-click menu

模式:右键菜单

kotlin
// 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.
kotlin
// RIGHT
rule.onNodeWithTag(RowTag).performMouseInput {
    rightClick(center)
}
rule.onNodeWithText("Delete").assertIsDisplayed()
rightClick
是
click(position, MouseButton.Secondary)
的简写(MouseInjectionScope.kt:356-357)。该方法出于直观性使用了“right”这一名称,但实际触发的是次要按钮——在左手鼠标上同样正确。

Pattern: Hover-driven tooltip

模式:由 hover 驱动的 tooltip

From
CombinedClickableTest.kt:3415-3422
:
kotlin
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.
来自
CombinedClickableTest.kt:3415-3422
:
kotlin
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)
发出 hover-enter 事件;
exit(position)
发出 hover-exit 事件。调用
exit
时传入节点外的
Offset(-1f, -1f)
,以模拟光标离开该表面。

Pattern: Ctrl+S shortcut — verbose vs idiomatic

模式:Ctrl+S 快捷键——冗长写法与惯用写法

kotlin
// WRONG
rule.onNodeWithTag(EditorTag).performKeyInput {
    keyDown(Key.CtrlLeft)
    pressKey(Key.S)
    keyUp(Key.CtrlLeft)
}
// WRONG because: a thrown assertion or early-return inside the block leaks Key.CtrlLeft
// in the "down" state, polluting subsequent tests. The release is not in a finally.
kotlin
// RIGHT
rule.onNodeWithTag(EditorTag).performKeyInput {
    withKeyDown(Key.CtrlLeft) {
        pressKey(Key.S)
    }
}
withKeyDown
releases the key in a
finally
block (KeyInjectionScope.kt:164-171). For multi-modifier shortcuts use
withKeysDown(listOf(Key.CtrlLeft, Key.ShiftLeft)) { pressKey(Key.S) }
.
kotlin
// WRONG
rule.onNodeWithTag(EditorTag).performKeyInput {
    keyDown(Key.CtrlLeft)
    pressKey(Key.S)
    keyUp(Key.CtrlLeft)
}
// WRONG because: a thrown assertion or early-return inside the block leaks Key.CtrlLeft
// in the "down" state, polluting subsequent tests. The release is not in a finally.
kotlin
// RIGHT
rule.onNodeWithTag(EditorTag).performKeyInput {
    withKeyDown(Key.CtrlLeft) {
        pressKey(Key.S)
    }
}
withKeyDown
会在
finally
块中释放按键(KeyInjectionScope.kt:164-171)。对于需要多个修饰键的快捷键,使用
withKeysDown(listOf(Key.CtrlLeft, Key.ShiftLeft)) { pressKey(Key.S) }
。

Pattern: Repeat-key autorepeat

模式:按键自动重复

kotlin
rule.onNodeWithTag(InputTag).performKeyInput {
    keyDown(Key.DirectionDown)
    advanceEventTime(800)   // 500 ms initial delay + 6 repeats at 50 ms
    keyUp(Key.DirectionDown)
}
advanceEventTime
is the input-dispatcher clock — it triggers repeat events at the documented cadence (first repeat at 500 ms, then every 50 ms — KeyInjectionScope.kt:43-50). MUST NOT substitute
rule.mainClock.advanceTimeBy(…)
: the main test clock advances Compose's frame clock, not the input dispatcher's event time, and no repeat events will be enqueued.
kotlin
rule.onNodeWithTag(InputTag).performKeyInput {
    keyDown(Key.DirectionDown)
    advanceEventTime(800)   // 500 ms initial delay + 6 repeats at 50 ms
    keyUp(Key.DirectionDown)
}
advanceEventTime
是 input dispatcher 的时钟——它按照文档规定的节奏触发重复事件(首次重复在 500 ms,随后每 50 ms 一次——KeyInjectionScope.kt:43-50)。绝不能使用
rule.mainClock.advanceTimeBy(…)
替代:主测试时钟推进的是 Compose 的帧时钟,而不是 input dispatcher 的事件时间,因此不会生成重复事件。

Pattern: Drag-and-drop with mouse

模式:使用鼠标进行拖放

kotlin
rule.onNodeWithTag(SourceTag).performMouseInput {
    dragAndDrop(
        start = center,
        end = Offset(center.x + 200f, center.y),
        durationMillis = 250,
    )
}
dragAndDrop
updates the pointer to
start
, presses, animates a move to
end
, then releases (MouseInjectionScope.kt:523-533). Default button is
MouseButton.Primary
; pass
button = MouseButton.Tertiary
for middle-click drag.
kotlin
rule.onNodeWithTag(SourceTag).performMouseInput {
    dragAndDrop(
        start = center,
        end = Offset(center.x + 200f, center.y),
        durationMillis = 250,
    )
}
dragAndDrop
会将指针更新到
start
,执行按下,以动画方式移动到
end
,然后释放(MouseInjectionScope.kt:523-533)。默认按键为
MouseButton.Primary
;传入
button = MouseButton.Tertiary
可使用中键进行拖放。

Pattern: Smooth scroll

模式:平滑滚动

kotlin
rule.onNodeWithTag(ScrollAreaTag).performMouseInput {
    smoothScroll(
        scrollAmount = -10f,                  // negative scrollAmount = scroll back; new content appears at the top (MouseInjectionScope.kt:537-542)
        durationMillis = 200,
        scrollWheel = ScrollWheel.Vertical,
    )
}
Positive
scrollAmount
reveals content from the bottom of a vertical column or from the end of a horizontal row (MouseInjectionScope.kt:537-542). For a single-tick wheel event, drop to
scroll(delta, scrollWheel)
.
kotlin
rule.onNodeWithTag(ScrollAreaTag).performMouseInput {
    smoothScroll(
        scrollAmount = -10f,                  // negative scrollAmount = scroll back; new content appears at the top (MouseInjectionScope.kt:537-542)
        durationMillis = 200,
        scrollWheel = ScrollWheel.Vertical,
    )
}
正的
scrollAmount
会显示垂直列底部或水平行末尾的内容(MouseInjectionScope.kt:537-542)。如果需要仅发送一次滚轮刻度事件,可下沉到
scroll(delta, scrollWheel)
。

Pattern: Multi-modal — hover then click while Shift held

模式:多模态——悬停后在按住 Shift 的同时点击

MultiModalInjectionScope
exposes
mouse { }
,
key { }
,
touch { }
etc. as sub-scopes; modifier-key state from one
key { withKeyDown(...) { } }
invocation persists across the rest of the surrounding
performMultiModalInput
, so a subsequent
mouse { }
block is dispatched while Shift is still down. The
withKeyDown
block itself has
KeyInjectionScope
as its receiver — calling
mouse { }
from inside it does not compile.
kotlin
rule.onNodeWithTag(NodeTag).performMultiModalInput {
    mouse { enter(center) }
    key { keyDown(Key.ShiftLeft) }
    mouse { click() }                 // dispatched with Shift still held
    key { keyUp(Key.ShiftLeft) }
}
A single
performMultiModalInput
keeps every modality in one batched flush; the modifier-key state, pointer position, and pressed buttons are shared across sub-scopes (MultiModalInjectionScope.kt). Use it when interleaving matters; otherwise two separate
performMouseInput
/
performKeyInput
calls are clearer.
MultiModalInjectionScope
暴露
mouse { }
、
key { }
、
touch { }
等子作用域;来自一次
key { withKeyDown(...) { } }
调用的修饰键状态,会在外围
performMultiModalInput
的剩余执行过程中持续存在,因此后续
mouse { }
块会在 Shift 仍被按住时分发。
withKeyDown
块本身的接收者是
KeyInjectionScope
——在它内部调用
mouse { }
无法通过编译。
kotlin
rule.onNodeWithTag(NodeTag).performMultiModalInput {
    mouse { enter(center) }
    key { keyDown(Key.ShiftLeft) }
    mouse { click() }                 // dispatched with Shift still held
    key { keyUp(Key.ShiftLeft) }
}
单次
performMultiModalInput
会将所有模态保持在一次批量提交中;修饰键状态、指针位置和已按下按钮会在各子作用域之间共享(MultiModalInjectionScope.kt)。当各模态确实需要交错时使用它;否则,分成两个独立的
performMouseInput
/
performKeyInput
调用会更清晰。

Pattern: Direct KeyEvent injection for precise control

模式:直接注入 KeyEvent 以实现精确控制

kotlin
import androidx.compose.ui.input.key.KeyEvent
import androidx.compose.ui.test.performKeyPress

val event = KeyEvent(NativeKeyEvent(NativeKeyEvent.ACTION_DOWN, NativeKeyEvent.KEYCODE_TAB))
rule.onRoot().performKeyPress(event)
performKeyPress
returns whether the event was consumed (
KeyInputHelpers.kt:27
). It bypasses the DSL — useful for replaying a captured
KeyEvent
or testing IME-derived keystrokes.
kotlin
import androidx.compose.ui.input.key.KeyEvent
import androidx.compose.ui.test.performKeyPress

val event = KeyEvent(NativeKeyEvent(NativeKeyEvent.ACTION_DOWN, NativeKeyEvent.KEYCODE_TAB))
rule.onRoot().performKeyPress(event)
performKeyPress
返回事件是否已被消费(KeyInputHelpers.kt:27)。它会绕过 DSL——适用于重放已捕获的
KeyEvent
,或测试由 IME 生成的按键输入。

Mandatory rules

强制规则

  • MUST wrap modifier-key shortcuts in
    withKeyDown
    /
    withKeysDown
    so the auto-release
    finally
    cleans up after a thrown assertion. Manual
    keyDown
    /
    keyUp
    pairs leak modifier state across tests.
  • MUST use
    advanceEventTime
    (the
    InjectionScope
    clock) — NOT
    MainTestClock.advanceTimeBy
    — when expecting key autorepeat events. Repeats are produced by the input dispatcher's event-time stream (KeyInjectionScope.kt:43-50).
  • MUST keep coordinates node-local using
    center
    ,
    topLeft
    ,
    bottomRight
    ,
    percentOffset(...)
    . Hardcoded screen coordinates make the test device-shaped — see
    ../injecting-touch-gestures/SKILL.md
    .
  • MUST funnel post-action assertions through
    rule.runOnIdle { … }
    (skydoves hot take #5).
  • MUST NOT use
    performMouseInput
    to test a finger tap on Android device tests —
    performClick()
    resolves to a touch tap on Android and a mouse click on desktop, automatically.
  • MUST NOT use
    Thread.sleep
    to wait between key or mouse events. Use
    advanceEventTime
    inside the block (event-time delay) or
    mainClock.advanceTimeBy
    outside it (frame clock delay).
  • PREFERRED: select
    performMultiModalInput
    only when modalities truly interleave; otherwise separate
    performMouseInput
    and
    performKeyInput
    calls read better.
  • 必须将修饰键快捷键包裹在
    withKeyDown
    /
    withKeysDown
    中,使自动释放逻辑能够在断言抛出后通过
    finally
    完成清理。手动配对
    keyDown
    /
    keyUp
    会让修饰键状态泄漏到后续测试中。
  • 必须使用
    advanceEventTime
    (
    InjectionScope
    时钟),而不是
    MainTestClock.advanceTimeBy
    ,以期望生成按键自动重复事件。重复事件由 input dispatcher 的事件时间流生成(KeyInjectionScope.kt:43-50)。
  • 必须使用
    center
    、
    topLeft
    、
    bottomRight
    、
    percentOffset(...)
    等方式保持坐标为节点本地坐标。硬编码屏幕坐标会使测试受设备形状影响——参见
    ../injecting-touch-gestures/SKILL.md
    。
  • 必须将操作后的断言放入
    rule.runOnIdle { … }
    中执行(skydoves 热辣观点 #5)。
  • 不得在 Android 设备测试中使用
    performMouseInput
    测试手指点按——
    performClick()
    会在 Android 上解析为触摸点按,在桌面端解析为鼠标点击,并且会自动完成选择。
  • 不得使用
    Thread.sleep
    等待按键或鼠标事件。在块内部使用
    advanceEventTime
    (事件时间延迟),或在块外部使用
    mainClock.advanceTimeBy
    (帧时钟延迟)。
  • **推荐:**仅当各模态确实需要交错时选择
    performMultiModalInput
    ;否则,分开的
    performMouseInput
    和
    performKeyInput
    调用更易阅读。

Verification

验证

  • Every modifier-key combo uses
    withKeyDown
    /
    withKeysDown
    rather than raw
    keyDown
    /
    keyUp
    pairs.
  • No
    Thread.sleep
    between or inside
    performMouseInput
    /
    performKeyInput
    blocks.
  • No hardcoded screen coordinates — every
    Offset(...)
    is derived from
    center
    ,
    top*
    ,
    bottom*
    ,
    percentOffset(...)
    , or relative deltas.
  • Tests asserting key autorepeat behaviour use
    advanceEventTime
    , not
    mainClock.advanceTimeBy
    .
  • Assertions following an action run inside
    rule.runOnIdle { … }
    .
  • ./gradlew :app:connectedDebugAndroidTest
    (or the equivalent host / desktop task) passes for the test under change.
  • 每个修饰键组合都使用
    withKeyDown
    /
    withKeysDown
    ,而不是原始的
    keyDown
    /
    keyUp
    配对。
  • 在
    performMouseInput
    /
    performKeyInput
    块内部或块之间都没有使用
    Thread.sleep
    。
  • 没有硬编码屏幕坐标——每个
    Offset(...)
    都派生自
    center
    、
    top*
    、
    bottom*
    、
    percentOffset(...)
    或相对位移。
  • 断言按键自动重复行为时使用
    advanceEventTime
    ,而不是
    mainClock.advanceTimeBy
    。
  • 操作后的断言在
    rule.runOnIdle { … }
    中运行。
  • ./gradlew :app:connectedDebugAndroidTest
    (或等效的宿主/桌面端任务)能够通过本次修改涉及的测试。

References

参考资料

  • Compose testing overview: https://developer.android.com/develop/ui/compose/testing
  • Compose Multiplatform testing: https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-test.html
  • Compose testing cheat sheet: https://developer.android.com/develop/ui/compose/testing-cheatsheet
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/Actions.kt
    —
    performMouseInput
    (Actions.kt:448),
    performKeyInput
    (Actions.kt:532),
    performMultiModalInput
    (Actions.kt:582),
    performTrackpadInput
    ,
    performRotaryScrollInput
    .
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/MouseInjectionScope.kt
    —
    press
    ,
    release
    ,
    moveTo
    ,
    moveBy
    ,
    enter
    ,
    exit
    ,
    scroll
    ,
    cancel
    , plus extensions
    click
    ,
    rightClick
    ,
    doubleClick
    ,
    tripleClick
    ,
    longClick
    ,
    animateMoveTo
    ,
    animateMoveBy
    ,
    animateMoveAlong
    ,
    dragAndDrop
    ,
    smoothScroll
    .
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/KeyInjectionScope.kt
    —
    keyDown
    ,
    keyUp
    ,
    isKeyDown
    , modifier-state vals,
    pressKey
    ,
    withKeyDown
    ,
    withKeysDown
    ,
    withKeyToggled
    ,
    withKeysToggled
    , repeat-key contract.
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/KeyInputHelpers.kt
    —
    performKeyPress(KeyEvent): Boolean
    (KeyInputHelpers.kt:27).
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/Mouse.kt
    —
    MouseButton.Primary
    /
    Secondary
    /
    Tertiary
    ,
    ScrollWheel.Horizontal
    /
    Vertical
    .
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/MultiModalInjectionScope.kt
    —
    touch
    ,
    mouse
    ,
    key
    ,
    rotary
    ,
    trackpad
    ,
    indirectPointer
    .
  • compose/foundation/foundation/src/androidDeviceTest/.../CombinedClickableTest.kt
    —
    performMouseInput { enter(center) }
    ,
    performMouseInput { exit(Offset(-1f, -1f)) }
    (CombinedClickableTest.kt:3415-3422).
  • skydoves — compose-performance-skills: https://github.com/skydoves/compose-performance-skills
  • Compose 测试概览:https://developer.android.com/develop/ui/compose/testing
  • Compose Multiplatform 测试:https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-test.html
  • Compose 测试速查表:https://developer.android.com/develop/ui/compose/testing-cheatsheet
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/Actions.kt
    ——
    performMouseInput
    (Actions.kt:448)、
    performKeyInput
    (Actions.kt:532)、
    performMultiModalInput
    (Actions.kt:582)、
    performTrackpadInput
    、
    performRotaryScrollInput
    。
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/MouseInjectionScope.kt
    ——
    press
    、
    release
    、
    moveTo
    、
    moveBy
    、
    enter
    、
    exit
    、
    scroll
    、
    cancel
    ,以及扩展函数
    click
    、
    rightClick
    、
    doubleClick
    、
    tripleClick
    、
    longClick
    、
    animateMoveTo
    、
    animateMoveBy
    、
    animateMoveAlong
    、
    dragAndDrop
    、
    smoothScroll
    。
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/KeyInjectionScope.kt
    ——
    keyDown
    、
    keyUp
    、
    isKeyDown
    、修饰键状态属性、
    pressKey
    、
    withKeyDown
    、
    withKeysDown
    、
    withKeyToggled
    、
    withKeysToggled
    、按键重复行为约定。
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/KeyInputHelpers.kt
    ——
    performKeyPress(KeyEvent): Boolean
    (KeyInputHelpers.kt:27)。
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/Mouse.kt
    ——
    MouseButton.Primary
    /
    Secondary
    /
    Tertiary
    ,
    ScrollWheel.Horizontal
    /
    Vertical
    。
  • compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/MultiModalInjectionScope.kt
    ——
    touch
    、
    mouse
    、
    key
    、
    rotary
    、
    trackpad
    、
    indirectPointer
    。
  • compose/foundation/foundation/src/androidDeviceTest/.../CombinedClickableTest.kt
    ——
    performMouseInput { enter(center) }
    、
    performMouseInput { exit(Offset(-1f, -1f)) }
    (CombinedClickableTest.kt:3415-3422)。
  • skydoves——compose-performance-skills:https://github.com/skydoves/compose-performance-skills