@unotest/mobile 0.8.3 → 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,31 @@ 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

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 };