@unotest/mobile 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.1] — 2026-05-18
+
+### Fixed — `init` pins the exact `@unotest/mobile` version in `.mcp.json`
+
+- **What broke.** The generated `.mcp.json` entry used a bare
+  `"args": ["-y", "@unotest/mobile"]` with no version pin. `npx` then
+  resolved that name against any **globally installed** copy first
+  (e.g. an old `npm i -g @unotest/mobile@0.1.x` from earlier
+  experimentation), bypassing the version the user just installed via
+  `npx @unotest/mobile@latest install ...`. The stale global frequently
+  had the pre-0.1.4 strict env schema, so the MCP server crashed at
+  startup with `Invalid environment. ... INVITE_DEEPLINK_PREFIX:
+  Required, API_BASE_URL: Required, ...`. Claude Code then surfaced
+  `-32000 Connection closed` and the agent fell back to draft-mode
+  scenario authoring — defeating the entire MCP-driven flow the
+  install just bootstrapped.
+- **Fix.** `init` now reads its own `package.json:version` and writes
+  the pinned form `"args": ["-y", "@unotest/mobile@<version>"]` into
+  `.mcp.json`. The MCP server Claude Code launches always matches the
+  `init`-running copy, so a stale global can no longer ambush startup.
+  Pre-release versions (e.g. `1.0.0-rc.3`) pass through verbatim.
+- **Migration.** Existing projects generated by `init` ≤ 0.8.0 keep
+  the bare entry. Run `npx @unotest/mobile@latest init --force` to
+  rewrite `.mcp.json` with the pinned form (preserves `.env`, only
+  rewrites templates).
+- Tests: +3 (`mcpServerEntry: pins to passed version`,
+  `pre-release versions pass through verbatim`,
+  `never emits a bare unversioned reference`). The third is the
+  belt-and-braces regression guard that fails loudly if anyone
+  reintroduces a bare `@unotest/mobile` arg in the template.
+
 ## [0.8.0] — 2026-05-18
 
 ### Fixed — WdaDriver auto-recovers from stale WDA sessions (B6)

package/README.md

@@ -1,123 +1,90 @@
 # `@unotest/mobile`
 
-**AI-native E2E testing for iOS React Native apps.** MCP server + CLI
-runner + JS-DSL scenarios. Project-agnostic — works with any RN/Expo app,
-not tied to a specific backend stack.
+**AI-native E2E testing for iOS apps.** An MCP server + CLI + JS-DSL
+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.
 
-Part of the `unotest` family. The web counterpart is a separate product.
-
-## Install
+## Quick start
 
 ```bash
-npm install --save-dev @unotest/mobile        # or yarn / pnpm — same effect
-npx @unotest/mobile init                      # bootstrap your project
-```
+# 1. Point us at your .app build. Auto-detects bundle ID, URL scheme,
+#    and required permissions from Info.plist; offers to bootstrap
+#    unotest/ and .mcp.json on first run.
+npx @unotest/mobile@latest install /path/to/Your.app --update-env
 
-`init` first runs an environment check (macOS / Xcode / iOS Simulator /
-Node 20+) and hard-fails on a non-macOS host before touching the
-filesystem. It then drops:
+# 2. Open Claude Code in this project. Ask: "write an e2e test for
+#    sign-in". The agent uses the MCP server to explore your app,
+#    record a scenario, and verify it runs end-to-end.
 
