@unotest/mobile 0.8.1 → 0.8.2

package/CHANGELOG.md

@@ -4,6 +4,55 @@ All notable changes to `@unotest/mobile` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.8.2] — 2026-05-18
+
+### Fixed — `type()` no longer drops 1-3 characters mid-string
+
+- **What broke.** `WdaDriver.type` issued `XCUIElement.typeText` at WDA's
+  default typing frequency (~60 letters/sec) into the simulator's iOS
+  keyboard. Under host contention (Claude Code + WDA build + Simulator
+  all running on the same Mac), the iOS keyboard layer couldn't keep
+  up and randomly dropped 1-3 characters from the middle of the string
+  — observed live as `petr@volkov.io` → `pr@volkov.io`, `Qwerty34##`
+  → `Qwery34##`. P4 / S8 had only addressed the unrelated *wrong-
+  keyboard-layout* failure (Cyrillic keyboard eating Latin chars
+  wholesale); this race is a separate failure mode that survived.
+- **Fix 1 — `ConnectHardwareKeyboard` pinned OFF on install.**
+  The `pinEnglishKeyboard` step (S8) now also writes
+  `ConnectHardwareKeyboard = false` into the Simulator.app preferences
+  on every install. When the toggle is ON (the default on a freshly
+  created sim, controlled by ⌘K inside the sim), iOS suppresses the
+  soft keyboard and routes keys through the host's physical keyboard
+  path — typeText then races against keyboard presentation. Pinning
+  OFF guarantees the soft keyboard renders and stays visible.
+  Idempotent. Reuses the existing `pinKeyboard: false` opt-out flag.
+- **Fix 2 — `WDA_TYPING_FREQUENCY` env (default `8`).** `WdaDriver.type`
+  now passes `frequency: <env>` in the POST `/element/{id}/value`
+  body, which WDA forwards to `fb_typeText:withFrequency:`. 8 cps is
+  conservative-but-still-usable: typical credentials (`petr@volkov.io`,
+  `Qwerty34##`) type in ~2s instead of the unreliable ~0.3s. Bump
+  higher if you trust your host's headroom; lower if you're seeing
+  drops in CI under heavy load. Validated as a positive integer at
+  `loadEnv` time.
+- **Why not pasteboard / per-char paste.** Researched approaches the
+  XCUITest community has tried (`UIPasteboard` + double-tap-menu paste,
+  per-char `typeKey:` calls, `setValue` direct-set): pasteboard paste
+  is **43% slower and flaky** (per iammike.org / 2022); per-char
+  `typeKey:` is only 3% faster than throttled `typeText`, complex to
+  wire reliably; `setValue` on native iOS text fields routes back to
+  `typeText` internally — there is no Apple-blessed "set text without
+  keyboard" API. WDA's own `maxTypingFrequency` is the documented knob.
+- **Tests:** +0 net. Modified 1 existing assertion to verify
+  `frequency: 8` lands in the request body. The hardware-keyboard
+  flip rides on the same `pinEnglishKeyboard` call site, so existing
+  call-sequence assertions still hold. Total 570.
+
+### Added — `WDA_TYPING_FREQUENCY` env var
+
+- Letters-per-second passed to WDA's `fb_typeText:withFrequency:` on
+  every `type(...)` call. Default `8`. See the fix entry above for
+  rationale on the conservative default.
+
 ## [0.8.1] — 2026-05-18
 
 ### Fixed — `init` pins the exact `@unotest/mobile` version in `.mcp.json`

package/README.md

@@ -30,18 +30,18 @@ you review the resulting `.js` files in `unotest/e2e/`.
 ┌─────────────┐  MCP (stdio)   ┌──────────────────┐
 │ Claude Code │ ◀────────────▶ │ @unotest/mobile  │
 └─────────────┘   tool calls   │  (this package)  │
