@unotest/mobile 0.1.0

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

@@ -0,0 +1,294 @@
+---
+name: write-e2e-test
+description: Write a new E2E test for the project under test using @unotest/mobile. Use when the user asks to write/cover/add a test for a feature, flow, or screen.
+---
+
+# Skill: write-e2e-test
+
+You are writing an end-to-end test using `@unotest/mobile` against an iOS
+React Native app. Tests live in `unotest/e2e/` inside the **project under
+test** (not in the `@unotest/mobile` package itself).
+
+This skill is the single source of truth — everything you need to write a
+correct test is below. Do not hunt for separate docs.
+
+## Before you write
+
+1. **Survey existing helpers** in `unotest/e2e/_helpers/`. Don't reinvent
+   `signin`, `seed_user_*`, `wipe_*` — reuse what's there. If a helper
+   you need doesn't exist, add it to `_helpers/<topic>.js` (not inline).
+
+2. **Survey existing scenarios** in `unotest/e2e/`. Match the style and
+   reuse the same setup/seed patterns.
+
+3. **Read the env file** `unotest/.env`. It tells you the app's bundle id,
+   simulator slot names, database URL, project CLI paths.
+
+4. **Ask the user only what you can't infer:** which feature/flow to test,
+   which user role if the app has roles, happy path, negative cases. Do
+   not ask about conventions — they are below.
+
+## Scenario shape
+
+Four phases per scenario — Setup, Enter, Act, Assert.
+
+```js
+// id-<scenario-id>
+// <one-line human description>
+// #<6-digit hex color>
+function test_<entry_name>() {
+  // 1. SETUP — DB / API / CLI fixtures
+  wipe_e2e_users();
+  user_id = seed_user("e2e-user@example.com", "e2e-pass-1234");
+
+  // 2. ENTER — bring the app to a known initial UI state
+  setDevice("A");
+  appLaunch(true);
+  waitFor(getByTestId("screen-welcome"), 15000);
+
+  // 3. ACT — the actions you're testing
+  signin("e2e-user@example.com", "e2e-pass-1234");
+  waitFor(getByTestId("screen-home"), 15000);
+  tap(getByTestId("btn-create-item"));
+  type(getByTestId("input-title"), "Hello");
+  tap(getByTestId("btn-save"));
+
+  // 4. ASSERT — UI + data checks
+  assertVisible(getByTestId("item-row-Hello"));
+  count = dbQuery("SELECT count(*)::text FROM items WHERE user_id = $1", user_id);
+  assertEqual(count, "1");
+}
+```
+
+The **3-line comment header** above `function` is mandatory for `test_*`
+and `flow_*` (linter rule E7). The order is fixed: id, description, hex
+color. The header is metadata used by the future Blockly visual editor;
+keep it stable.
+
+## DSL — strict JS subset
+
+The DSL is **not** full JavaScript. The parser rejects what the
+visual-editor target (Blockly) can't render.
+
+**Allowed:**
+- Top-level `function name(args) { ... }` definitions
+- Bare-name assignment: `x = expr;` (no `var`/`let`/`const`)
+- `if`/`else`, blocks `{ ... }`
+- Function calls (statement or expression position)
+- Literals: number, string, `true` / `false` / `null`
+- Array literals `[a, b, c]` (used for variadic args)
+- Arithmetic: `+ - * /`
+- Comparisons: `== != < <= > >=`
+- Logical: `&& ||`
+- String concatenation: `"a" + "b"`
+
+**Forbidden** (linter will reject):
+- `var` / `let` / `const`
+- `for` / `while` (`maxSteps` budget protects from infinite loops)
+- Object literals `{a: 1}` — pass payloads as JSON-as-string instead
+- Member access `obj.field` — primitives only
+- Index access `arr[i]`
+- Unary `!` / `-` (use `0 - n` for negative numbers)
+- `===` / `!==` (use `==` / `!=`)
+- `+=` / `-=` / `++` / `--`
+- Arrow functions, classes, destructuring
+- Nested function definitions
+
+For structured payloads, pass JSON as a string:
+```js
+apiCall("POST", "/api/users", '{"email":"x@y.z","name":"X"}');
+```
+
+## DSL functions
+
+### Device
+
+| Function | Effect |
+|---|---|
+| `setDevice(slot)` | Switch the "current device" for subsequent UI calls. `slot` must be in `EnvConfig.simBySlot` (defined in `unotest/.env`, e.g. `"A"` or `"B"`). |
+| `appLaunch(clean?)` | Launch the app under test. `clean=true` → terminate + relaunch from clean state. |
+| `openDeeplink(url)` | Open a URL on the current device. |
+
+### Selectors (pure — return Selector objects, no driver call)
+
+| Function | Returns |
+|---|---|
+| `getByTestId(s)` | `{ testId: s }` |
+| `getByText(s)` | `{ text: s }` |
+| `getByLabel(s)` | `{ label: s }` |
+| `ordinal(target, n)` | wraps a Selector with `ordinal: n` (0-indexed) |
+| `near(target, anchor, maxPx?)` | wraps a Selector with `near: { anchor, maxDistancePx? }` |
+
+`testId`, `text`, `label` are **equal-priority citizens** — there is no
+implicit fallback chain. Use `getByText` on custom buttons that lack a
+`testID`. iOS surfaces a React Native `testID` as the WDA `name` attribute.
+
+### UI actions
+
+| Function | Behavior |
+|---|---|
+| `tap(selector)` | Auto-wait up to `defaultActionWaitMs`, then tap the element's center. |
+| `type(selector, text)` | Auto-wait, tap to focus, send keys. |
+| `swipe(direction, fromSel?)` | Direction is `"up"` / `"down"` / `"left"` / `"right"`. If `fromSel` is given, auto-wait + swipe from its center; else from screen center. |
+| `pressKey(key)` | `"home"` / `"enter"` / `"escape"`. iOS has no `back`. No selector → no auto-wait. |
+| `waitFor(selector, timeoutMs?)` | Explicit poll up to `defaultWaitForTimeoutMs`. |
+| `pause(ms)` | Sleep. Use sparingly; prefer `waitFor`. |
+
+### Data
+
+| Function | Description |
+|---|---|
+| `dbQuery(sql, ...args)` | Parameterized SELECT through `DbClient` (pg / mysql / sqlite, picked by `DATABASE_URL`). Returns the **first cell of the first row** as a string. For multi-row results use multiple `dbQuery` calls. |
+| `dbExec(sql, ...args)` | Parameterized INSERT/UPDATE/DELETE. If the driver returned rows (e.g. `INSERT ... RETURNING` on pg or sqlite 3.35+), returns the first cell of the first row; otherwise `""`. Does not parse the SQL. |
+| `apiCall(method, path, body?, headers?)` | HTTP request via `ApiClient.call`. `body` is JSON-as-string. Returns raw response body. |
+| `shell(cmd, ...args)` | `execFile`-style spawn — args go straight to `child_process` argv with **no shell interpretation**. Throws on non-zero exit. Returns stdout. |
+
+Project-specific seeding (creating users, fixtures, etc.) lives in
+`unotest/e2e/_helpers/`. The core `@unotest/mobile` package does not know
+about your backend stack — you wire it via `shell` / `dbExec` / `apiCall`.
+
+### Time
+
+| Function | Description |
+|---|---|
+| `today()` | ISO date `YYYY-MM-DD` (UTC) for the runtime. |
+| `daysFromNow(n)` | ISO date `n` days from today. For negative n use `daysFromNow(0 - n)` — the DSL has no unary minus. |
+| `nowMs()` | Unix timestamp in milliseconds (useful for unique suffixes). |
+
+### Assertions
+
+| Function | Effect |
+|---|---|
+| `assertEqual(a, b)` | Throws if `a !== b`. |
+| `assertVisible(selector)` | Resolves the selector against the current screen; throws if no match. |
+| `assertCount(selector, n)` | Probes `ordinal: 0..N-1`; throws if the total count is not `n`. |
+| `assertEnabled(selector)` | Resolves against the **raw** a11y tree (not compact). Throws if `enabled !== true` or the field is missing. |
+| `assertDisabled(selector)` | Same, expects `enabled === false`. |
+
+## Helpers
+
+- Live in `unotest/e2e/_helpers/*.js`. Globally visible to all scenarios.
+- `snake_case` function names (`seed_user`, `signin`, `wipe_e2e_users`).
+- `return` is **allowed** in helpers (forbidden in `test_*` / `flow_*`).
+- **Snapshot scoping**: helper mutations don't leak to caller variables.
+  Pass information back via return values.
+- Recursion depth capped at `maxCallDepth` (default 32).
+- Cross-file: every file under `_helpers/` is auto-loaded for every
+  scenario — convention, not magic.
+
+Extract to a helper when:
+- 5+ lines repeat across 2+ scenarios.
+- A piece of setup needs to be available to many tests.
+
+Don't extract prematurely — one-off code stays inline.
+
+Example:
+
+```js
+// unotest/e2e/_helpers/seed.js
+function seed_user(email, password) {
+  shell("npm", "--prefix", "./apps/api", "run", "cli", "--",
+        "create-user", "--email", email, "--password", password);
+  return dbQuery("SELECT id FROM users WHERE email = $1", email);
+}
+```
+
+## Setup strategy
+
+Pick the highest viable option:
+
+1. **`shell()` to a project CLI** — goes through real business logic
+   (password hashing, hooks, side effects). Best fidelity.
+   ```js
+   shell("npm", "run", "cli", "--", "create-user", "--email", email);
+   ```
+2. **`apiCall()`** — when the CLI doesn't exist but the endpoint does.
+3. **Direct `dbExec("INSERT INTO ...")`** — only when intentionally
+   bypassing business logic. Rare; document why.
+
+For dates, use `today()` / `daysFromNow(n)`. **Never** hardcode a date
+like `"2026-05-12"` — tests would silently rot.
+
+## Cleanup
+
+Wipe **at the start of the scenario**, not at the end. Failed runs skip
+end-of-test cleanup; start-of-test cleanup always runs.
+
+```js
+function test_X() {
+  wipe_e2e_users();   // beginning — always runs
+  // ...
+}
+```
+
+## Authoring workflow
+
+1. **Plan the test.** One-line description. Decide setup, actor, assertion.
+2. **Pick a path:**
+   - Single feature → `unotest/e2e/<feature>/<actor>-<verb>-<context>.js`
+   - Cross-feature smoke / integration → `unotest/e2e/<actor>-<verb>-<context>.js`
+3. **Copy `unotest/e2e/_template.js`**, rename, adjust the 3-line header
+   (id / description / color).
+4. **Write setup** using existing helpers. If you need a new one, add to
+   `_helpers/<topic>.js` first, then use it.
+5. **Run via MCP `run_test` with `pauseOnFailure: true`:**
+   - On pause: `inspect_runtime <id>` → see vars, last error.
+   - Use `screenshot` + `a11y_tree` to understand UI state.
+   - Use `resolve_selector` to find correct testIDs (returns the top-3
+     near-misses with reasons when no exact match).
+   - Fix the scenario, then `resume <id>` to retry the failed step.
+   - Once green: `abort_runtime <id>` to teardown.
+6. **Lint:** `npx @unotest/mobile lint` (also runs automatically on every
+   `e2e <name>`).
+
+## Linter codes
+
+| Code | Severity | Meaning |
+|---|---|---|
+| E1 | error | Function name not in `FunctionRegistry` and not declared as a user helper. |
+| E2 | error | AST node outside the MVP subset, or `return` in a `test_*` / `flow_*` body. |
+| E3 | error | `setDevice("X")` slot not in `EnvConfig.simBySlot`. |
+| E4 | error | JSON-string arg in `apiCall` doesn't parse. |
+| W5 | warn  | An `assert*` call before any UI action — likely a typo. |
+| E7 | error | `test_*` / `flow_*` function missing the 3-line header (`// id-...`, `// description`, `// #color`) immediately above `function`. |
+| E8 | error | Duplicate user-function name, or a user function shadows a built-in. |
+
+## Common antipatterns
+
+- **Hardcoding testIDs without verifying** them in the app. Use
+  `resolve_selector` first to confirm the ID exists.
+- **Inlining 30 lines of signin** in every scenario — extract a `signin` helper.
+- **One mega-test** covering everything — split by actor / action so
+  failures point at one thing.
+- **Tests depending on each other's state** — every scenario must be
+  self-contained.
+- **Using `getByText("...")` when a `testID` exists** — `testID` is stable
+  across locale changes; visible text is not.
+- **Hardcoding dates** — use `today()` / `daysFromNow(n)`.
+- **Object literals or member access** — DSL forbids them; use JSON
+  strings and primitive returns.
+
+## When the test fails to run
+
+| Symptom | Likely cause |
+|---|---|
+| `Invalid environment` | `unotest/.env` missing keys. Compare to `.env.example`. |
+| `ECONNREFUSED` from `dbQuery` | `DATABASE_URL` not reachable. For docker Postgres, ensure the host port is exposed (`ports: ["5432:5432"]`). |
+| `relation "..." does not exist` | DB migrations not run, or a helper references a table that doesn't exist in this project. |
+| `Sim "X" not found` | `SIM_A_NAME` / `SIM_B_NAME` in `.env` don't match `xcrun simctl list devices`. |
+| `Entry function "test_X" not found` | File basename doesn't match the function name. Convention: `unotest/e2e/<path>/foo-bar.js` → `function test_foo_bar()`. |
+
+If a selector resolves to the wrong element or times out: use
+`resolve_selector` (MCP) to see the top-3 near-misses with reasons.
+
+## Output to user
+
+After writing tests:
+
+1. **Summarize the scenarios you added** — file paths, one line each.
+2. **List any new helpers added** to `_helpers/`.
+3. **Call out app-side TODOs** — missing `testID`s, missing CLI
+   subcommands, missing DB schema. Don't silently assume; surface them
+   so the user can decide.
+4. **Confirm `npx @unotest/mobile lint` passes.** If you ran `run_test`,
+   report pass/fail per scenario.

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+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.1.0] — 2026-05-14
+
+Initial public release.
+
+### Added
+
+- MCP server with low-level UI tools (`tap`, `type`, `swipe`, `screenshot`,
+  `a11y_tree`, `resolve_selector`, `app_launch`, `wait_for`, ...) and a
+  paused-on-failure debugger (`run_test`, `step`, `resume`, `inspect_runtime`).
+- CLI runner: `unotest-mobile init`, `doctor`, `e2e <name>`, `lint`.
+- JS-DSL scenario authoring (strict subset of JS — see the `write-e2e-test`
+  Claude Code skill for the reference).
+- WebDriverAgent driver for iOS Simulator, with on-demand build and per-version
+  cache (`~/.cache/unotest/mobile/wda/`).
+- Multi-device support (slot A / slot B simulators, parallel WDA sessions).
+- Multi-DB plugin (Postgres, MySQL, SQLite) selected by `DATABASE_URL`.
+- `unotest-mobile init` bootstraps consumer projects with `unotest/e2e/`
+  layout, `.mcp.json` registration, and the `write-e2e-test` skill.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Volkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# `@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.
+
+Part of the `unotest` family. The web counterpart is a separate product.
+
+## Install
+
+```bash
+npm install --save-dev @unotest/mobile        # or yarn / pnpm — same effect
+npx @unotest/mobile init                      # bootstrap your project
+```
+
+`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:
+
+- `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
+
+`--force` overwrites existing files (except `unotest/.env`).
+`--allow-non-macos` lets you scaffold on a CI prep stage.
+
+## Quick start
+
+```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 tools
+
+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`.
+
+**Pause-on-failure debugger:**
+`run_test` (with `pauseOnFailure: true`), `step`, `resume`,
+`inspect_runtime`, `abort_runtime`, `list_runtimes`.
+
+## 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.
+
+## License
+
+[MIT](./LICENSE)

