@shipvo/test 0.1.1 → 0.1.3

package/README.md

@@ -20,6 +20,46 @@ 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.
+
+```ts
+import { test, expect } from "@shipvo/test/vitest";
+
+test("shows an error when the catalogue is down", async ({ phone }) => {
+  await phone.mockNetwork([
+    { url: /\/api\/products/, status: 503, body: { error: "down" }, delayMs: 300 },
+  ]);
+  await phone.tap("Reload");
+  await phone.waitFor(/try again/i);
+  await phone.clearNetworkMocks(); // back to the real network
+});
+```
+
+A rule has `url` (a string that must equal the full request URL, or a RegExp), an optional `method` (any method if left out), `status`, `body` (a string, or an object sent as JSON), optional `headers` and optional `delayMs`. The first matching rule wins, and each `mockNetwork` call replaces the earlier rules. Only `fetch` and XHR calls are stubbed. A bad rule throws a `PhoneError` with code `mock_invalid`.
+
 ## Failure-path examples
 
 Runnable versions are in [`examples/flows.ts`](examples/flows.ts). They use the Tide & Tackle labels. Change them to match your app. The checkout flows need a cart, so open the phone with one: `openApp({ seedCart: [{ product_id: "rod-surf-36", quantity: 1 }] })`. The full purchase is in [`checkout.test.ts`](../../apps/tide-and-tackle/tests/checkout.test.ts).

package/dist/index.d.ts

@@ -1,4 +1,9 @@
-export { openApp, Phone, Device } from "./phone.js";
-export type { DeviceSettings, DeviceProfile, OpenOptions, Notification } from "./phone.js";
+export { openApp, Phone, Device, Contacts, Calendar, Files, PhoneError } from "./phone.js";
+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 } from "./phone.js";
+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.d.ts

@@ -1,4 +1,27 @@
 import { type Node, type Target } from "./tree.js";