-                                └────────┬─────────┘
-                                         │ HTTP
-                                ┌────────▼──────────┐
-                                │  WebDriverAgent   │
-                                │  (Apple's XCUI    │
-                                │   driver, on sim) │
-                                └────────┬──────────┘
-                                         │
-                                ┌────────▼──────────┐
-                                │  iOS Simulator    │
-                                │  Your .app        │
-                                └───────────────────┘
+                               └────────┬─────────┘
+                                        │ HTTP
+                               ┌────────▼──────────┐
+                               │  WebDriverAgent   │
+                               │  (Apple's XCUI    │
+                               │   driver, on sim) │
+                               └────────┬──────────┘
+                                        │
+                               ┌────────▼──────────┐
+                               │  iOS Simulator    │
+                               │  Your .app        │
+                               └───────────────────┘
 ```
 
 - **The agent sees the accessibility tree, not screenshots.** WDA

package/dist/mcp/server.js

@@ -240,6 +240,15 @@ var EnvSchema = z.object({
   // Implicit auto-wait on selector-bearing actions (D-18).
   WDA_DEFAULT_ACTION_WAIT_MS: z.string().default("2000").transform((v) => Number.parseInt(v, 10)),
   WDA_DEFAULT_WAITFOR_TIMEOUT_MS: z.string().default("10000").transform((v) => Number.parseInt(v, 10)),
+  // Typing frequency (letters/sec) passed through to WDA's
+  // `fb_typeText:withFrequency:` on every `type(...)` call. WDA's own
+  // default is its `maxTypingFrequency` (typically 60 cps) which under
+  // contention from the host (Claude Code + WDA build + sim) races
+  // against the iOS keyboard presentation and randomly drops 1-3 chars
+  // mid-string. 8 cps is the conservative-but-still-usable value that
+  // empirically eliminates drops without making typing visibly slow
+  // (`petr@volkov.io` types in ~2s instead of ~0.3s).
+  WDA_TYPING_FREQUENCY: z.string().default("8").transform((v) => Number.parseInt(v, 10)),
   // TTL for paused-failed runtimes before auto-abort (D-17). Default 30 min.
   PAUSED_RUNTIME_TTL_MS: z.string().default("1800000").transform((v) => Number.parseInt(v, 10))
 });
@@ -287,6 +296,11 @@ ${issues}`
       );
     }
   }
+  if (!Number.isFinite(raw.WDA_TYPING_FREQUENCY) || raw.WDA_TYPING_FREQUENCY <= 0) {
+    throw new Error(
+      `WDA_TYPING_FREQUENCY must be a positive integer (letters/sec). Got "${process.env.WDA_TYPING_FREQUENCY}".`
+    );
+  }
   cached = {
     ...raw,
     simPool,
@@ -294,6 +308,7 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
+    wdaTypingFrequency: raw.WDA_TYPING_FREQUENCY,
     pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
     explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
@@ -636,6 +651,17 @@ async function pinEnglishKeyboardSim(udid) {
     "-string",
     "en_US"
   ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "com.apple.iphonesimulator.SimulatorApp",
+    "ConnectHardwareKeyboard",
+    "-bool",
+    "false"
+  ]);
 }
 __name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
@@ -690,8 +716,11 @@ var SimctlAdapter = class {
   async privacyGrant(udid, service, bundleId) {
     return privacyGrantSim(udid, service, bundleId);
   }
-  /** S8 — pin the sim's keyboard to en_US@QWERTY so WDA's typeText
-   *  doesn't drop Latin chars when the sim was last on a Cyrillic layout. */
+  /** S8 — prepare the sim's keyboard for reliable `typeText`. Pins
+   *  layout to en_US@QWERTY (otherwise a leftover Cyrillic layout
+   *  drops Latin chars) and forces "Connect Hardware Keyboard" OFF
+   *  (otherwise the soft keyboard is suppressed and `typeText` races
+   *  against keyboard presentation, dropping 1-3 chars mid-string). */
   async pinEnglishKeyboard(udid) {
     return pinEnglishKeyboardSim(udid);
   }
@@ -1277,7 +1306,8 @@ Install it first: \`npx unotest-mobile install <path-to-.app>\` (or set APP_PATH
     await this.withFreshSession(slot, async (session) => {
       const elementId = await this.resolveElementId(slot, selector);
       await session.client.setElementValue(session.getSessionId(), elementId, {
-        value: Array.from(text)
+        value: Array.from(text),
+        frequency: this.deps.typingFrequency
       });
     });
   }
@@ -1578,6 +1608,7 @@ function createDriver(cfg) {
         simBySlot: cfg.env.simBySlot,
         wdaPortBySlot: cfg.env.wdaPortBySlot,
         appBundleId: cfg.env.APP_BUNDLE_ID,
+        typingFrequency: cfg.env.wdaTypingFrequency,
         binaryProvider
       });
     }
@@ -6819,7 +6850,7 @@ async function installApp2(opts, deps) {
       }
     }
     if (opts.pinKeyboard !== false) {
-      deps.logger.info(`[${slot}] pinning keyboard to en_US@QWERTY`);
+      deps.logger.info(`[${slot}] pinning keyboard (en_US@QWERTY, soft only)`);
       await deps.simctl.pinEnglishKeyboard(sim.udid);
     }
     let launched = false;

package/dist/runner/cli.js

@@ -236,6 +236,15 @@ var EnvSchema = z.object({
   // Implicit auto-wait on selector-bearing actions (D-18).
   WDA_DEFAULT_ACTION_WAIT_MS: z.string().default("2000").transform((v) => Number.parseInt(v, 10)),
   WDA_DEFAULT_WAITFOR_TIMEOUT_MS: z.string().default("10000").transform((v) => Number.parseInt(v, 10)),
+  // Typing frequency (letters/sec) passed through to WDA's
+  // `fb_typeText:withFrequency:` on every `type(...)` call. WDA's own
+  // default is its `maxTypingFrequency` (typically 60 cps) which under
+  // contention from the host (Claude Code + WDA build + sim) races
+  // against the iOS keyboard presentation and randomly drops 1-3 chars
+  // mid-string. 8 cps is the conservative-but-still-usable value that
+  // empirically eliminates drops without making typing visibly slow
+  // (`petr@volkov.io` types in ~2s instead of ~0.3s).
+  WDA_TYPING_FREQUENCY: z.string().default("8").transform((v) => Number.parseInt(v, 10)),
   // TTL for paused-failed runtimes before auto-abort (D-17). Default 30 min.
   PAUSED_RUNTIME_TTL_MS: z.string().default("1800000").transform((v) => Number.parseInt(v, 10))
 });
@@ -283,6 +292,11 @@ ${issues}`
       );
     }
   }