package/bin/mcp.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// CLI dispatcher for @unotest/mobile.
+//
+//   unotest-mobile              → MCP server (default; no subcommand)
+//   unotest-mobile init         → bootstrap consumer project
+//   unotest-mobile doctor       → re-run environment checks
+//   unotest-mobile e2e <name>   → run scenario unotest/e2e/<name>.js
+//   unotest-mobile lint         → lint scenarios + helpers
+//
+// 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
+// runtime — consumers don't install dev deps.
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { existsSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+
+const args = process.argv.slice(2);
+const sub = args[0];
+
+function dispatch(sub) {
+  switch (sub) {
+    case "init":
+      return { entry: "dist/runner/init.js", forwardArgs: args.slice(1) };
+    case "doctor":
+      return { entry: "dist/runner/doctor.js", forwardArgs: args.slice(1) };
+    case "lint":
+      return { entry: "dist/runner/cli.js", forwardArgs: ["lint"] };
+    case "e2e":
+      return { entry: "dist/runner/cli.js", forwardArgs: args.slice(1) };
+    default:
+      // No-arg invocation → MCP server (current claude mcp add behavior).
+      return { entry: "dist/mcp/server.js", forwardArgs: [] };
+  }
+}
+
+const { entry, forwardArgs } = dispatch(sub);
+const entryPath = resolve(root, entry);
+
+if (!existsSync(entryPath)) {
+  process.stderr.write(
+    `[unotest-mobile] missing build artifact: ${entry}\n` +
+      `Did you forget to run \`pnpm build\`? (In a published package this should not happen — please open an issue.)\n`,
+  );
+  process.exit(1);
+}
+
+// Hygiene: ensure /usr/bin is on PATH (xcrun etc.) even when launched from
+// minimal-PATH contexts like Claude Desktop.
+const env = { ...process.env };
+const paths = (env.PATH ?? "").split(":");
+if (!paths.includes("/usr/bin") && existsSync("/usr/bin")) {
+  env.PATH = `/usr/bin:${env.PATH ?? ""}`;
+}
+
+const child = spawn(process.execPath, [entryPath, ...forwardArgs], {
+  stdio: "inherit",
+  env,
+  // No cwd override — inherit caller's cwd (consumer project root, where
+  // unotest/e2e/ and unotest/.env live).
+});
+child.on("exit", (code) => process.exit(code ?? 1));