@unotest/mobile 0.8.3 → 0.10.0

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,47 @@ 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.10.0] - 2026-08-06
+
+### Patch Changes
+
+- Updated dependencies [7ed750c]
+- Updated dependencies [574841f]
+- Updated dependencies [337a31c]
+  - @unotest/dsl@0.10.0
+  - @unotest/protocol@0.10.0
+  - @unotest/core@0.10.0
+  - @unotest/viewer@0.10.0
+
+## [0.9.2] - 2026-06-16
+
+Released in lockstep with the rest of the ecosystem. No functional changes.
+
+## [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
@@ -37,8 +78,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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
+  → `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
@@ -88,7 +129,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `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
+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.
@@ -148,7 +189,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `result.detectedPermissions`.
 - **Pre-grant on install.** When the resolved permissions list is
   non-empty, every service is granted with `simctl privacy <udid> grant
-  <service> <bundleId>` immediately after install. Pre-empts SpringBoard
+<service> <bundleId>` immediately after install. Pre-empts SpringBoard
   permission dialogs (location, motion, photos, …) that would otherwise
   block scenarios on first launch — those dialogs live in SpringBoard,
   not in the app's a11y tree.
@@ -188,7 +229,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **New `alert:` section in `mode: "outline"`.** When a native
   `UIAlertController` is on screen its title, body, and button labels
   appear as the first section of the outline, plus a `_meta.alert_active:
-  true` flag. Previously the alert lived in SpringBoard (outside the
+true` flag. Previously the alert lived in SpringBoard (outside the
   app's a11y tree) and the agent kept tapping the underlying button
   through the modal — usually the wrong one, sometimes destructive.
 - **Grammar contract.** The `alert:` section and `_meta.alert_active`
@@ -242,7 +283,7 @@ After the fixes, `run_test` on a freshly-generated exploration returned
   is unchanged — keychain reset only fires when the caller explicitly
   opts into a fresh state.
 - Keychain reset is invoked **unconditionally** in the `app_install
-  { clean: true }` flow even when `simctl uninstall` reports "app not
+{ clean: true }` flow even when `simctl uninstall` reports "app not
   installed" — prior-run tokens may still linger, that's the whole
   reason for B5.
 - MCP descriptions for `app_install`'s `clean` parameter and
@@ -258,7 +299,7 @@ After the fixes, `run_test` on a freshly-generated exploration returned
   one tool — `explore_step { action: "tap" | "type" | … }`. The single
   rule: passing `explorationId` records the call into an exploration
   session; omitting it runs the action ad-hoc. There is no `record:
-  false` override.
+false` override.
 - **Alerts (`accept_alert`, `dismiss_alert`) appear here for the first
   time as `explore_step` actions** — not as separate tools. The
   Driver+DSL alert layer landed in P0; this release wires the MCP
@@ -359,12 +400,12 @@ unchanged.
     on UIAlertController, last on action sheet).
   - `readAlert()` — return title + body of the active alert as a string,
     or throw `NoAlertPresentError` if none is on screen.
-  Before this, scenarios had no way to dismiss SpringBoard alerts: the
-  resolver-driven `tap(getByTestId(...))` couldn't reach buttons that
-  live outside the app process — `ordinal` selectors appeared to match
-  but the tap landed on the wrong element. Pre-granting permissions via
-  `xcrun simctl privacy` was the only workaround. MCP exposure (as
-  `explore_step` actions) lands in a follow-up.
+    Before this, scenarios had no way to dismiss SpringBoard alerts: the
+    resolver-driven `tap(getByTestId(...))` couldn't reach buttons that
+    live outside the app process — `ordinal` selectors appeared to match
+    but the tap landed on the wrong element. Pre-granting permissions via
+    `xcrun simctl privacy` was the only workaround. MCP exposure (as
+    `explore_step` actions) lands in a follow-up.
 
 ## [0.3.0] — 2026-05-15
 
@@ -435,7 +476,7 @@ unchanged.
 
 - **Simulator runtime disambiguation.** When multiple simulators share
   a name across iOS versions, pin to one via `SIM_A_NAME=<name> @
-  <runtime>` (e.g. `SIM_A_NAME=iPhone 16 @ iOS 17.5`). The runtime
+<runtime>` (e.g. `SIM_A_NAME=iPhone 16 @ iOS 17.5`). The runtime
   part is matched as a substring of the friendly runtime name, so
   partial values like `iOS 17` work too. The `Sim "X" not found` error
   now lists all available sims with their runtime.
@@ -468,7 +509,7 @@ unchanged.
   persist.
 - **Pre-launch precondition check.** `WdaDriver.getSession()` now
   verifies `APP_BUNDLE_ID` is installed on the target sim via `simctl
-  get_app_container` before starting the WDA session. If missing, throws
+get_app_container` before starting the WDA session. If missing, throws
   a clear actionable error pointing at `unotest-mobile install`.
 - `SimctlAdapter.isInstalled(udid, bundleId)` and
   `SimctlAdapter.erase(udid)` — exposed on the adapter; ios-utils gains

package/README.md

@@ -90,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
 
@@ -116,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
@@ -150,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 };