+  if (!Number.isFinite(raw.WDA_TYPING_FREQUENCY) || raw.WDA_TYPING_FREQUENCY <= 0) {
+    throw new Error(
+      `WDA_TYPING_FREQUENCY must be a positive integer (letters/sec). Got "${process.env.WDA_TYPING_FREQUENCY}".`
+    );
+  }
   cached = {
     ...raw,
     simPool,
@@ -290,6 +304,7 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
+    wdaTypingFrequency: raw.WDA_TYPING_FREQUENCY,
     pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
     explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
@@ -632,6 +647,17 @@ async function pinEnglishKeyboardSim(udid) {
     "-string",
     "en_US"
   ]);
+  await exec2("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "com.apple.iphonesimulator.SimulatorApp",
+    "ConnectHardwareKeyboard",
+    "-bool",
+    "false"
+  ]);
 }
 __name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
@@ -686,8 +712,11 @@ var SimctlAdapter = class {
   async privacyGrant(udid, service, bundleId) {
     return privacyGrantSim(udid, service, bundleId);
   }
-  /** S8 — pin the sim's keyboard to en_US@QWERTY so WDA's typeText
-   *  doesn't drop Latin chars when the sim was last on a Cyrillic layout. */
+  /** S8 — prepare the sim's keyboard for reliable `typeText`. Pins
+   *  layout to en_US@QWERTY (otherwise a leftover Cyrillic layout
+   *  drops Latin chars) and forces "Connect Hardware Keyboard" OFF
+   *  (otherwise the soft keyboard is suppressed and `typeText` races
+   *  against keyboard presentation, dropping 1-3 chars mid-string). */
   async pinEnglishKeyboard(udid) {
     return pinEnglishKeyboardSim(udid);
   }
@@ -1273,7 +1302,8 @@ Install it first: \`npx unotest-mobile install <path-to-.app>\` (or set APP_PATH
     await this.withFreshSession(slot, async (session) => {
       const elementId = await this.resolveElementId(slot, selector);
       await session.client.setElementValue(session.getSessionId(), elementId, {
-        value: Array.from(text)
+        value: Array.from(text),
+        frequency: this.deps.typingFrequency
       });
     });
   }
@@ -1574,6 +1604,7 @@ function createDriver(cfg) {
         simBySlot: cfg.env.simBySlot,
         wdaPortBySlot: cfg.env.wdaPortBySlot,
         appBundleId: cfg.env.APP_BUNDLE_ID,
+        typingFrequency: cfg.env.wdaTypingFrequency,
         binaryProvider
       });
     }

package/dist/runner/init.js

@@ -272,6 +272,11 @@ APP_BUNDLE_ID=com.example.myapp
 WDA_PORTS=A=8100,B=8101
 # WDA_DEFAULT_ACTION_WAIT_MS=2000
 # WDA_DEFAULT_WAITFOR_TIMEOUT_MS=10000
+# Letters/sec for type() \u2014 WDA's fb_typeText:withFrequency:. Conservative
+# default avoids char-drop races against the iOS keyboard layer when the
+# host is under load. Bump higher (e.g. 20) on a quiet machine; lower
+# (e.g. 4) if you still see drops in CI.
+# WDA_TYPING_FREQUENCY=8
 
 # --- Artifacts / sessions / paused-runtime TTL -----------------------------
 # Defaults are sensible \u2014 uncomment only to override.

package/dist/runner/install.js

@@ -84,6 +84,15 @@ var EnvSchema = z.object({
   // Implicit auto-wait on selector-bearing actions (D-18).
   WDA_DEFAULT_ACTION_WAIT_MS: z.string().default("2000").transform((v) => Number.parseInt(v, 10)),
   WDA_DEFAULT_WAITFOR_TIMEOUT_MS: z.string().default("10000").transform((v) => Number.parseInt(v, 10)),
+  // Typing frequency (letters/sec) passed through to WDA's
+  // `fb_typeText:withFrequency:` on every `type(...)` call. WDA's own
+  // default is its `maxTypingFrequency` (typically 60 cps) which under
+  // contention from the host (Claude Code + WDA build + sim) races
+  // against the iOS keyboard presentation and randomly drops 1-3 chars
+  // mid-string. 8 cps is the conservative-but-still-usable value that
+  // empirically eliminates drops without making typing visibly slow
+  // (`petr@volkov.io` types in ~2s instead of ~0.3s).
+  WDA_TYPING_FREQUENCY: z.string().default("8").transform((v) => Number.parseInt(v, 10)),
   // TTL for paused-failed runtimes before auto-abort (D-17). Default 30 min.
   PAUSED_RUNTIME_TTL_MS: z.string().default("1800000").transform((v) => Number.parseInt(v, 10))
 });
@@ -131,6 +140,11 @@ ${issues}`
       );
     }
   }