+/** One address-book entry. */
+export type Contact = {
+    id: string;
+    name: string;
+    phoneNumbers?: string[];
+    emails?: string[];
+};
+/** One calendar event. `start` and `end` are ISO 8601 strings. */
+export type CalendarEvent = {
+    id: string;
+    title: string;
+    start: string;
+    end: string;
+    allDay?: boolean;
+    location?: string;
+    notes?: string;
+};
+/** A file the simulated picker offers. `content` is its text. */
+export type SeedFile = {
+    name: string;
+    mimeType: string;
+    content: string;
+};
 type Grant = "granted" | "denied" | "undetermined";
 /** What the simulated phone has. Takes effect for the next action. */
 export type DeviceSettings = {
@@ -19,7 +42,15 @@ export type DeviceSettings = {
         camera?: Grant;
         location?: Grant;
         notifications?: Grant;
+        contacts?: Grant;
+        calendar?: Grant;
     };
+    /** The address book the app can read once contacts permission is granted. Replaces the current one. */
+    contacts?: Contact[];
+    /** The calendar events the app can read once calendar permission is granted. Replaces the current ones. */
+    calendar?: CalendarEvent[];
+    /** The files the file picker offers. Replaces the current ones. */
+    files?: SeedFile[];
     biometrics?: {
         enrolled?: boolean;
         nextResult?: "success" | "fail" | "cancel";
@@ -52,8 +83,26 @@ export type Notification = {
     body: string;
     data?: Record<string, unknown>;
 };
+/** An action the simulator refused. `code` is set for typed failures such as `no_url_listener` or `stale_ref`. */
+export declare class PhoneError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/** What a mocked request answers with. An object `body` is sent as JSON. */
+export type MockResponse = {
+    status: number;
+    body?: string | Record<string, unknown> | unknown[] | null;
+    headers?: Record<string, string>;
+    delayMs?: number;
+};
+/** A string `url` must equal the full request URL. A RegExp is tested against it. Without `method`, any method matches. The first matching rule wins. */
+export type MockRule = {
+    url: string | RegExp;
+    method?: string;
+} & MockResponse;
 type Reply = {
     ok: boolean;
+    code?: string;
     screen?: string | null;
     error?: string;
     path?: string;
@@ -61,6 +110,8 @@ type Reply = {
     log?: unknown[];
     capabilities?: unknown;
     release?: string | number;
+    delivered?: boolean;
+    id?: string;
 };
 /** A simulated phone running your app. Every action returns once the screen has settled, and updates `screen`. */
 export declare class Phone {
@@ -71,6 +122,13 @@ export declare class Phone {
     /** The current screen as an accessibility tree. */
     screen: string;
     readonly device: Device;
+    /** The simulated address book. */
+    readonly contacts: Contacts;
+    readonly calendar: Calendar;
+    /** The notification shade. Call it to list notifications; `receive` and `tap` deliver and open one. */
+    readonly notifications: Notifications;
+    /** The simulated file picker. */
+    readonly files: Files;
     constructor(session: string, sim: string, app: string, release: string | number);
     /** @internal */
     call(path: string, body: Record<string, unknown>): Promise<Reply>;
@@ -99,16 +157,21 @@ export declare class Phone {
         timeout?: number;
         interval?: number;
     }): Promise<this>;
-    /** Deliver a push notification: it shows as a banner the app can be opened from. */
+    /** Deliver a push notification: it shows as a banner the app can be opened from. It reaches the app only if notification permission is granted (`phone.device.set({ permissions: { notifications: "granted" } })`); otherwise nothing is delivered and this still resolves. Use `phone.notifications.receive()` to learn whether it was delivered. */
     notify(n: {
         title: string;
         body: string;
         data?: Record<string, unknown>;
     }): Promise<this>;
-    /** The notification shade (banners vanish after about 5 s, the shade keeps them). */
-    notifications(): Promise<Notification[]>;
     /** Tap a notification from the shade (the newest if no id). */
     openNotification(id?: string): Promise<this>;
+    /** Open a deep link in the app, as a push tap or share link would. Throws a `PhoneError` with code `no_url_listener` if the app has no `onUrl` listener. */
+    openUrl(url: string): Promise<this>;
+    /** Stub `fetch` and XHR calls the app makes. Replaces earlier rules. Unmatched requests go to the network as usual.
+     * Throws a `PhoneError` with code `mock_invalid` for a bad rule. */
+    mockNetwork(rules: MockRule[]): Promise<this>;
+    /** Remove every network mock. */
+    clearNetworkMocks(): Promise<this>;
     /** What the app did with the device: permission prompts and answers, location reads, scans, fingerprint checks, payments. */
     deviceLog(): Promise<unknown[]>;
     /** A PNG of the screen. Works when the test runs on the same machine as the simulator, as in CI. */
@@ -116,6 +179,45 @@ export declare class Phone {
     /** Nothing to release on the simulator side today; kept so tests read the same if that changes. */
     close(): Promise<void>;
 }
+/** Turns rules into the wire format. The sim's parseMockRules (packages/sim/mock-rules.mjs) reads it: the two must stay in sync. */
+export declare function encodeMockRules(rules: MockRule[]): unknown[];
+/** The simulated address book. Apps read it with `expo-contacts` or `device.contacts.getAll()`; writing back is not simulated. */
+export declare class Contacts {
+    private readonly phone;
+    constructor(phone: Phone);
+    /** Seed the address book (replaces what was there). The app still asks for permission; answer with `phone.device.set({ permissions: { contacts } })` or tap the dialog. */
+    set(contacts: Contact[]): Promise<Phone>;
+}
+/** `phone.notifications()` lists the shade (banners vanish after about 5 s, the shade keeps them). */
+export interface Notifications {
+    (): Promise<Notification[]>;
+    /** Push a notification to the app. It reaches the app only if notification permission is granted; resolves `false` (and the app sees nothing) when it is not. */
+    receive(n: {
+        title: string;
+        body: string;
+        data?: Record<string, unknown>;
+    }): Promise<boolean>;
+    /** Tap a notification in the shade (the newest if no id): the app's tap handler runs with its `data`. */
+    tap(id?: string): Promise<Phone>;
+}
+/** The simulated file picker. The app opens it with `expo-document-picker` or `device.files.pick()`; you answer it here. */
+export declare class Files {
+    private readonly phone;
+    constructor(phone: Phone);
+    /** Seed the files the picker offers (replaces what was there). */
+    set(files: SeedFile[]): Promise<Phone>;
+    /** Pick a file in the open picker dialog by name. */
+    pick(name: string): Promise<Phone>;
+    /** Cancel the open picker dialog. */
+    cancel(): Promise<Phone>;
+}
+/** The simulated calendar. Apps read it with `expo-calendar` or `device.calendar.getEvents()`; writing back is not simulated. */
+export declare class Calendar {
+    private readonly phone;
+    constructor(phone: Phone);
+    /** Seed the calendar (replaces what was there). The app still asks for permission; answer with `phone.device.set({ permissions: { calendar } })` or tap the dialog. */
+    set(events: CalendarEvent[]): Promise<Phone>;
+}
 /** The simulated phone's hardware and settings. */
 export declare class Device {
     private readonly phone;

package/dist/phone.js

@@ -1,5 +1,15 @@
 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(redact(message));
+        this.code = code;
+        this.name = "PhoneError";
+    }
+}
 /** A simulated phone running your app. Every action returns once the screen has settled, and updates `screen`. */
 export class Phone {
     session;
@@ -9,12 +19,23 @@ export class Phone {
     /** The current screen as an accessibility tree. */
     screen = "";
     device;
+    /** The simulated address book. */
+    contacts;
+    calendar;
+    /** The notification shade. Call it to list notifications; `receive` and `tap` deliver and open one. */
+    notifications;
+    /** The simulated file picker. */
+    files;
     constructor(session, sim, app, release) {
         this.session = session;
         this.sim = sim;
         this.app = app;
         this.release = release;
         this.device = new Device(this);
+        this.contacts = new Contacts(this);
+        this.calendar = new Calendar(this);
+        this.files = new Files(this);
+        this.notifications = makeNotifications(this);
     }
     /** @internal */
     async call(path, body) {
@@ -36,7 +57,7 @@ export class Phone {
                 this.screen = again.screen;
         }
         if (!r.ok)
-            throw new Error(`${action} failed: ${r.error}\n\nScreen now:\n${this.screen}`);
+            throw new PhoneError(`${action} failed: ${r.error}\n\nScreen now:\n${this.screen}`, r.code);
         return r;
     }
     /** Every element on the current screen. */
@@ -51,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; }
@@ -74,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));
         }
     }
