fix(ios): type characters individually to prevent dropped keystrokes

The default WDA `/wda/keys` path pushes the whole string in a single
request, so XCUITest fires keystrokes back-to-back with ~30-50ms gaps.
If the input's onChange handler blocks for longer than that gap (RN
re-render, predictive bar, autocorrect), every keystroke that lands
inside the blocking window is dropped, producing contiguous gaps such
as "Al is amazing" arriving as "Al mazing".

Send characters one at a time with an inter-key delay so the gap
exceeds the typical app reaction window. The new `keyboardTypeDelay`
option on `IOSDeviceInputOpt` defaults to 80ms and can be set to 0 to
restore the legacy one-shot behavior.

Author: quanru

packages/core/src/device/device-options.ts

@@ -112,6 +112,16 @@ export type AndroidDeviceOpt = {
 export type IOSDeviceInputOpt = {
   /** Automatically dismiss the keyboard after input is completed */
   autoDismissKeyboard?: boolean;
+  /**
+   * Per-character delay (ms) used when typing into iOS input fields. When set
+   * to a positive number, characters are dispatched to WebDriverAgent one at a
+   * time with this gap between them, which prevents app-side reaction windows
+   * (re-render, predictive bar, autocorrect) from swallowing a contiguous
+   * block of keystrokes. Set to 0 to send the whole string in a single
+   * `/wda/keys` request (faster, but lossy on slow-reacting inputs).
+   * @default 80
+   */
+  keyboardTypeDelay?: number;
 };
 
 /**

packages/core/tests/unit-test/device-options.test.ts

@@ -85,6 +85,7 @@ describe('Device Options Type Definitions', () => {
     test('IOSDeviceInputOpt should include keyboard options', () => {
       const inputOptions: IOSDeviceInputOpt = {
         autoDismissKeyboard: true,
+        keyboardTypeDelay: 80,
       };
 
       expect(inputOptions).toBeDefined();

packages/ios/src/device.ts

@@ -468,12 +468,15 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
     const shouldAutoDismissKeyboard =
       options?.autoDismissKeyboard ?? this.options?.autoDismissKeyboard ?? true;
 
-    debugDevice(`Typing text: "${text}"`);
+    const delayMs =
+      options?.keyboardTypeDelay ?? this.options?.keyboardTypeDelay ?? 80;
+
+    debugDevice(`Typing text: "${text}" (delayMs=${delayMs})`);
 
     try {
       // Wait a bit to ensure keyboard is ready
       await sleep(200);
-      await this.wdaBackend.typeText(text);
+      await this.wdaBackend.typeText(text, { delayMs });
       await sleep(300); // Give more time for text to appear
     } catch (error) {
       debugDevice(`Failed to type text with WDA: ${error}`);

packages/ios/src/ios-webdriver-client.ts

@@ -1,3 +1,4 @@
+import { sleep } from '@midscene/core/utils';
 import { getDebug } from '@midscene/shared/logger';
 import { WebDriverClient } from '@midscene/webdriver';
 
@@ -304,17 +305,42 @@ export class IOSWebDriverClient extends WebDriverClient {
     }
   }
 
-  async typeText(text: string): Promise<void> {
+  async typeText(text: string, options?: { delayMs?: number }): Promise<void> {
     this.ensureSession();
 
+    // Clean the text to avoid unwanted trailing spaces
+    const cleanText = text.trim();
+    if (!cleanText) {
+      return;
+    }
+
+    const chars = Array.from(cleanText);
+    const delayMs = options?.delayMs ?? 0;
+
     try {
-      // Clean the text to avoid unwanted trailing spaces
-      const cleanText = text.trim();
-      // Use WebDriverAgent's keys endpoint with array value
-      await this.makeRequest('POST', `/session/${this.sessionId}/wda/keys`, {
-        value: cleanText.split(''), // Must be an array of characters
-      });
-      debugIOS(`Typed text: "${text}"`);
+      if (delayMs > 0) {
+        // Per-character sends with an inter-key gap prevent a single app-side
+        // reaction window (re-render, predictive bar, autocorrect) from
+        // swallowing a contiguous block of keystrokes.
+        for (let i = 0; i < chars.length; i++) {
+          await this.makeRequest(
+            'POST',
+            `/session/${this.sessionId}/wda/keys`,
+            {
+              value: [chars[i]],
+            },
+          );
+          if (i < chars.length - 1) {
+            await sleep(delayMs);
+          }
+        }
+      } else {
+        // Use WebDriverAgent's keys endpoint with array value
+        await this.makeRequest('POST', `/session/${this.sessionId}/wda/keys`, {
+          value: chars, // Must be an array of characters
+        });
+      }
+      debugIOS(`Typed text: "${text}" (delayMs=${delayMs})`);
     } catch (error) {
       debugIOS(`Failed to type text "${text}": ${error}`);
       throw new Error(`Failed to type text: ${error}`);

packages/ios/tests/unit-test/device.test.ts

@@ -236,8 +236,43 @@ describe('IOSDevice', () => {
       expect(mockWdaClient.tap).toHaveBeenNthCalledWith(1, 10, 20);
       expect(mockWdaClient.tap).toHaveBeenNthCalledWith(2, 30, 40);
       expect(mockWdaClient.clearActiveElement).toHaveBeenCalledTimes(2);
-      expect(mockWdaClient.typeText).toHaveBeenNthCalledWith(1, 'from action');
-      expect(mockWdaClient.typeText).toHaveBeenNthCalledWith(2, 'from pointer');
+      expect(mockWdaClient.typeText).toHaveBeenNthCalledWith(1, 'from action', {
+        delayMs: 80,
+      });
+      expect(mockWdaClient.typeText).toHaveBeenNthCalledWith(
+        2,
+        'from pointer',
+        { delayMs: 80 },
+      );
+    });
+
+    it('forwards keyboardTypeDelay from per-call options to the WDA backend', async () => {
+      await device.inputPrimitives.keyboard.typeText('per call', {
+        autoDismissKeyboard: false,
+        keyboardTypeDelay: 25,
+      } as any);
+
+      expect(mockWdaClient.typeText).toHaveBeenLastCalledWith('per call', {
+        delayMs: 25,
+      });
+    });
+
+    it('falls back to device-level keyboardTypeDelay when the call omits it', async () => {
+      const deviceWithDelay = new IOSDevice({
+        wdaPort: DEFAULT_WDA_PORT,
+        wdaHost: 'localhost',
+        keyboardTypeDelay: 0,
+      });
+
+      await deviceWithDelay.inputPrimitives.keyboard.typeText('default delay', {
+        autoDismissKeyboard: false,
+      } as any);
+
+      expect(mockWdaClient.typeText).toHaveBeenLastCalledWith('default delay', {
+        delayMs: 0,
+      });
+
+      await deviceWithDelay.destroy();
     });
   });
 
@@ -383,8 +418,10 @@ describe('IOSDevice', () => {
     it('should type text', async () => {
       await device.connect();
 
-      await device.typeText('Hello World');
-      expect(mockWdaClient.typeText).toHaveBeenCalledWith('Hello World');
+      await (device as any).typeText('Hello World');
+      expect(mockWdaClient.typeText).toHaveBeenCalledWith('Hello World', {
+        delayMs: 80,
+      });
     });
 
     it('should press home button', async () => {
@@ -521,7 +558,9 @@ describe('IOSDevice', () => {
         .fn()
         .mockRejectedValue(new Error('Type text failed'));
 
-      await expect(device.typeText('test')).rejects.toThrow('Type text failed');
+      await expect((device as any).typeText('test')).rejects.toThrow(
+        'Type text failed',
+      );
     });
   });
 
@@ -584,10 +623,12 @@ describe('IOSDevice', () => {
       });
 
       await deviceWithAutoDismiss.connect();
-      await deviceWithAutoDismiss.typeText('test text');
+      await (deviceWithAutoDismiss as any).typeText('test text');
 
       // Should call typeText and swipe (for keyboard dismiss)
-      expect(mockBackend.typeText).toHaveBeenCalledWith('test text');
+      expect(mockBackend.typeText).toHaveBeenCalledWith('test text', {
+        delayMs: 80,
+      });
       expect(mockBackend.swipe).toHaveBeenCalled();
     });
   });

packages/ios/tests/unit-test/wda-backend.test.ts

@@ -1,5 +1,84 @@
 import { DEFAULT_WDA_PORT } from '@midscene/shared/constants';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+import { IOSWebDriverClient } from '../../src/ios-webdriver-client';
+
+function createClientWithSession() {
+  const client = new IOSWebDriverClient({
+    port: DEFAULT_WDA_PORT,
+    host: 'localhost',
+  });
+  // Bypass createSession() — we only want to observe outbound HTTP calls.
+  (client as any).sessionId = 'session-under-test';
+  const makeRequest = vi
+    .spyOn(client as any, 'makeRequest')
+    .mockResolvedValue(undefined);
+  return { client, makeRequest };
+}
+
+describe('IOSWebDriverClient.typeText delivery modes', () => {
+  it('sends the whole string in one /wda/keys request when delayMs is 0 (default)', async () => {
+    const { client, makeRequest } = createClientWithSession();
+
+    await client.typeText('Al is amazing');
+
+    expect(makeRequest).toHaveBeenCalledTimes(1);
+    expect(makeRequest).toHaveBeenCalledWith(
+      'POST',
+      '/session/session-under-test/wda/keys',
+      {
+        value: [
+          'A',
+          'l',
+          ' ',
+          'i',
+          's',
+          ' ',
+          'a',
+          'm',
+          'a',
+          'z',
+          'i',
+          'n',
+          'g',
+        ],
+      },
+    );
+  });
+
+  it('emits one /wda/keys request per character when delayMs > 0', async () => {
+    const { client, makeRequest } = createClientWithSession();
+
+    await client.typeText('Hi!', { delayMs: 1 });
+
+    expect(makeRequest).toHaveBeenCalledTimes(3);
+    expect(makeRequest).toHaveBeenNthCalledWith(
+      1,
+      'POST',
+      '/session/session-under-test/wda/keys',
+      { value: ['H'] },
+    );
+    expect(makeRequest).toHaveBeenNthCalledWith(
+      2,
+      'POST',
+      '/session/session-under-test/wda/keys',
+      { value: ['i'] },
+    );
+    expect(makeRequest).toHaveBeenNthCalledWith(
+      3,
+      'POST',
+      '/session/session-under-test/wda/keys',
+      { value: ['!'] },
+    );
+  });
+
+  it('trims surrounding whitespace and skips empty input', async () => {
+    const { client, makeRequest } = createClientWithSession();
+
+    await client.typeText('   ');
+
+    expect(makeRequest).not.toHaveBeenCalled();
+  });
+});
 
 describe('IOSWebDriverClient - Simple Tests', () => {
   describe('Module Structure', () => {