+  if (!Number.isFinite(raw.WDA_TYPING_FREQUENCY) || raw.WDA_TYPING_FREQUENCY <= 0) {
+    throw new Error(
+      `WDA_TYPING_FREQUENCY must be a positive integer (letters/sec). Got "${process.env.WDA_TYPING_FREQUENCY}".`
+    );
+  }
   cached = {
     ...raw,
     simPool,
@@ -138,6 +152,7 @@ ${issues}`
     wdaPortBySlot,
     defaultActionWaitMs: raw.WDA_DEFAULT_ACTION_WAIT_MS,
     defaultWaitForTimeoutMs: raw.WDA_DEFAULT_WAITFOR_TIMEOUT_MS,
+    wdaTypingFrequency: raw.WDA_TYPING_FREQUENCY,
     pausedRuntimeTtlMs: raw.PAUSED_RUNTIME_TTL_MS,
     explorationsDir: raw.EXPLORATIONS_DIR ?? `${raw.ARTIFACTS_DIR}/explorations`
   };
@@ -364,6 +379,17 @@ async function pinEnglishKeyboardSim(udid) {
     "-string",
     "en_US"
   ]);
+  await exec("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "write",
+    "com.apple.iphonesimulator.SimulatorApp",
+    "ConnectHardwareKeyboard",
+    "-bool",
+    "false"
+  ]);
 }
 __name(pinEnglishKeyboardSim, "pinEnglishKeyboardSim");
 
@@ -418,8 +444,11 @@ var SimctlAdapter = class {
   async privacyGrant(udid, service, bundleId) {
     return privacyGrantSim(udid, service, bundleId);
   }
-  /** S8 — pin the sim's keyboard to en_US@QWERTY so WDA's typeText
-   *  doesn't drop Latin chars when the sim was last on a Cyrillic layout. */
+  /** S8 — prepare the sim's keyboard for reliable `typeText`. Pins
+   *  layout to en_US@QWERTY (otherwise a leftover Cyrillic layout
+   *  drops Latin chars) and forces "Connect Hardware Keyboard" OFF
+   *  (otherwise the soft keyboard is suppressed and `typeText` races
+   *  against keyboard presentation, dropping 1-3 chars mid-string). */
   async pinEnglishKeyboard(udid) {
     return pinEnglishKeyboardSim(udid);
   }
@@ -912,6 +941,11 @@ APP_BUNDLE_ID=com.example.myapp
 WDA_PORTS=A=8100,B=8101
 # WDA_DEFAULT_ACTION_WAIT_MS=2000
 # WDA_DEFAULT_WAITFOR_TIMEOUT_MS=10000
+# Letters/sec for type() \u2014 WDA's fb_typeText:withFrequency:. Conservative
+# default avoids char-drop races against the iOS keyboard layer when the
+# host is under load. Bump higher (e.g. 20) on a quiet machine; lower
+# (e.g. 4) if you still see drops in CI.
+# WDA_TYPING_FREQUENCY=8
 
 # --- Artifacts / sessions / paused-runtime TTL -----------------------------
 # Defaults are sensible \u2014 uncomment only to override.
@@ -1324,7 +1358,7 @@ async function installApp2(opts, deps) {
       }
     }
     if (opts.pinKeyboard !== false) {
-      deps.logger.info(`[${slot}] pinning keyboard to en_US@QWERTY`);
+      deps.logger.info(`[${slot}] pinning keyboard (en_US@QWERTY, soft only)`);
       await deps.simctl.pinEnglishKeyboard(sim.udid);
     }
     let launched = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unotest/mobile",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "AI-native E2E testing for iOS React Native apps. MCP server + CLI runner + JS-DSL scenarios.",
   "license": "MIT",
   "type": "module",