-- `unotest/e2e/` with a starter scenario, template, and `_helpers/` dir
-- `unotest/AGENTS.md` — short pointer for AI coding agents
-- `unotest/.env.example` (committed) and `unotest/.env` (gitignored)
-- `.claude/skills/write-e2e-test.md` — the Claude Code skill the agent
-  uses when asked to write a test
-- `.mcp.json` — project-scoped MCP registration (merges with existing)
-- `.gitignore` updates
+# 3. (Optional) Re-run any saved test from the CLI:
+npx @unotest/mobile@latest e2e <test-name>
+```
 
-`--force` overwrites existing files (except `unotest/.env`).
-`--allow-non-macos` lets you scaffold on a CI prep stage.
+That's it. You never edit DSL by hand — the agent writes the scenarios,
+you review the resulting `.js` files in `unotest/e2e/`.
 
-## Quick start
+## How it works
 
-```bash
-# 1. Edit unotest/.env — fill in DATABASE_URL, SIM_A_NAME, APP_BUNDLE_ID, ...
-# 2. Boot iOS simulators matching SIM_A_NAME / SIM_B_NAME (Xcode → Devices).
-# 3. Open Claude Code in this project — MCP server auto-registers via .mcp.json.
-#    Ask the agent to write a test; it follows the `write-e2e-test` skill.
-
-npx @unotest/mobile doctor               # re-check environment
-npx @unotest/mobile e2e smoke-welcome    # run the starter scenario
-npx @unotest/mobile lint                 # static check of all scenarios
 ```
-
-## What this gives you
-
-- **AI-driven authoring.** Claude (via MCP) sees your screen and
-  accessibility tree — it doesn't guess testIDs, it resolves them.
-- **Pause-on-failure debugger.** When a step fails, the runtime pauses;
-  use `inspect_runtime` / `step` / `resume` to fix and retry without
-  rerunning setup.
-- **Multi-device flows.** Two simulators in parallel — useful for
-  invite/share/handoff flows where one user's action must surface on
-  another user's device.
-- **Engine-agnostic.** Today's driver is WebDriverAgent (HTTP, no JVM);
-  swap to your own XCTest / idb backend without rewriting scenarios.
-
-## DSL — strict JS subset
-
-Scenarios are JS files (`unotest/e2e/*.js`) with one entry function per
-file. The full reference is bundled with the package as the
-`write-e2e-test` Claude Code skill — open
-`.claude/skills/write-e2e-test.md` after `init` for the cheat sheet.
-
-```js
-// id-smoke-welcome
-// First-run sanity: harness reaches sim, WDA, and app launch handshake
-// #00aa00
-function test_smoke_welcome() {
-  setDevice("A");
-  appLaunch(true);
-  waitFor(getByTestId("screen-welcome"), 15000);
-  assertVisible(getByTestId("btn-start"));
-}
+┌─────────────┐  MCP (stdio)   ┌──────────────────┐
+│ Claude Code │ ◀────────────▶ │ @unotest/mobile  │
+└─────────────┘   tool calls   │  (this package)  │
+                                └────────┬─────────┘
+                                         │ HTTP
+                                ┌────────▼──────────┐
+                                │  WebDriverAgent   │
+                                │  (Apple's XCUI    │
+                                │   driver, on sim) │
+                                └────────┬──────────┘
+                                         │
+                                ┌────────▼──────────┐
+                                │  iOS Simulator    │
+                                │  Your .app        │
+                                └───────────────────┘
 ```
 
-## MCP tools
-
-After `init`, Claude Code (or any MCP-aware client) gets:
+- **The agent sees the accessibility tree, not screenshots.** WDA
+  returns a structured tree (roles, testID, text, bounds); we render it
+  as a token-cheap text outline. Works on RN/Expo and on plain Swift
+  apps too, as long as they expose accessibility.
+- **Tests are plain `.js` files in your repo.** `unotest/e2e/*.js`.
+  Goes into git, into code review, into CI. No proprietary format, no
+  binary blob.
+- **The DSL is a sandboxed JS subset.** Scenarios run in a vendored AST
+  interpreter — they can't `require`, `fetch`, touch the filesystem, or
+  import anything. AI-generated tests are safe to run blindly.
+- **Pause-on-failure debugger.** When a step throws, the runtime
+  freezes mid-scenario. The agent (or you) calls `inspect_runtime`,
+  patches the scenario, and `resume`s from the same step — no full
+  simulator restart, no rerunning setup.
+- **Local-only.** Everything runs on your Mac. Your `.app` never leaves
+  the machine.
+
+**Life of a test:** the agent explores your app live (taps real
+buttons, reads the live a11y tree) → records the actions → emits a JS
+scenario → runs it through our interpreter → on failure, pauses,
+patches, resumes. Every step goes through one of ~15 MCP tools the
+agent already knows; you don't wire anything.
 
-**Discovery + lifecycle:**
-`devices_list`, `screenshot`, `a11y_tree`, `resolve_selector`,
-`app_install`, `session_reset`.
-
-**Exploration recording (P2):**
-`explore_start`, `explore_step`, `explore_record`, `explore_remove_step`,
-`explore_state`, `explore_stop`, `generate_dsl_from_exploration`,
-`save_exploration_as_test`. `explore_step` is the single execute-and-
-optionally-record entry point for all UI actions (tap, type, press_key,
-swipe, wait_for, app_launch, open_deeplink, accept_alert, dismiss_alert).
-Pass `explorationId` to record into a session, omit it for ad-hoc.
+## Requirements
 
-**Pause-on-failure debugger:**
-`run_test` (with `pauseOnFailure: true`), `step`, `resume`,
-`inspect_runtime`, `abort_runtime`, `list_runtimes`.
+- **macOS** with Xcode + iOS Simulator (Apple licensing — iOS
+  simulators don't run on Linux/Windows).
+- **Node 20+** (for `npx`; you don't need a Node project).
+- First run of WebDriverAgent compiles once and caches under
+  `~/.cache/unotest/mobile/wda/` — ~5–15 min, subsequent runs reuse it.
 
 ## CLI
 
 | Command | What it does |
 |---|---|
-| `npx @unotest/mobile init` | Bootstrap a consumer project. Idempotent. |
-| `npx @unotest/mobile doctor` | Re-run environment checks. |
-| `npx @unotest/mobile e2e <name>` | Run `unotest/e2e/<name>.js`. Supports nested paths. |
-| `npx @unotest/mobile lint` | Static check of all scenarios + helpers. |
-| `npx @unotest/mobile` (no args) | Run as MCP stdio server. |
-
-## Requirements
-
-- **macOS** with Xcode + iOS Simulator (Apple licensing — iOS simulators
-  cannot run on Linux/Windows hosts).
-- **Node 20+**.
-- **Xcode command-line tools** for the on-demand WebDriverAgent build.
-  WDA is compiled once and cached in
-  `~/.cache/unotest/mobile/wda/<version>/` — first build is ~5–15
-  minutes, subsequent runs reuse the cache.
-
-## Status
-
-`0.1.0` — initial public release. iOS-focused (RN, Expo, native Swift).
-Android driver is on the roadmap. Local execution only; cloud runners
-will follow.
+| `npx @unotest/mobile@latest install <path>` | Install a `.app` on the configured sim; auto-detect bundle ID + permissions; `--update-env` persists. |
+| `npx @unotest/mobile@latest init` | Just bootstrap `unotest/` + `.mcp.json` without installing an app. |
+| `npx @unotest/mobile@latest doctor` | Re-check the environment (Xcode, sim, Node, WDA cache). |
+| `npx @unotest/mobile@latest e2e <name>` | Run `unotest/e2e/<name>.js`. |
+| `npx @unotest/mobile@latest lint` | Static check of all scenarios + helpers. |
+| `npx @unotest/mobile@latest` (no args) | Run as MCP stdio server (this is what Claude Code launches). |
 
 ## License
 

package/dist/runner/init.js

@@ -290,10 +290,20 @@ WDA_PORTS=A=8100,B=8101
     "unotest/artifacts/",
     "unotest/sessions/"
   ],
-  mcpServerEntry: {
+  /**
+   * Build the `.mcp.json` entry for this package, pinned to the supplied
+   * version. Caller (`runInit`) reads its own `package.json:version` and
+   * passes it in, so the entry written into the consumer's project
+   * always matches the `init`-running copy. Pinning side-steps the
+   * `npx` stale-global / stale-cache ambush: a bare `@unotest/mobile`
+   * arg lets `npx` resolve to whatever globally-installed (often very
+   * old) copy a developer happens to have, which then crashes at
+   * startup against the current env schema.
+   */
+  mcpServerEntry: /* @__PURE__ */ __name((version) => ({
     command: "npx",
-    args: ["-y", "@unotest/mobile"]
-  }
+    args: ["-y", `@unotest/mobile@${version}`]
+  }), "mcpServerEntry")
 };
 
 // src/runner/init/mcp-config-merger.ts
