feat: group gesture commands

Author: thymikee

examples/test-app/README.md

@@ -88,8 +88,9 @@ pnpm test-app:replay:android
 
 These run the `.ad` replay suite in `examples/test-app/replays`.
 
-`gesture-lab.ad` is iOS-only and verifies `pan`, `fling`, `pinch`, and
-`rotate-gesture` against the gesture metrics rendered by the Home screen.
+`gesture-lab.ad` is iOS-only and verifies `gesture pan`, `gesture fling`,
+`gesture pinch`, and `gesture rotate` against the gesture metrics rendered by
+the Home screen.
 
 To target a specific iOS simulator or an installed Expo development build, run the
 underlying command directly so global flags stay before replay inputs:

examples/test-app/replays/gesture-lab.ad

@@ -6,34 +6,34 @@ env APP_URL=""
 open "${APP_TARGET}" --relaunch --launch-url "${APP_URL}"
 wait "Gesture lab" 30000
 
-fling left 195 443 180
+gesture fling left 195 443 180
 wait "fling 1" 5000
 
-fling right 195 443 180
+gesture fling right 195 443 180
 wait "fling 2" 5000
 
-fling up 195 443 80 80
+gesture fling up 195 443 80 80
 wait "fling 3" 5000
 
-fling down 195 443 80 80
+gesture fling down 195 443 80 80
 wait "fling 4" 5000
 
-pan 195 443 -80 0
+gesture pan 195 443 -80 0
 wait "x -" 5000
 
-pan 195 443 160 0
+gesture pan 195 443 160 0
 wait "x 72" 5000
 
-pan 195 443 0 -80
+gesture pan 195 443 0 -80
 wait "y -" 5000
 
-pan 195 443 0 160
+gesture pan 195 443 0 160
 wait "y 56" 5000
 
-pinch 1.25 195 443
+gesture pinch 1.25 195 443
 wait "pinch changed yes" 5000
 
-rotate-gesture 35 195 443
+gesture rotate 35 195 443
 wait "rotate changed yes" 5000
 
 close

scripts/integration-progress.mjs

