@shipvo/test 0.1.2 → 0.1.4

package/README.md

@@ -20,6 +20,27 @@ npx shipvo sim          # the simulator, http://localhost:4545
 npx vitest run
 ```
 
+## Plain-language steps
+
+Write a test as plain lines, one step per line. Blank lines and lines starting with `#` are ignored. Quoted text is the element's accessibility name or text, as in `phone.tap("...")`.
+
+```ts
+import { openApp, parseSteps, runSteps } from "@shipvo/test";
+
+const phone = await openApp();
+await runSteps(phone, parseSteps(`
+  # find a lure and put it in the cart
+  type "popper" into "Search" and press enter
+  tap "Add 1 to cart"
+  wait for "Cart"
+  do not see "Error"
+  scroll down
+  go back
+`));
+```
+
+Lines: `tap "X"`, `type "X" into "Y"` (optional `and press enter`), `scroll down`, `go back`, `see "X"`, `do not see "X"`, `wait for "X"`. An unknown line throws a `PhoneError` with code `step_unparsed` and its line number. `runSteps` stops at the first failing step and names its line.
+
 ## Mock the network
 
 Stub what the app's `fetch` gets back, so you can test slow, empty and failing responses without a backend. Requests that match no rule go to the network as usual.

package/dist/index.d.ts

@@ -2,3 +2,8 @@ export { openApp, Phone, Device, Contacts, Calendar, Files, PhoneError } from ".
 export type { DeviceSettings, DeviceProfile, OpenOptions, Notification, Contact, CalendarEvent, SeedFile, MockRule, MockResponse } from "./phone.js";
 export { parseScreen, find } from "./tree.js";
 export type { Node, Target } from "./tree.js";
+export { parseSteps, runSteps } from "./steps.js";
+export type { Step } from "./steps.js";
+export { proposeRepair } from "./repair.js";
+export type { Repair } from "./repair.js";
+export { secret, redact } from "./secrets.js";

package/dist/index.js

@@ -1,2 +1,5 @@
 export { openApp, Phone, Device, Contacts, Calendar, Files, PhoneError } from "./phone.js";
 export { parseScreen, find } from "./tree.js";
+export { parseSteps, runSteps } from "./steps.js";
+export { proposeRepair } from "./repair.js";
+export { secret, redact } from "./secrets.js";

package/dist/phone.js

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
 import { find, parseScreen } from "./tree.js";
+import { redact } from "./secrets.js";
 /** An action the simulator refused. `code` is set for typed failures such as `no_url_listener` or `stale_ref`. */
 export class PhoneError extends Error {
     code;
     constructor(message, code) {
-        super(message);
+        super(redact(message));
         this.code = code;
         this.name = "PhoneError";
     }
@@ -71,7 +72,7 @@ export class Phone {
             return find(this.nodes(), target);
         }
         catch (e) {
-            throw new Error(`${e.message}\n\nScreen now:\n${this.screen}`);
+            throw new Error(redact(`${e.message}\n\nScreen now:\n${this.screen}`));
         }
     }
     async tap(target) { await this.act("tap", { ref: this.locate(target).ref }); return this; }
@@ -94,7 +95,7 @@ export class Phone {
             if (this.sees(text))
                 return this;
             if (Date.now() > end)
-                throw new Error(`timed out waiting for ${text instanceof RegExp ? text : `"${text}"`}\n\nScreen now:\n${this.screen}`);
+                throw new Error(redact(`timed out waiting for ${text instanceof RegExp ? text : `"${text}"`}\n\nScreen now:\n${this.screen}`));
             await new Promise((r) => setTimeout(r, opts.interval ?? 250));
         }
     }
@@ -106,7 +107,7 @@ export class Phone {
             if (!this.sees(text))
                 return this;
             if (Date.now() > end)
-                throw new Error(`"${text}" is still on screen after ${opts.timeout ?? 5000} ms\n\nScreen now:\n${this.screen}`);
+                throw new Error(redact(`"${text}" is still on screen after ${opts.timeout ?? 5000} ms\n\nScreen now:\n${this.screen}`));
             await new Promise((r) => setTimeout(r, opts.interval ?? 250));
         }
     }

package/dist/repair.d.ts

