@unotest/mobile 0.1.1 → 0.8.1

package/README.md

@@ -1,116 +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
+- **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.
 
-After `init`, Claude Code (or any MCP-aware client) gets:
-
-**Low-level UI:**
-`devices_list`, `screenshot`, `a11y_tree`, `resolve_selector`, `tap`,
-`type`, `press_key`, `swipe`, `open_deeplink`, `app_launch`, `wait_for`,
-`session_reset`.
+## 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/bin/mcp.js

@@ -12,9 +12,10 @@
 // runtime — consumers don't install dev deps.
 
 import { spawn } from "node:child_process";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { dirname, resolve } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const root = resolve(here, "..");
@@ -22,19 +23,65 @@ const root = resolve(here, "..");
 const args = process.argv.slice(2);
 const sub = args[0];
 
+// Meta flags must work without environment setup — before unotest/.env
+// exists, before any subcommand context. Handle them in the dispatcher
+// before routing.
+if (sub === "--version" || sub === "-v") {
+  const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+if (sub === "--help" || sub === "-h") {
+  process.stdout.write(
+    `unotest-mobile — AI-native E2E testing for iOS apps\n\n` +
+      `Usage: unotest-mobile [command] [...args]\n\n` +
+      `Commands:\n` +
+      `  init             Bootstrap a consumer project (env check + scaffold).\n` +
+      `  doctor           Re-run environment checks.\n` +
+      `  install <path>   Install a .app bundle on the configured simulator slot(s).\n` +
+      `  e2e <name>       Run scenario unotest/e2e/<name>.js.\n` +
+      `  lint             Static check of all scenarios + helpers.\n` +
+      `  (no command)     Run as MCP stdio server.\n\n` +
+      `Flags:\n` +
+      `  --version, -v    Print package version.\n` +
+      `  --help, -h       Show this help.\n\n` +
+      `Docs: https://www.npmjs.com/package/@unotest/mobile\n`,
+  );
+  process.exit(0);
+}
+
+// UNOTEST_DEV=1 — used by the evals harness (and useful for local dev)
+// to route subcommands through src/ via tsx instead of the prebuilt dist/.
+// Ensures `npx unotest-mobile lint` in a workdir runs against the CURRENT
+// source, not whatever happens to be in dist/ (or a published npm version).
+const dev = process.env.UNOTEST_DEV === "1";
+const ext = dev ? ".ts" : ".js";
+const baseDir = dev ? "src" : "dist";
+
 function dispatch(sub) {
   switch (sub) {
     case "init":
-      return { entry: "dist/runner/init.js", forwardArgs: args.slice(1) };
+      return { entry: `${baseDir}/runner/init${ext}`, forwardArgs: args.slice(1) };
     case "doctor":
-      return { entry: "dist/runner/doctor.js", forwardArgs: args.slice(1) };
+      return { entry: `${baseDir}/runner/doctor${ext}`, forwardArgs: args.slice(1) };
+    case "install":
+      return { entry: `${baseDir}/runner/install${ext}`, forwardArgs: args.slice(1) };
     case "lint":
-      return { entry: "dist/runner/cli.js", forwardArgs: ["lint"] };
+      return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: ["lint"] };
     case "e2e":
-      return { entry: "dist/runner/cli.js", forwardArgs: args.slice(1) };
+      return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: args.slice(1) };
     default:
       // No-arg invocation → MCP server (current claude mcp add behavior).
-      return { entry: "dist/mcp/server.js", forwardArgs: [] };
+      // Unknown subcommands also land here — print a hint to stderr so
+      // typos like `e2e init` (meant `init`) don't silently route into the
+      // MCP server with a confusing env error.
+      if (sub !== undefined) {
+        process.stderr.write(
+          `[unotest-mobile] unknown command "${sub}" — running MCP server. ` +
+            `See \`unotest-mobile --help\` for available commands.\n`,
+        );
+      }
+      return { entry: `${baseDir}/mcp/server${ext}`, forwardArgs: [] };
   }
 }
 
@@ -57,7 +104,18 @@ if (!paths.includes("/usr/bin") && existsSync("/usr/bin")) {
   env.PATH = `/usr/bin:${env.PATH ?? ""}`;
 }
 
-const child = spawn(process.execPath, [entryPath, ...forwardArgs], {
+// In dev mode, resolve tsx as a loader by absolute path (cwd-independent).
+// tsx walks up node_modules from this dispatcher's location, so it's
+// reliably found even when invoked from a workdir with no node_modules.
+const nodeArgs = [];
+if (dev) {
+  const req = createRequire(import.meta.url);
+  const tsxLoaderPath = req.resolve("tsx", { paths: [root] });
+  nodeArgs.push("--import", pathToFileURL(tsxLoaderPath).href);
+}
+nodeArgs.push(entryPath, ...forwardArgs);
+
+const child = spawn(process.execPath, nodeArgs, {
   stdio: "inherit",
   env,
   // No cwd override — inherit caller's cwd (consumer project root, where