@@ -391,6 +401,20 @@ function readPackageFile(relativePath) {
   return readFileSync(abs, "utf8");
 }
 __name(readPackageFile, "readPackageFile");
+function readOwnVersion() {
+  const pkgRaw = readPackageFile("package.json");
+  if (pkgRaw === null) {
+    throw new Error(
+      `package.json missing at ${packageRoot}. This is a packaging bug \u2014 reinstall \`@unotest/mobile\` or report the issue.`
+    );
+  }
+  const parsed = JSON.parse(pkgRaw);
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error(`package.json:version is not a non-empty string`);
+  }
+  return parsed.version;
+}
+__name(readOwnVersion, "readOwnVersion");
 function runInit(argv = process.argv.slice(2)) {
   const opts = parseInitArgs(argv);
   const target = process.cwd();
@@ -446,10 +470,7 @@ function runInit(argv = process.argv.slice(2)) {
     const merge = mergeMcpConfig(
       existing,
       "unotest-mobile",
-      {
-        command: templates.mcpServerEntry.command,
-        args: [...templates.mcpServerEntry.args]
-      },
+      templates.mcpServerEntry(readOwnVersion()),
       { force: opts.force }
     );
     if (merge.action !== "already-present") {

package/dist/runner/install.js

@@ -930,10 +930,20 @@ WDA_PORTS=A=8100,B=8101
     "unotest/artifacts/",
     "unotest/sessions/"
   ],
-  mcpServerEntry: {
+  /**
+   * Build the `.mcp.json` entry for this package, pinned to the supplied
+   * version. Caller (`runInit`) reads its own `package.json:version` and
+   * passes it in, so the entry written into the consumer's project
+   * always matches the `init`-running copy. Pinning side-steps the
+   * `npx` stale-global / stale-cache ambush: a bare `@unotest/mobile`
+   * arg lets `npx` resolve to whatever globally-installed (often very
+   * old) copy a developer happens to have, which then crashes at
+   * startup against the current env schema.
+   */
+  mcpServerEntry: /* @__PURE__ */ __name((version) => ({
     command: "npx",
-    args: ["-y", "@unotest/mobile"]
-  }
+    args: ["-y", `@unotest/mobile@${version}`]
+  }), "mcpServerEntry")
 };
 
 // src/runner/init/mcp-config-merger.ts
@@ -1031,6 +1041,20 @@ function readPackageFile(relativePath) {
   return readFileSync(abs, "utf8");
 }
 __name(readPackageFile, "readPackageFile");
+function readOwnVersion() {
+  const pkgRaw = readPackageFile("package.json");
+  if (pkgRaw === null) {
+    throw new Error(
+      `package.json missing at ${packageRoot}. This is a packaging bug \u2014 reinstall \`@unotest/mobile\` or report the issue.`
+    );
+  }
+  const parsed = JSON.parse(pkgRaw);
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error(`package.json:version is not a non-empty string`);
+  }
+  return parsed.version;
+}
+__name(readOwnVersion, "readOwnVersion");
 function runInit(argv = process.argv.slice(2)) {
   const opts = parseInitArgs(argv);
   const target = process.cwd();
@@ -1086,10 +1110,7 @@ function runInit(argv = process.argv.slice(2)) {
     const merge = mergeMcpConfig(
       existing,
       "unotest-mobile",
-      {
-        command: templates.mcpServerEntry.command,
-        args: [...templates.mcpServerEntry.args]
-      },
+      templates.mcpServerEntry(readOwnVersion()),
       { force: opts.force }
     );
     if (merge.action !== "already-present") {

package/package.json

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