Injecting Touch Gestures

Injecting Touch Gestures — performTouchInput, Not performGesture

performTouchInput { … } is the single entry point for synthetic touch events in Compose tests. It runs a block in a TouchInjectionScope whose coordinate system is node-local (origin at the node's top-left), batches every event the block enqueues, and flushes them as a single non-recomposing burst when the block returns. The legacy performGesture { … } is @Deprecated("Replaced by performTouchInput") (Actions.kt:337-355) — MUST NOT appear in any new code.

When to use this skill

• The test must simulate a partial gesture, multi-touch, fling with controlled velocity, or pinch-to-zoom — anything richer than a single tap.
• The developer needs precise coordinates relative to a node (e.g. drag by exactly 100 px from center).
• A gesture must be split across two performTouchInput blocks while a finger is still "down".
• A test currently uses performGesture { } and must be migrated.
• A test simulates touch with hardcoded screen coordinates and is flaky on different display sizes.

When NOT to use this skill

• A simple tap on a node — use performClick() from ../clicking-and-scrolling/SKILL.md. It is platform-appropriate and shorter.
• The gesture is a hover, right-click, or scroll wheel — use ../injecting-mouse-and-keyboard/SKILL.md.
• The flow is "tap a button, then assert a Snackbar appears" — assert via ../../assertions/asserting-node-state-and-text/SKILL.md, not by inspecting touch state.
• The test is fighting a fling animation — 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.
• The receiver node carries Modifier.testTag("…") from production code so the test selects it deterministically.
• For multi-touch gestures (pinch, multiTouchSwipe), the target composable accepts pointer input via Modifier.pointerInput { … } — typically Modifier.transformable, Modifier.draggable2D, or a custom detectTransformGestures.

Workflow

1. Acquire the receiver. performTouchInput is an extension on SemanticsNodeInteraction. Find the node first.

rule.onNodeWithTag(DragSurfaceTag).performTouchInput { /* DSL */ }

2. Use node-local coordinates. Inside the block, (0, 0) is the node's top-left. Reach for the geometry helpers from InjectionScope (InjectionScope.kt:34-206): center, topLeft, topCenter, topRight, centerLeft, centerRight, bottomLeft, bottomCenter, bottomRight, width, height, plus right == width - 1f and bottom == height - 1f (pixels are 0-based — InjectionScope.kt:96-112). Use percentOffset(.5f, .5f) for relative positioning. MUST NOT hardcode screen coordinates.

3. Pick the right level of abstraction. High-level helpers cover most cases:

4. Drop to low-level events for partial gestures. All in TouchInjectionScope (TouchInjectionScope.kt):

   • down(pointerId = 0, position) — start a pointer at position.
   • moveTo(pointerId = 0, position, delayMillis = eventPeriodMillis) — enqueue a move event.
   • moveBy(pointerId = 0, delta, delayMillis = eventPeriodMillis) — relative form.
   • updatePointerTo(pointerId, position) / updatePointerBy(pointerId, delta) — adjust the pointer position without enqueueing a move; useful when batching multiple pointer updates into a single move(delayMillis) call.
   • move(delayMillis = eventPeriodMillis) — flush a move event combining every pending pointer update.
   • up(pointerId = 0) — release.
   • cancel(delayMillis = eventPeriodMillis) — emit a MotionEvent.ACTION_CANCEL-equivalent.
   • currentPosition(pointerId = 0): Offset? — query the last-known position of a pointer.

5. Split gestures across blocks when recomposition matters mid-gesture. Pointer state is shared across performTouchInput invocations on the same node — a pointer left "down" stays down. Use this to assert state at a frame the gesture passes through.

rule.onNodeWithTag(Tag).performTouchInput { down(center) }
// recomposition + assertions happen here
rule.onNodeWithTag(Tag).performTouchInput { moveBy(Offset(0f, 100f)); up() }

Subsequent invocations on a different node remap pointer positions into that node's local space (TouchInjectionScope.kt:50-55), so positions are still local, not screen-global.

6. Trust event batching. Every event enqueued inside one performTouchInput block is sent as one batch when the block returns; recomposition cannot interleave inside a block (Actions.kt:362-377). That is why all coordinates are resolved up front — and why a moving target does not invalidate the gesture inside one block.

Patterns

Pattern: Replace performGesture with performTouchInput

// WRONG
@Suppress("DEPRECATION")
rule.onNodeWithTag(Tag).performGesture { swipeUp() }
// WRONG because: performGesture is @Deprecated("Replaced by performTouchInput") (Actions.kt:337).
// The replaceWith metadata in the @Deprecated annotation explicitly suggests performTouchInput.

// RIGHT
rule.onNodeWithTag(Tag).performTouchInput { swipeUp() }

This is a non-negotiable migration. performGesture exists only for binary compatibility.