@shipvo/test 0.1.0 → 0.1.2

package/README.md

@@ -20,4 +20,62 @@ npx shipvo sim          # the simulator, http://localhost:4545
 npx vitest run
 ```
 
-Works with any runner through `openApp` from `@shipvo/test`. Full guide, CI workflow and API: [Test your app in CI](/docs/testing/).
+## 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).
+
+**Permission denied**
+
+```ts
+await phone.tap(/^Open cart/);
+await phone.tap("Choose delivery and pay");
+await phone.tap("Use my location");
+await phone.tap("Deny");
+await phone.waitFor("Location permission was not granted.");
+```
+
+**Offline**
+
+```ts
+await phone.device.set({ online: false });
+await phone.waitFor("You're offline");
+```
+
+**Payment decline**
+
+```ts
+await phone.device.set({ payment: { nextResult: "decline", pin: "1234" }, biometrics: { enrolled: true, nextResult: "success" } });
+await phone.tap(/^Open cart/);
+await phone.tap("Choose delivery and pay");
+await phone.tap(/^Any day Shop pickup/);
+await phone.tap("Mobile money");
+await phone.type("Mobile money number", "677000111");
+await phone.tap("Place order");
+await phone.tap("Use fingerprint");
+await phone.type("Mobile money PIN", "1234");
+await phone.tap("Confirm payment");
+await phone.waitFor("Payment declined");
+```
+
+The tests for these flows run against a small fake simulator, not the real app. The fake follows the real screen order and button names.
+
+Works with any runner through `openApp` from `@shipvo/test`. Full guide, CI workflow and API: [Test your app in CI](https://shipvo.dev/docs/testing/).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-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";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { openApp, Phone, Device } from "./phone.js";
+export { openApp, Phone, Device, Contacts, Calendar, Files, PhoneError } from "./phone.js";
 export { parseScreen, find } from "./tree.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,14 @@
 import { existsSync, readFileSync } from "node:fs";
 import { find, parseScreen } from "./tree.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);
+        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 +18,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 +56,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. */
@@ -90,12 +110,17 @@ export class Phone {
             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 +133,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/test",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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.",
@@ -51,6 +51,6 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run"
+    "test": "tsc -p tsconfig.examples.json && vitest run"
   }
 }