@@ -0,0 +1,18 @@
+import type { Node } from "./tree.js";
+import type { Step } from "./steps.js";
+export type Repair = {
+    kind: "repaired";
+    step: Step;
+    reason: string;
+} | {
+    kind: "unresolved";
+    candidates: Node[];
+};
+/**
+ * Propose a fix for a failed `tap` or `type` step, given the current accessibility tree (a screen string or parsed nodes).
+ * Returns `repaired` when exactly one element with the right role has the closest name. Returns `unresolved`, with the
+ * nearby candidates, when there is none, several are equally close, the best match has a different role, or its label cannot be written in a step line (it has a double quote or a newline).
+ * A repaired step is the same step with a new target: its text, enter flag and line are kept. Other step kinds are always `unresolved`.
+ * This function never removes or skips a step.
+ */
+export declare function proposeRepair(step: Step, tree: string | Node[]): Repair;

package/dist/repair.js

@@ -0,0 +1,65 @@
+import { parseScreen } from "./tree.js";
+const TEXT_ROLES = ["textbox", "searchbox", "spinbutton", "combobox"];
+const TAP_ROLES = ["button", "link", "tab", "checkbox", "switch", "radio", "menuitem", "option"];
+const label = (n) => n.name || n.text;
+const norm = (s) => s.trim().toLowerCase();
+function distance(a, b) {
+    let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const cur = [i];
+        for (let j = 1; j <= b.length; j++)
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        prev = cur;
+    }
+    return prev[b.length];
+}
+/** 1 for equal names, towards 0 for unrelated ones. A name that contains the other counts as close. */
+function similarity(a, b) {
+    a = norm(a);
+    b = norm(b);
+    if (!a || !b)
+        return 0;
+    if (a === b)
+        return 1;
+    const contained = a.includes(b) || b.includes(a) ? 0.5 + 0.5 * (Math.min(a.length, b.length) / Math.max(a.length, b.length)) : 0;
+    return Math.max(contained, 1 - distance(a, b) / Math.max(a.length, b.length));
+}
+const CLOSE = 0.5;
+/**
+ * Propose a fix for a failed `tap` or `type` step, given the current accessibility tree (a screen string or parsed nodes).
+ * Returns `repaired` when exactly one element with the right role has the closest name. Returns `unresolved`, with the
+ * nearby candidates, when there is none, several are equally close, the best match has a different role, or its label cannot be written in a step line (it has a double quote or a newline).
+ * A repaired step is the same step with a new target: its text, enter flag and line are kept. Other step kinds are always `unresolved`.
+ * This function never removes or skips a step.
+ */
+export function proposeRepair(step, tree) {
+    const nodes = typeof tree === "string" ? parseScreen(tree) : tree;
+    if (step.kind !== "tap" && step.kind !== "type")
+        return { kind: "unresolved", candidates: [] };
+    const roles = step.role ? [step.role] : step.kind === "type" ? TEXT_ROLES : TAP_ROLES;
+    const scored = nodes
+        .filter((n) => label(n) !== "")
+        .map((n) => ({ n, s: similarity(step.target, label(n)) }))
+        .filter((x) => x.s >= CLOSE)
+        .sort((a, b) => b.s - a.s);
+    const sameRole = scored.filter((x) => roles.includes(x.n.role));
+    if (sameRole.length === 0)
+        return { kind: "unresolved", candidates: scored.map((x) => x.n) };
+    const top = sameRole.filter((x) => x.s === sameRole[0].s);
+    if (top.length > 1)
+        return { kind: "unresolved", candidates: top.map((x) => x.n) };
+    const best = top[0].n;
+    // A closer match with another role means the role changed: do not guess.
+    if (scored[0].s > top[0].s)
+        return { kind: "unresolved", candidates: scored.map((x) => x.n) };
+    // The step grammar has no escapes, so a label with a quote or newline cannot be written back as a step line.
+    if (/["\r\n]/.test(label(best)))
+        return { kind: "unresolved", candidates: [best] };
+    if (label(best) === step.target)
+        return { kind: "unresolved", candidates: [best] };
+    return {
+        kind: "repaired",
+        step: { ...step, target: label(best) },
+        reason: `${step.kind} target "${step.target}" is now "${label(best)}" (${best.role}, ref ${best.ref})`,
+    };
+}

package/dist/secrets.d.ts

@@ -0,0 +1,6 @@
+/** Read `SHIPVO_TEST_<NAME>` from the environment. Throws, naming the variable, if it is missing or empty. The value is masked as `***` in errors from this package. */
+export declare function secret(name: string): string;
+/** Replace every secret value that was read so far with `***`. */
+export declare function redact(text: string): string;
+/** Replace each `{secret:NAME}` with its value. Throws if a variable is missing. */
+export declare function resolveSecrets(text: string): string;

package/dist/secrets.js

@@ -0,0 +1,29 @@
+/** Secret values read so far. Shared by the whole process and never cleared. */
+const known = new Set();
+/** Values shorter than this are not masked: masking `1` would garble every error. */
+const MIN_MASK = 4;
+/** Read `SHIPVO_TEST_<NAME>` from the environment. Throws, naming the variable, if it is missing or empty. The value is masked as `***` in errors from this package. */
+export function secret(name) {
+    const key = name.toUpperCase();
+    const variable = `SHIPVO_TEST_${key}`;
+    const value = process.env[variable];
+    if (!value) {
+        const err = new Error(`secret "${name}" is not set. Set the environment variable ${variable} (in CI, map a repository secret to it with \`env:\`).`);
+        err.code = "secret_missing";
+        throw err;
+    }
+    if (value.length >= MIN_MASK)
+        known.add(value);
+    return value;
+}
+/** Replace every secret value that was read so far with `***`. */
+export function redact(text) {
+    let out = text;
+    for (const v of [...known].sort((a, b) => b.length - a.length))
+        out = out.split(v).join("***");
+    return out;
+}
+/** Replace each `{secret:NAME}` with its value. Throws if a variable is missing. */
+export function resolveSecrets(text) {
+    return text.replace(/\{secret:([A-Za-z0-9_]+)\}/g, (_m, n) => secret(n));
+}

package/dist/steps.d.ts

@@ -0,0 +1,38 @@
+import type { Phone } from "./phone.js";
+/** One parsed line. `target` is the quoted text: an accessibility name or visible text, as in the typed API. `role` is optional and narrows which elements a repair may pick. `line` is the 1-based line number in the source text. */
+export type Step = {
+    kind: "tap";
+    target: string;
+    role?: string;
+    line: number;
+} | {
+    kind: "type";
+    target: string;
+    text: string;
+    enter: boolean;
+    role?: string;
+    line: number;
+} | {
+    kind: "scroll";
+    direction: "down";
+    line: number;
+} | {
+    kind: "back";
+    line: number;
+} | {
+    kind: "see";
+    text: string;
+    line: number;
+} | {
+    kind: "not_see";
+    text: string;
+    line: number;
+} | {
+    kind: "wait_for";
+    text: string;
+    line: number;
+};
+/** Turn plain-language lines into typed steps. Blank lines and lines starting with `#` are ignored. An unknown line throws a `PhoneError` with code `step_unparsed`. */
+export declare function parseSteps(text: string): Step[];
+/** Run steps in order. Stops at the first failing step and throws an error that names its line. */
+export declare function runSteps(phone: Phone, steps: Step[]): Promise<void>;

package/dist/steps.js

@@ -0,0 +1,67 @@
+import { PhoneError } from "./phone.js";
+import { redact, resolveSecrets } from "./secrets.js";
+const Q = '"([^"]*)"';
+const rules = [
+    [new RegExp(`^tap ${Q}$`, "i"), (m, line) => ({ kind: "tap", target: m[1], line })],
+    [new RegExp(`^type ${Q} into ${Q}( and press enter)?$`, "i"), (m, line) => ({ kind: "type", text: m[1], target: m[2], enter: !!m[3], line })],
+    [/^scroll down$/i, (_m, line) => ({ kind: "scroll", direction: "down", line })],
+    [/^go back$/i, (_m, line) => ({ kind: "back", line })],
+    [new RegExp(`^do not see ${Q}$`, "i"), (m, line) => ({ kind: "not_see", text: m[1], line })],
+    [new RegExp(`^see ${Q}$`, "i"), (m, line) => ({ kind: "see", text: m[1], line })],
+    [new RegExp(`^wait for ${Q}$`, "i"), (m, line) => ({ kind: "wait_for", text: m[1], line })],
+];
+/** Turn plain-language lines into typed steps. Blank lines and lines starting with `#` are ignored. An unknown line throws a `PhoneError` with code `step_unparsed`. */
+export function parseSteps(text) {
+    const steps = [];
+    text.split(/\r?\n/).forEach((raw, i) => {
+        const s = raw.trim();
+        if (!s || s.startsWith("#"))
+            return;
+        for (const [re, make] of rules) {
+            const m = s.match(re);
+            if (m) {
+                steps.push(make(m, i + 1));
+                return;
+            }
+        }
+        throw new PhoneError(`line ${i + 1}: cannot understand "${s}"`, "step_unparsed");
+    });
+    return steps;
+}
+/** Run steps in order. Stops at the first failing step and throws an error that names its line. */
+export async function runSteps(phone, steps) {
+    for (const s of steps) {
+        try {
+            switch (s.kind) {
+                case "tap":
+                    await phone.tap(s.target);
+                    break;
+                case "type":
+                    await phone.type(s.target, resolveSecrets(s.text), s.enter ? { enter: true } : {});
+                    break;
+                case "scroll":
+                    await phone.scroll(s.direction);
+                    break;
+                case "back":
+                    await phone.back();
+                    break;
+                case "wait_for":
+                    await phone.waitFor(s.text);
+                    break;
+                // see and not_see put the screen in the message: the catch below redacts it. Keep that.
+                case "see":
+                    if (!phone.sees(s.text))
+                        throw new Error(`expected to see "${s.text}"\n\nScreen now:\n${phone.screen}`);
+                    break;
+                case "not_see":
+                    if (phone.sees(s.text))
+                        throw new Error(`expected not to see "${s.text}"\n\nScreen now:\n${phone.screen}`);
+                    break;
+            }
+        }
+        catch (e) {
+            const err = e;
+            throw new PhoneError(`step on line ${s.line} failed: ${redact(err.message)}`, err.code ?? "step_failed");
+        }
+    }
+}

package/dist/vitest.js

@@ -3,15 +3,16 @@
 //   test("checkout", async ({ phone }) => { await phone.tap("Add to cart"); expect(phone).toSee("Cart (1)"); });
 import { expect, test as base } from "vitest";
 import { openApp } from "./phone.js";
+import { redact } from "./secrets.js";
 const show = (t) => (t instanceof RegExp ? String(t) : JSON.stringify(t));
 expect.extend({
     toSee(phone, text) {
         const pass = phone.sees(text);
-        return { pass, message: () => (pass ? `expected the screen not to show ${show(text)}\n\n${phone.screen}` : `expected the screen to show ${show(text)}\n\nScreen now:\n${phone.screen}`) };
+        return { pass, message: () => redact(pass ? `expected the screen not to show ${show(text)}\n\n${phone.screen}` : `expected the screen to show ${show(text)}\n\nScreen now:\n${phone.screen}`) };
     },
     toHaveButton(phone, name) {
         const pass = phone.nodes().some((n) => n.role === "button" && (name instanceof RegExp ? name.test(n.name) : n.name === name));
-        return { pass, message: () => (pass ? `expected no button ${show(name)}` : `expected a button ${show(name)}\n\nScreen now:\n${phone.screen}`) };
+        return { pass, message: () => redact(pass ? `expected no button ${show(name)}` : `expected a button ${show(name)}\n\nScreen now:\n${phone.screen}`) };
     },
 });
 /** A fresh simulated phone per test, closed afterwards. Needs the simulator running (npx shipvo sim). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/test",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Typed end-to-end tests for React Native apps that run in the Shipvo simulator: open the app, tap, type, set the phone's location, camera and permissions, and assert on what is on screen. Works in Vitest or any test runner, headless, in CI.",
@@ -17,6 +17,7 @@
     }
   },
   "files": [
+    "skills",
     "dist",
     "README.md"
   ],

package/skills/shipvo-test/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: shipvo-test
+description: Write and run end-to-end tests for a React Native app with @shipvo/test. Use when the project depends on @shipvo/test and you need a typed test, plain-language steps or a network mock.
+---
+
+# @shipvo/test
+
+Headless end-to-end tests that run in the Shipvo simulator. No emulator needed.
+
+```bash
+shipvo sim          # simulator on http://localhost:4545
+npx vitest run      # run typed tests
+shipvo test         # run tests/*.steps
+```
+
+## A typed test
+
+```ts
+import { test, expect } from "@shipvo/test/vitest";
+
+test("adds a lure to the cart", async ({ phone }) => {
+  await phone.tap("Add 1 to cart");
+  expect(phone).toSee("Cart");
+  await phone.waitFor(/1 item/);
+});
+```
+
+Other calls: `phone.type("Search", "popper")`, `phone.scroll("down")`, `phone.back()`, `phone.device.set({ location: { latitude: 4.05, longitude: 9.77 } })`.
+
+## Plain-language steps
+
+One step per line in `tests/<name>.steps`. `#` starts a comment.
+
+```
+tap "Add 1 to cart"
+type "popper" into "Search" and press enter
+scroll down
+go back
+see "X"
+do not see "X"
+wait for "Cart"
+```
+
+An unknown line fails with code `step_unparsed` and its line number. `shipvo test --repair` shows a diff for broken steps; add `--write` to save it.
+
+## Mock the network
+
+```ts
+await phone.mockNetwork([{ url: /\/api\/products/, status: 503, body: { error: "down" }, delayMs: 300 }]);
+await phone.clearNetworkMocks();
+```