@unotest/mobile 0.8.2 → 0.9.1

package/.claude/skills/write-e2e-test.md

@@ -6,7 +6,7 @@ description: Write a new E2E test for the project under test using @unotest/mobi
 # Skill: write-e2e-test
 
 You are writing an end-to-end test using `@unotest/mobile` against an
-iOS React Native app. The test lives in `unotest/e2e/<name>.js` in the
+iOS React Native app. The test lives in `unotest/e2e-mobile/<name>.js` in the
 project under test.
 
 **Default mode is verify-against-live-app.** A test that hasn't been
@@ -35,7 +35,7 @@ Five phases, in this order. Don't skip phases.
 
 ### Phase 0 — read context
 
-`unotest/e2e/_template/example.js` shows the exact DSL syntax (bare
+`unotest/e2e-mobile/_template/example.js` shows the exact DSL syntax (bare
 top-level functions, no `import`/`export`/`async`/`await`/`const`/`let`/
 `var`/arrow-functions). Read it first. The DSL looks like JavaScript
 but is a frozen subset — when your default JS instincts disagree with
@@ -196,9 +196,12 @@ save_exploration_as_test { explorationId, scenarioName: "<name>" }
   with `// SKIPPED` comments.
 - File exists? Pass `overwrite: true`.
 
-The 3-line scenario header (`// id-...`, `// <title>`, `// #<color>`)
-is emitted automatically by the generator above the
-`function test_<name>()` line.
+Every executable statement in a `test_*` body MUST live inside a
+`step("human-readable intent", () => { ... })` block - the linter's
+`validator:step-coverage` rule enforces it. The generator groups
+recorded sections into `step(...)` blocks automatically; keep the
+labels meaningful when editing (they're what an agent reads when
+repairing a broken step).
 
 ### Phase 5 — reset state, then run_test
 
@@ -213,6 +216,10 @@ Via MCP — reinstall the app to wipe its sandbox AND auth tokens:
 app_install { path: "<APP_PATH from unotest/.env>", clean: true }
 ```
 
+To just PREPARE devices (boot SIM_POOL + install APP_PATH, no wipe),
+the viewer's App panel runs `npx unotest-mobile app-server` and holds
+it; runs then find booted sims with the build installed.
+
 **Do NOT pass `erase: true`.** `erase: true` runs `simctl erase` which
 wipes the entire simulator including WebDriverAgent. `clean: true`
 alone is the right soft-reset — it now resets the keychain too, so
@@ -354,7 +361,7 @@ Time: `today()`, `daysFromNow(n)`, `nowMs()`.
 
 ## Helpers convention
 
-Reusable steps go in `unotest/e2e/_helpers/<group>.js`. Helper naming
+Reusable steps go in `unotest/e2e-mobile/_helpers/<group>.js`. Helper naming
 is **snake_case** (`signin_as`, `seed_workout`). **Before recording an
 inline flow, check `_helpers/` for an existing helper** — `Glob` or
 `Read`. If `signin_as(email, password)` exists, the generated test
@@ -363,7 +370,7 @@ should call it instead of re-recording four steps. (After
 for the helper call.)
 
 ```
-unotest/e2e/_helpers/auth.js:
+unotest/e2e-mobile/_helpers/auth.js:
 function signin_as(email, password) { ... }
 ```
 
@@ -394,13 +401,15 @@ npx unotest-mobile lint
 ```
 
 Lint codes to recognize:
-- E1/E2 — unknown function or unsupported statement (drift to plain JS).
-- E5 — wrong arg count for a built-in.
-- E6 — wrong arg TYPE / order, e.g. `swipe(getByTestId("x"), "up")` —
-  argTypes are `("up"|..., selector)`.
-- E7 — missing 3-line header above `test_*`/`flow_*` (generator emits
-  it; only fires if you hand-edited).
-- E8 — helper used but not defined in `_helpers/`.
+- E2 — statement/expression outside the frozen subset (drift to plain JS).
+- E3 — `setDevice()` with an unknown sim slot.
+- E8 — duplicate helper name / shadowing a built-in.
+- validator:unknown-function — typo'd or undefined function name.
+- validator:arity — wrong arg count for a built-in.
+- validator:arg-kind — wrong arg TYPE / order, e.g.
+  `swipe(getByTestId("x"), "up")` — argTypes are `("up"|..., selector)`.
+- validator:step-coverage — a statement in a `test_*` body is not inside
+  `step("description", () => { ... })`. Wrap it.
 
 If lint flags `import`/`export`/`await`/`const` — re-read the DSL
 section above and rewrite.

package/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.9.1] - 2026-06-14
+
+### Changed
+
+- **`@unotest/studio` integration** — the mobile runner participates in the
+  desktop shell ("mobile in studio").
+- Ecosystem version lockstep to `0.9.1`.
+
+## [0.9.0] - 2026-06-11
+
+### Added
+
+- **Viewer integration.** The mobile runner now drives the localhost
+  `@unotest/viewer`: run artifacts (`steps.jsonl` / `runtime.json` / manifest),
+  live runtime state, the debug control plane (step / continue / abort / pause +
+  breakpoints), and snapshot / console / failure capture — so a mobile run is
+  inspectable in the same UI as web.
+
+### Changed
+
+- **Workspace overlay + shared packages.** Moved into the `@unotest` pnpm
+  workspace overlay; adopts the shared `@unotest/core` (run / runtime writers,
+  debug-commands watcher) and the `@unotest/dsl` executor instead of forked
+  copies.
+
+## [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

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
@@ -22,7 +90,7 @@ npx @unotest/mobile@latest e2e <test-name>
 ```
 
 That's it. You never edit DSL by hand — the agent writes the scenarios,
-you review the resulting `.js` files in `unotest/e2e/`.
+you review the resulting `.js` files in `unotest/e2e-mobile/`.
 
 ## How it works
 
@@ -48,7 +116,7 @@ you review the resulting `.js` files in `unotest/e2e/`.
   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`.