@@ -86,16 +107,21 @@ 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));
         }
     }
-    /** Deliver a push notification: it shows as a banner the app can be opened from. */
+    /** Deliver a push notification: it shows as a banner the app can be opened from. It reaches the app only if notification permission is granted (`phone.device.set({ permissions: { notifications: "granted" } })`); otherwise nothing is delivered and this still resolves. Use `phone.notifications.receive()` to learn whether it was delivered. */
     async notify(n) { await this.act("push_notification", n); return this; }
-    /** The notification shade (banners vanish after about 5 s, the shade keeps them). */
-    async notifications() { return (await this.act("notifications")).notifications ?? []; }
     /** Tap a notification from the shade (the newest if no id). */
     async openNotification(id) { await this.act("open_notification", { id }); return this; }
+    /** Open a deep link in the app, as a push tap or share link would. Throws a `PhoneError` with code `no_url_listener` if the app has no `onUrl` listener. */
+    async openUrl(url) { await this.act("open_url", { url }); return this; }
+    /** Stub `fetch` and XHR calls the app makes. Replaces earlier rules. Unmatched requests go to the network as usual.
+     * Throws a `PhoneError` with code `mock_invalid` for a bad rule. */
+    async mockNetwork(rules) { await this.act("set_network_mocks", { rules: encodeMockRules(rules) }); return this; }
+    /** Remove every network mock. */
+    async clearNetworkMocks() { await this.act("set_network_mocks", { rules: [] }); return this; }
     /** What the app did with the device: permission prompts and answers, location reads, scans, fingerprint checks, payments. */
     async deviceLog() { return (await this.act("device_log")).log ?? []; }
     /** A PNG of the screen. Works when the test runs on the same machine as the simulator, as in CI. */