@@ -488,17 +488,17 @@ function summarizeCommandFamilyOwnership(files) {
       commands: ['snapshot', 'diff', 'screenshot'],
     },
     {
-      name: 'press/click/fill/type/scroll/swipe/pinch/rotate/app-switcher',
+      name: 'press/click/fill/type/scroll/swipe/gesture/rotate/app-switcher',
       commands: [
         'press',
         'click',
         'focus',
         'longpress',
         'swipe',
         'scroll',
+        'gesture',
         'type',
         'fill',
-        'pinch',
         'rotate',
         'app-switcher',
         'back',
@@ -609,7 +609,10 @@ function extractProviderScenarioCommandReferences(text) {
     ['interactions.get', 'get'],
     ['interactions.is', 'is'],
     ['interactions.longPress', 'longpress'],
-    ['interactions.pinch', 'pinch'],
+    ['interactions.pan', 'gesture'],
+    ['interactions.fling', 'gesture'],
+    ['interactions.pinch', 'gesture'],
+    ['interactions.rotateGesture', 'gesture'],
     ['interactions.press', 'press'],
     ['interactions.scroll', 'scroll'],
     ['interactions.swipe', 'swipe'],

src/cli/commands/generic.ts

@@ -111,23 +111,11 @@ const genericClientCommandRunners = {
       pauseMs: flags.pauseMs,
       pattern: flags.pattern,
     }),
-  pan: ({ client, positionals, flags }) =>
-    client.interactions.pan({
-      ...buildSelectionOptions(flags),
-      x: Number(positionals[0]),
-      y: Number(positionals[1]),
-      dx: Number(positionals[2]),
-      dy: Number(positionals[3]),
-      durationMs: optionalNumber(positionals[4]),
-    }),
-  fling: ({ client, positionals, flags }) =>
-    client.interactions.fling({
-      ...buildSelectionOptions(flags),
-      direction: readGestureDirection(positionals[0], 'fling'),
-      x: Number(positionals[1]),
-      y: Number(positionals[2]),
-      distance: optionalNumber(positionals[3]),
-      durationMs: optionalNumber(positionals[4]),
+  gesture: ({ client, positionals, flags }) =>
+    runGestureCommand({
+      client,
+      positionals,
+      flags,
     }),
   focus: ({ client, positionals, flags }) =>
     client.interactions.focus({
@@ -153,21 +141,6 @@ const genericClientCommandRunners = {
       amount: optionalNumber(positionals[1]),
       pixels: flags.pixels,
     }),
-  pinch: ({ client, positionals, flags }) =>
-    client.interactions.pinch({
-      ...buildSelectionOptions(flags),
-      scale: Number(positionals[0]),
-      x: optionalNumber(positionals[1]),
-      y: optionalNumber(positionals[2]),
-    }),
-  'rotate-gesture': ({ client, positionals, flags }) =>
-    client.interactions.rotateGesture({
-      ...buildSelectionOptions(flags),
-      degrees: Number(positionals[0]),
-      x: optionalNumber(positionals[1]),
-      y: optionalNumber(positionals[2]),
-      velocity: optionalNumber(positionals[3]),
-    }),
   'trigger-app-event': ({ client, positionals, flags }) =>
     client.apps.triggerEvent({
       ...buildSelectionOptions(flags),
@@ -218,6 +191,53 @@ const genericClientCommandRunners = {
     client.settings.update(settingsCommandCodec.decode(positionals, flags)),
 } satisfies Partial<Record<PublicCommandName, GenericClientCommandRunner>>;
 
+function runGestureCommand(params: {
+  client: AgentDeviceClient;
+  positionals: string[];
+  flags: CliFlags;
+}): Promise<CommandRequestResult> {
+  const { client, positionals, flags } = params;
+  const subcommand = required(positionals[0], 'gesture requires subcommand');
+  const args = positionals.slice(1);
+  switch (subcommand) {
+    case 'pan':
+      return client.interactions.pan({
+        ...buildSelectionOptions(flags),
+        x: Number(args[0]),
+        y: Number(args[1]),
+        dx: Number(args[2]),
+        dy: Number(args[3]),
+        durationMs: optionalNumber(args[4]),
+      });
+    case 'fling':
+      return client.interactions.fling({
+        ...buildSelectionOptions(flags),
+        direction: readGestureDirection(args[0], 'gesture fling'),
+        x: Number(args[1]),
+        y: Number(args[2]),
+        distance: optionalNumber(args[3]),
+        durationMs: optionalNumber(args[4]),
+      });
+    case 'pinch':
+      return client.interactions.pinch({
+        ...buildSelectionOptions(flags),
+        scale: Number(args[0]),
+        x: optionalNumber(args[1]),
+        y: optionalNumber(args[2]),
+      });
+    case 'rotate':
+      return client.interactions.rotateGesture({
+        ...buildSelectionOptions(flags),
+        degrees: Number(args[0]),
+        x: optionalNumber(args[1]),
+        y: optionalNumber(args[2]),
+        velocity: optionalNumber(args[3]),
+      });
+    default:
+      throw new AppError('INVALID_ARGS', 'gesture requires one of: pan, fling, pinch, rotate');
+  }
+}
+
 export const genericClientCommandHandlers = Object.fromEntries(
   Object.entries(genericClientCommandRunners).map(([command, run]) => [
     command,

src/client.ts

@@ -333,8 +333,9 @@ export function createAgentDeviceClient(
         ),
       pan: async (options) =>
         await executeCommandRequest(
-          PUBLIC_COMMANDS.pan,
+          PUBLIC_COMMANDS.gesture,
           [
+            'pan',
             String(options.x),
             String(options.y),
             String(options.dx),
@@ -347,8 +348,9 @@ export function createAgentDeviceClient(
         const distance =
           options.durationMs !== undefined ? (options.distance ?? 180) : options.distance;
         return await executeCommandRequest(
-          PUBLIC_COMMANDS.fling,
+          PUBLIC_COMMANDS.gesture,
           [
+            'fling',
             options.direction,
             String(options.x),
             String(options.y),
@@ -384,15 +386,21 @@ export function createAgentDeviceClient(
         ),
       pinch: async (options) =>
         await executeCommandRequest(
-          PUBLIC_COMMANDS.pinch,
-          [String(options.scale), ...optionalNumber(options.x), ...optionalNumber(options.y)],
+          PUBLIC_COMMANDS.gesture,
+          [
+            'pinch',
+            String(options.scale),
+            ...optionalNumber(options.x),
+            ...optionalNumber(options.y),
+          ],
           options,
         ),
       rotateGesture: async (options) => {
         const center = options.x !== undefined || options.y !== undefined;
         return await executeCommandRequest(
-          PUBLIC_COMMANDS.rotateGesture,
+          PUBLIC_COMMANDS.gesture,
           [
+            'rotate',
             String(options.degrees),
             ...(center ? [String(options.x), String(options.y)] : []),
             ...optionalNumber(options.velocity),

src/command-catalog.ts

@@ -13,8 +13,8 @@ export const PUBLIC_COMMANDS = {
   diff: 'diff',
   fill: 'fill',
   find: 'find',
-  fling: 'fling',
   focus: 'focus',
+  gesture: 'gesture',
   get: 'get',
   home: 'home',
   install: 'install',
@@ -25,17 +25,14 @@ export const PUBLIC_COMMANDS = {
   longPress: 'longpress',
   network: 'network',
   open: 'open',
-  pan: 'pan',
   perf: 'perf',
-  pinch: 'pinch',
   press: 'press',
   push: 'push',
   record: 'record',
   reactNative: 'react-native',
   reinstall: 'reinstall',
   replay: 'replay',
   rotate: 'rotate',
-  rotateGesture: 'rotate-gesture',
   scroll: 'scroll',
   screenshot: 'screenshot',
   settings: 'settings',
@@ -91,19 +88,17 @@ export const DAEMON_COMMAND_GROUPS = {
     PUBLIC_COMMANDS.diff,
     PUBLIC_COMMANDS.fill,
     PUBLIC_COMMANDS.find,
-    PUBLIC_COMMANDS.fling,
+    PUBLIC_COMMANDS.gesture,
     PUBLIC_COMMANDS.get,
     PUBLIC_COMMANDS.home,
     PUBLIC_COMMANDS.is,
     PUBLIC_COMMANDS.keyboard,
     PUBLIC_COMMANDS.longPress,
-    PUBLIC_COMMANDS.pan,
-    PUBLIC_COMMANDS.pinch,
+    'pinch',
     PUBLIC_COMMANDS.press,
     PUBLIC_COMMANDS.record,
     PUBLIC_COMMANDS.reactNative,
     PUBLIC_COMMANDS.rotate,
-    PUBLIC_COMMANDS.rotateGesture,
     PUBLIC_COMMANDS.screenshot,
     PUBLIC_COMMANDS.scroll,
     PUBLIC_COMMANDS.settings,

src/core/dispatch-interactions.ts

@@ -456,7 +456,7 @@ export async function handlePanCommand(
   const dx = Number(positionals[2]);
   const dy = Number(positionals[3]);
   if ([x, y, dx, dy].some((value) => !Number.isFinite(value))) {
-    throw new AppError('INVALID_ARGS', 'pan requires x y dx dy [durationMs]');
+    throw new AppError('INVALID_ARGS', 'gesture pan requires x y dx dy [durationMs]');
   }
   const requestedDurationMs = positionals[4] ? Number(positionals[4]) : 500;
   const durationMs = requireIntInRange(requestedDurationMs, 'durationMs', 16, 10_000);
@@ -483,7 +483,10 @@ export async function handleFlingCommand(
   const x = Number(positionals[1]);
   const y = Number(positionals[2]);
   if (![x, y].every(Number.isFinite)) {
-    throw new AppError('INVALID_ARGS', 'fling requires direction x y [distance] [durationMs]');
+    throw new AppError(
+      'INVALID_ARGS',
+      'gesture fling requires direction x y [distance] [durationMs]',
+    );
   }
   const distanceInput = positionals[3] ? Number(positionals[3]) : 180;
   const distance = requireFinitePositiveNumber(distanceInput, 'distance');
@@ -601,23 +604,23 @@ export async function handlePinchCommand(
   if (device.platform === 'android') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      'Android pinch is not supported in current adb backend; requires instrumentation-based backend.',
+      'Android gesture pinch is not supported in current adb backend; requires instrumentation-based backend.',
     );
   }
   if (device.target === 'tv') {
-    throw new AppError('UNSUPPORTED_OPERATION', 'pinch is not supported on tvOS');
+    throw new AppError('UNSUPPORTED_OPERATION', 'gesture pinch is not supported on tvOS');
   }
   if (device.platform === 'macos' && context?.surface && context.surface !== 'app') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      'pinch is only supported in macOS app sessions. Re-open the target app without --surface desktop|menubar|frontmost-app first.',
+      'gesture pinch is only supported in macOS app sessions. Re-open the target app without --surface desktop|menubar|frontmost-app first.',
     );
   }
   const scale = Number(positionals[0]);
   const x = positionals[1] ? Number(positionals[1]) : undefined;
   const y = positionals[2] ? Number(positionals[2]) : undefined;
   if (Number.isNaN(scale) || scale <= 0) {
-    throw new AppError('INVALID_ARGS', 'pinch requires scale > 0');
+    throw new AppError('INVALID_ARGS', 'gesture pinch requires scale > 0');
   }
   await runIosRunnerCommand(
     device,
@@ -640,16 +643,16 @@ export async function handleRotateGestureCommand(
   if (device.platform === 'android') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      'Android rotate-gesture is not supported in current adb backend; requires instrumentation-based backend.',
+      'Android gesture rotate is not supported in current adb backend; requires instrumentation-based backend.',
     );
   }
   if (device.target === 'tv') {
-    throw new AppError('UNSUPPORTED_OPERATION', 'rotate-gesture is not supported on tvOS');
+    throw new AppError('UNSUPPORTED_OPERATION', 'gesture rotate is not supported on tvOS');
   }
   if (device.platform === 'macos') {
     throw new AppError(
       'UNSUPPORTED_OPERATION',
-      'rotate-gesture is not supported on macOS; XCTest rotation gestures are available only for iOS app sessions.',
+      'gesture rotate is not supported on macOS; XCTest rotation gestures are available only for iOS app sessions.',
     );
   }
 
@@ -676,13 +679,13 @@ type RotateGestureParams = {
 function parseRotateGestureParams(positionals: string[]): RotateGestureParams {
   const degrees = Number(positionals[0]);
   if (!Number.isFinite(degrees)) {
-    throw new AppError('INVALID_ARGS', 'rotate-gesture requires degrees [x] [y] [velocity]');
+    throw new AppError('INVALID_ARGS', 'gesture rotate requires degrees [x] [y] [velocity]');
   }
 
   const center = parseOptionalGestureCenter(positionals[1], positionals[2]);
   const velocity = Number(positionals[3] ?? (degrees >= 0 ? 1 : -1));
   if (!Number.isFinite(velocity) || velocity === 0) {
-    throw new AppError('INVALID_ARGS', 'rotate-gesture velocity must be a non-zero number');
+    throw new AppError('INVALID_ARGS', 'gesture rotate velocity must be a non-zero number');
   }
 
   return { degrees, ...center, velocity };
@@ -694,13 +697,13 @@ function parseOptionalGestureCenter(
 ): Pick<RotateGestureParams, 'x' | 'y'> {
   if (xInput === undefined && yInput === undefined) return {};
   if (xInput === undefined || yInput === undefined) {
-    throw new AppError('INVALID_ARGS', 'rotate-gesture center requires both x and y');
+    throw new AppError('INVALID_ARGS', 'gesture rotate center requires both x and y');
   }
 
   const x = Number(xInput);
   const y = Number(yInput);
   if (!Number.isFinite(x) || !Number.isFinite(y)) {
-    throw new AppError('INVALID_ARGS', 'rotate-gesture center requires finite x and y');
+    throw new AppError('INVALID_ARGS', 'gesture rotate center requires finite x and y');
   }
   return { x, y };
 }