+- **Tests are plain `.js` files in your repo.** `unotest/e2e-mobile/*.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
@@ -82,8 +150,9 @@ agent already knows; you don't wire anything.
 | `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 e2e <name>` | Run `unotest/e2e-mobile/<name>.js`. |
 | `npx @unotest/mobile@latest lint` | Static check of all scenarios + helpers. |
+| `npx @unotest/mobile@latest viewer` | Start the local results viewer (HTTP+WS) with mobile as the active target; opens in your browser. |
 | `npx @unotest/mobile@latest` (no args) | Run as MCP stdio server (this is what Claude Code launches). |
 
 ## License

package/bin/{mcp.js → unotest-mobile.js}

@@ -6,6 +6,7 @@
 //   unotest-mobile doctor       → re-run environment checks
 //   unotest-mobile e2e <name>   → run scenario unotest/e2e/<name>.js
 //   unotest-mobile lint         → lint scenarios + helpers
+//   unotest-mobile viewer       → start the local results viewer (HTTP+WS)
 //
 // All entries are compiled by tsup to dist/ before publish; this dispatcher
 // just resolves the right one and execs it via plain node. No tsx at
@@ -41,6 +42,8 @@ if (sub === "--help" || sub === "-h") {
       `  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` +
+      `  viewer           Start the local results viewer (HTTP+WS server).\n` +
+      `  app-server       Boot SIM_POOL sims + install APP_PATH; hold until Ctrl-C.\n` +
       `  (no command)     Run as MCP stdio server.\n\n` +
       `Flags:\n` +
       `  --version, -v    Print package version.\n` +
@@ -70,6 +73,12 @@ function dispatch(sub) {
       return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: ["lint"] };
     case "e2e":
       return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: args.slice(1) };
+    case "viewer":
+      return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: ["viewer"] };
+    case "app-server":
+      // Device holder (M-16): boot SIM_POOL + install APP_PATH, hold
+      // until SIGTERM. Spawned by the viewer's App panel.
+      return { entry: `${baseDir}/runner/cli${ext}`, forwardArgs: ["app-server"] };
     default:
       // No-arg invocation → MCP server (current claude mcp add behavior).
       // Unknown subcommands also land here — print a hint to stderr so

package/dist/dsl/mobile-dsl-language-service.d.ts

@@ -0,0 +1,12 @@
+import { IDslLanguageService, DslVocabEntry, DslValidateContext, DslDiagnostic } from '@unotest/protocol';
+
+declare class MobileDslLanguageService implements IDslLanguageService {
+    private readonly vocab;
+    private readonly registry;
+    constructor();
+    getVocab(): DslVocabEntry[];
+    validate(source: string, ctx?: DslValidateContext): DslDiagnostic[];
+}
+declare const mobileDslLanguageService: MobileDslLanguageService;
+
+export { MobileDslLanguageService, mobileDslLanguageService as default, mobileDslLanguageService };