@unotest/mobile 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -4,6 +4,78 @@ 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.3] — 2026-05-18
+
+### Added — README onboarding protocol for AI agents
+
+- **New top-of-README section.** A developer dropping the npm page
+  link into their AI agent's context (Cursor, Claude Desktop, Claude
+  Code in another project, etc.) now gets a 5-step protocol explicitly
+  addressed to the agent: verify host → pick working directory → ask
+  for `.app` path → run interactive setup in user's terminal → hand off
+  to Claude Code in the same directory. Spells out where the agent's
+  responsibility ends (not test authoring; that's a separate Claude
+  Code session via MCP) and what NOT to run via its own `Bash`-style
+  shell tool (the install command is interactive — needs a real TTY
+  for the simulator picker; tool-spawned shells either hang or fall
+  back to a non-interactive code path that can confuse the user).
+- The working-directory step is explicit because `init` drops
+  `unotest/`, `.mcp.json`, `.claude/skills/`, and `AGENTS.md` into
+  cwd, and `.mcp.json`'s location determines what Claude Code sees on
+  its next launch. Recommends the app repo root by default; monorepo
+  root for monorepos; explicit warning that a separate test repo
+  divorces tests from the app and should be chosen only when the user
+  asks for it.
+
+## [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

@@ -5,6 +5,74 @@ that lets Claude (or any MCP client) drive your iOS Simulator and write
 real test scenarios for your app — works with any backend stack
 (Node/Python/Rails/Go/Java), no JS expertise required from you.
 
+## If you're an AI agent helping a user set this up
+
+*(Humans: skip this section, jump to [Quick start](#quick-start).)*
+
+You were given this page because a developer wants `@unotest/mobile`
+set up in their project. Follow this protocol exactly — don't improvise.
+
+**1. Verify the host.** Run `xcrun simctl list devices` via your shell
+tool. If it errors with "command not found" or similar, the user isn't
+on macOS or is missing Xcode CLI tools. Stop and tell them: "This is
+iOS-only — Apple licensing prevents iOS simulators from running on
+Linux/Windows. You'll need macOS with Xcode installed." Also verify
+`node --version` ≥ 20.
+
+**2. Pick a working directory with the user.** Setup writes
+`unotest/` (test scaffold), `.mcp.json` (Claude Code config),
+`.claude/skills/` (skill the in-project agent reads), and an
+`AGENTS.md` into the current directory, and updates `.gitignore` if
+present. Where these land determines what Claude Code sees later, so
+ask the user explicitly:
+
+- **Default — the app's repo root.** Same directory as their
+  `package.json` (RN/Expo) or where their `.xcodeproj` lives (native).
+  Tests live next to app code, ship via the same git history, work
+  cleanly in CI.
+- **Monorepo:** the monorepo root, not the app subfolder. Claude Code
+  is typically opened at the monorepo root, and `.mcp.json` must live
+  there to be auto-discovered.
+- **Separate test repo:** any directory the user picks. Choose this
+  only if they explicitly want tests divorced from the app.
+
+Once the user picks, have them `cd` there. All commands below run
+from that directory.
+
+**3. Ask the user for the `.app` path.** `@unotest/mobile` drives a
+real installed app — it needs the path to a built `.app` bundle.
+Ask: *"What's the absolute path to your built `.app`?"* Common
+locations:
+- React Native / Expo: `./ios/build/Build/Products/Debug-iphonesimulator/<App>.app`
+  after `npx expo run:ios` or `pod install && xcodebuild`.
+- Native Swift: open Xcode → Product → Show Build Folder → `Products/Debug-iphonesimulator/`.
+
+If they don't have one yet, tell them to build first; don't guess
+paths.
+
+**4. Tell the user to run the setup command in the chosen directory.**
+**Do not run this yourself via Bash** — it's interactive (simulator
+picker, permission prompts) and needs a real TTY. Your shell tool
+will hang or get a non-interactive fallback. Give them this exact
+line to paste (from the directory picked in step 2):
+
+```bash
+npx @unotest/mobile@latest install <their-app-path> --update-env
+```
+
+They'll see: env check → file scaffold → simulator picker (arrow keys)
+→ permission grant prompt → install logs. Wait for the line
+`✓ Installed <bundle.id>`. That's the success signal.
+
+**5. Hand off to Claude Code.** Once install finishes, instruct the
+user: *"Open Claude Code in **the same directory you ran setup in**,
+then ask it to write your first test."* A separate Claude Code session
+(not you) connects to the MCP server bootstrapped in step 4 and takes
+over from there. Your job ends here — you're setup, not test authoring.
+
+If any step fails, surface the actual error verbatim to the user and
+stop. Don't try alternative paths.
+
 ## Quick start
 
 ```bash
@@ -30,18 +98,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.3",
   "description": "AI-native E2E testing for iOS React Native apps. MCP server + CLI runner + JS-DSL scenarios.",
   "license": "MIT",
   "type": "module",