@@ -108,6 +134,73 @@ export class Phone {
     /** Nothing to release on the simulator side today; kept so tests read the same if that changes. */
     async close() { }
 }
+/** Turns rules into the wire format. The sim's parseMockRules (packages/sim/mock-rules.mjs) reads it: the two must stay in sync. */
+export function encodeMockRules(rules) {
+    const bad = (i, why) => new PhoneError(`mockNetwork rule ${i}: ${why}`, "mock_invalid");
+    if (!Array.isArray(rules))
+        throw new PhoneError("mockNetwork needs an array of rules", "mock_invalid");
+    return rules.map((r, i) => {
+        if (!r || typeof r !== "object")
+            throw bad(i, "must be an object");
+        const { url, method, status, body, headers, delayMs } = r;
+        if (!(typeof url === "string" && url) && !(url instanceof RegExp))
+            throw bad(i, "url must be a non-empty string or a RegExp");
+        if (method !== undefined && (typeof method !== "string" || !method))
+            throw bad(i, "method must be a non-empty string");
+        if (!Number.isInteger(status) || status < 100 || status > 599)
+            throw bad(i, "status must be an integer from 100 to 599");
+        if (delayMs !== undefined && (typeof delayMs !== "number" || !(delayMs >= 0) || delayMs > 60000))
+            throw bad(i, "delayMs must be a number from 0 to 60000");
+        const h = { ...(headers ?? {}) };
+        let text = "";
+        if (typeof body === "string")
+            text = body;
+        else if (body !== undefined && body !== null) {
+            text = JSON.stringify(body);
+            if (!Object.keys(h).some((k) => k.toLowerCase() === "content-type"))
+                h["content-type"] = "application/json";
+        }
+        return { ...(typeof url === "string" ? { url } : { urlRegex: { source: url.source, flags: url.flags } }), method, response: { status, body: text, headers: h, delayMs } };
+    });
+}
+/** The simulated address book. Apps read it with `expo-contacts` or `device.contacts.getAll()`; writing back is not simulated. */
+export class Contacts {
+    phone;
+    constructor(phone) {
+        this.phone = phone;
+    }
+    /** Seed the address book (replaces what was there). The app still asks for permission; answer with `phone.device.set({ permissions: { contacts } })` or tap the dialog. */
+    async set(contacts) { await this.phone.act("set_device", { device: { contacts } }); return this.phone; }
+}
+function makeNotifications(phone) {
+    const list = async () => ((await phone.act("notifications")).notifications ?? []);
+    return Object.assign(list, {
+        async receive(n) { return (await phone.act("push_notification", n)).delivered === true; },
+        async tap(id) { await phone.act("open_notification", { id }); return phone; },
+    });
+}
+/** The simulated file picker. The app opens it with `expo-document-picker` or `device.files.pick()`; you answer it here. */
+export class Files {
+    phone;
+    constructor(phone) {
+        this.phone = phone;
+    }
+    /** Seed the files the picker offers (replaces what was there). */
+    async set(files) { await this.phone.act("set_device", { device: { files } }); return this.phone; }
+    /** Pick a file in the open picker dialog by name. */
+    async pick(name) { return this.phone.tap({ role: "button", name }); }
+    /** Cancel the open picker dialog. */
+    async cancel() { return this.phone.tap({ role: "button", name: "Cancel" }); }
+}
+/** The simulated calendar. Apps read it with `expo-calendar` or `device.calendar.getEvents()`; writing back is not simulated. */
+export class Calendar {
+    phone;
+    constructor(phone) {
+        this.phone = phone;
+    }
+    /** Seed the calendar (replaces what was there). The app still asks for permission; answer with `phone.device.set({ permissions: { calendar } })` or tap the dialog. */
+    async set(events) { await this.phone.act("set_device", { device: { calendar: events } }); return this.phone; }
+}
 /** The simulated phone's hardware and settings. */
 export class Device {
     phone;

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.1",
+  "version": "0.1.3",
   "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.",