nativeproof 0.1.1

package/dist/mock-server.js

@@ -0,0 +1,122 @@
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+function pathOf(rawUrl) {
+    const url = rawUrl ?? "/";
+    const query = url.indexOf("?");
+    return query === -1 ? url : url.slice(0, query);
+}
+function frameType(frame, fallback) {
+    return typeof frame.type === "string" ? frame.type : fallback;
+}
+/** Valid WebSocket application close codes are 3000-4999; anything else falls back to 4000. */
+function wsCloseCode(code) {
+    return code >= 3000 && code <= 4999 ? code : 4000;
+}
+export async function startMockServer(options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const recorded = [];
+    const routes = new Map();
+    const sockets = new Set();
+    const record = (path, direction, type, payload) => {
+        recorded.push({ path, type, direction, payload });
+    };
+    const http = createServer((req, res) => {
+        const path = pathOf(req.url);
+        record(path, "sent", "request", { method: req.method ?? "GET" });
+        const action = routes.get(path);
+        if (action?.kind === "reject") {
+            res.statusCode = action.code;
+            res.end();
+            return;
+        }
+        if (action?.kind === "abort") {
+            req.destroy();
+            return;
+        }
+        res.setHeader("content-type", "application/json");
+        if (action?.kind === "fulfill") {
+            record(path, "received", frameType(action.frame, "response"), action.frame);
+            res.end(JSON.stringify(action.frame));
+            return;
+        }
+        res.end("{}");
+    });
+    const wss = new WebSocketServer({ server: http });
+    wss.on("connection", (socket, req) => {
+        const path = pathOf(req.url);
+        const entry = { socket, path };
+        sockets.add(entry);
+        record(path, "sent", "open", {});
+        const action = routes.get(path);
+        if (action?.kind === "reject") {
+            socket.close(wsCloseCode(action.code), String(action.code));
+            return;
+        }
+        if (action?.kind === "abort") {
+            socket.terminate();
+            return;
+        }
+        socket.on("message", (data) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(data.toString());
+            }
+            catch {
+                parsed = { raw: data.toString() };
+            }
+            const payload = parsed && typeof parsed === "object" ? parsed : {};
+            record(path, "sent", frameType(payload, "message"), payload);
+        });
+        socket.on("close", () => {
+            sockets.delete(entry);
+        });
+        if (action?.kind === "fulfill") {
+            record(path, "received", frameType(action.frame, "message"), action.frame);
+            socket.send(JSON.stringify(action.frame));
+        }
+    });
+    await new Promise((resolve) => {
+        http.listen(options.port ?? 0, host, () => resolve());
+    });
+    const address = http.address();
+    const port = typeof address === "object" && address !== null ? address.port : (options.port ?? 0);
+    return {
+        url: `http://${host}:${port}`,
+        wsUrl: `ws://${host}:${port}`,
+        port,
+        async frames() {
+            return recorded.slice();
+        },
+        route(path) {
+            return {
+                fulfill: (frame) => {
+                    routes.set(path, { kind: "fulfill", frame });
+                },
+                reject: (opts) => {
+                    routes.set(path, { kind: "reject", code: opts.code });
+                },
+                abort: () => {
+                    routes.set(path, { kind: "abort" });
+                },
+            };
+        },
+        send(path, frame) {
+            for (const entry of sockets) {
+                if (entry.path === path) {
+                    record(path, "received", frameType(frame, "message"), frame);
+                    entry.socket.send(JSON.stringify(frame));
+                }
+            }
+        },
+        async stop() {
+            for (const entry of sockets)
+                entry.socket.terminate();
+            wss.close();
+            // Drop any lingering keep-alive sockets so http.close() actually resolves.
+            http.closeAllConnections();
+            await new Promise((resolve) => {
+                http.close(() => resolve());
+            });
+        },
+    };
+}

package/dist/mock.d.ts

@@ -0,0 +1,54 @@
+import { type WaitOptions } from "./locator.js";
+/**
+ * Backend mocking that feels like Playwright's `page.route()`.
+ *
+ * The framework owns the *contract* — observe the frames an app exchanged, and
+ * intercept a path to control its reply — while a consuming app injects the concrete
+ * backend (a mock WebSocket/REST server). With it, `expect(mock).toHaveSent(...)`
+ * replaces hand-rolled log parsing and `mock.route("/x").reject(...)` reads like
+ * network interception. The framework imports nothing app-specific.
+ */
+/** Direction of a frame relative to the app under test. */
+export type FrameDirection = "sent" | "received";
+/** One observed protocol frame (a REST call or socket message), normalised. */
+export interface MockFrame {
+    readonly path: string;
+    readonly type: string;
+    readonly direction: FrameDirection;
+    readonly payload?: Readonly<Record<string, unknown>>;
+}
+/** A partial frame to match against: `path` / `type` plus any payload fields. */
+export interface FrameMatch {
+    path?: string;
+    type?: string;
+    [key: string]: unknown;
+}
+/** Controls how an intercepted path replies — the Playwright `Route` equivalent. */
+export interface MockRoute {
+    /** Answer with a canned frame/body. */
+    fulfill(frame: Record<string, unknown>): void;
+    /** Reject the connect/request with an error code. */
+    reject(options: {
+        code: number;
+    }): void;
+    /** Drop the connect/request entirely. */
+    abort(): void;
+}
+export interface MockBackend {
+    /** Every frame observed so far, in order, both directions. */
+    frames(): Promise<readonly MockFrame[]>;
+    /** Intercept a path and control its reply. */
+    route(path: string): MockRoute;
+    /** Release the backend (stop the server, close sockets). */
+    stop(): Promise<void>;
+}
+/**
+ * True if `frame` satisfies every field of `match`: `path` / `type` at the top level,
+ * every other key against the frame's payload.
+ */
+export declare function matchesFrame(frame: MockFrame, match: FrameMatch): boolean;
+export declare function describeMatch(match: FrameMatch): string;
+/** Single-shot check: does any observed frame match `match` in `direction`? */
+export declare function frameExists(mock: MockBackend, direction: FrameDirection, match: FrameMatch): Promise<boolean>;
+/** Poll until a frame matching `match` in `direction` appears, or the timeout elapses. */
+export declare function waitForFrame(mock: MockBackend, direction: FrameDirection, match: FrameMatch, options?: WaitOptions): Promise<boolean>;

package/dist/mock.js

@@ -0,0 +1,30 @@
+import { waitUntil } from "./locator.js";
+/**
+ * True if `frame` satisfies every field of `match`: `path` / `type` at the top level,
+ * every other key against the frame's payload.
+ */
+export function matchesFrame(frame, match) {
+    if (match.path !== undefined && frame.path !== match.path)
+        return false;
+    if (match.type !== undefined && frame.type !== match.type)
+        return false;
+    for (const [key, value] of Object.entries(match)) {
+        if (key === "path" || key === "type")
+            continue;
+        if (frame.payload?.[key] !== value)
+            return false;
+    }
+    return true;
+}
+export function describeMatch(match) {
+    return JSON.stringify(match);
+}
+/** Single-shot check: does any observed frame match `match` in `direction`? */
+export async function frameExists(mock, direction, match) {
+    const frames = await mock.frames();
+    return frames.some((frame) => frame.direction === direction && matchesFrame(frame, match));
+}
+/** Poll until a frame matching `match` in `direction` appears, or the timeout elapses. */
+export function waitForFrame(mock, direction, match, options = {}) {
+    return waitUntil(() => frameExists(mock, direction, match), (present) => present, options);
+}

package/dist/page.d.ts

@@ -0,0 +1,24 @@
+import type { Driver } from "./driver.js";
+import { type Locator, type Selector, type WaitOptions } from "./locator.js";
+/**
+ * Playwright-style `getBy*` ergonomics over a {@link Driver}, so selectors are
+ * discovered, not inferred. `page(driver).getByText("Submit")` returns a {@link Locator}
+ * and you never spell out which native attribute backs it.
+ */
+export interface Page {
+    /** Escape hatch: a locator from a raw selector. */
+    locator(selector: Selector, options?: WaitOptions): Locator;
+    getByText(text: string, options?: WaitOptions): Locator;
+    getByTestId(testId: string, options?: WaitOptions): Locator;
+    getByLabel(label: string, options?: WaitOptions): Locator;
+    getById(id: string, options?: WaitOptions): Locator;
+    /**
+     * Match by accessible name. Native accessibility trees don't expose web-style roles
+     * reliably, so `role` is advisory and the dependable signal is the name (the element's
+     * accessibility label). Pass `{ name }`.
+     */
+    getByRole(role: string, options: {
+        name: string;
+    } & WaitOptions): Locator;
+}
+export declare function page(driver: Driver): Page;

package/dist/page.js

@@ -0,0 +1,17 @@
+import { by, locator } from "./locator.js";
+export function page(driver) {
+    return {
+        locator: (selector, options = {}) => locator(driver, selector, options),
+        getByText: (text, options = {}) => locator(driver, by.text(text), options),
+        getByTestId: (testId, options = {}) => locator(driver, by.testId(testId), options),
+        getByLabel: (label, options = {}) => locator(driver, by.label(label), options),
+        getById: (id, options = {}) => locator(driver, by.id(id), options),
+        getByRole: (role, options) => {
+            const { name, ...wait } = options;
+            if (!name) {
+                throw new Error(`getByRole(${JSON.stringify(role)}) needs { name } on native — it matches the accessible label`);
+            }
+            return locator(driver, by.label(name), wait);
+        },
+    };
+}

package/dist/runner-config.d.ts

@@ -0,0 +1 @@
+export declare const config: Record<string, unknown>;

package/dist/runner-config.js

@@ -0,0 +1,32 @@
+import { pathToFileURL } from "node:url";
+import { buildWdioConfig } from "./config.js";
+/**
+ * The bridge the `nativeproof` CLI hands to WebdriverIO: it loads the user's
+ * `nativeproof.config.ts` (path in `NATIVEPROOF_CONFIG`) and exports the synthesised `config`.
+ * The CLI runs `wdio run <this file>` with `--import tsx`, so the TS config loads.
+ * Not part of the public API — it is the runner entry point.
+ */
+const configPath = process.env.NATIVEPROOF_CONFIG;
+if (!configPath) {
+    throw new Error("NATIVEPROOF_CONFIG is not set — run NativeProof through the `nativeproof` CLI");
+}
+const loaded = (await import(pathToFileURL(configPath).href));
+const userConfig = loaded.default;
+if (!userConfig) {
+    throw new Error(`${configPath} must \`export default defineConfig(...)\``);
+}
+const env = {};
+const { PLATFORM, NATIVEPROOF_PROJECT, SPEC, APPIUM_HOST, APPIUM_PORT, APPIUM_PATH } = process.env;
+if (PLATFORM)
+    env.platform = PLATFORM;
+if (NATIVEPROOF_PROJECT)
+    env.project = NATIVEPROOF_PROJECT;
+if (SPEC)
+    env.spec = SPEC;
+if (APPIUM_HOST)
+    env.appiumHost = APPIUM_HOST;
+if (APPIUM_PORT)
+    env.appiumPort = Number(APPIUM_PORT);
+if (APPIUM_PATH)
+    env.appiumPath = APPIUM_PATH;
+export const config = buildWdioConfig(userConfig, env);

package/dist/runner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * BDD-runner seam.
+ *
+ * The fixtures and the `test` facade register suites through whatever BDD runner
+ * hosts them: Mocha by default (its `describe` / `before` / `after` / `it` globals, as
+ * WebdriverIO uses), or any other runner wired explicitly with {@link useRunner}
+ * (for example node:test). This keeps the framework from hard-coding a single runner,
+ * the way Playwright owns its own.
+ */
+export interface BddHooks {
+    describe(title: string, fn: () => void): void;
+    before(fn: () => void | Promise<void>): void;
+    after(fn: () => void | Promise<void>): void;
+    it(title: string, fn: () => void | Promise<void>): void;
+}
+/** Wire an explicit BDD runner (e.g. node:test's hooks). Overrides global detection. */
+export declare function useRunner(hooks: BddHooks): void;
+/** The active BDD runner: the one set via {@link useRunner}, else the ambient globals. */
+export declare function runner(): BddHooks;

package/dist/runner.js

@@ -0,0 +1,29 @@
+let configured = null;
+/** Wire an explicit BDD runner (e.g. node:test's hooks). Overrides global detection. */
+export function useRunner(hooks) {
+    configured = hooks;
+}
+function fromGlobals() {
+    const globals = globalThis;
+    const { describe, before, after, it } = globals;
+    if (typeof describe === "function" &&
+        typeof before === "function" &&
+        typeof after === "function" &&
+        typeof it === "function") {
+        return {
+            describe: describe,
+            before: before,
+            after: after,
+            it: it,
+        };
+    }
+    return null;
+}
+/** The active BDD runner: the one set via {@link useRunner}, else the ambient globals. */
+export function runner() {
+    const hooks = configured ?? fromGlobals();
+    if (!hooks) {
+        throw new Error("No BDD runner found. Run under Mocha (WebdriverIO's default) or call useRunner({ describe, before, after, it }) — e.g. with node:test's hooks.");
+    }
+    return hooks;
+}

package/dist/screen.d.ts

@@ -0,0 +1,35 @@
+import { captureScreenshot, captureState, captureText } from "./evidence.js";
+import { type Bounds } from "./source.js";
+/**
+ * Base class for all Screen Objects.
+ *
+ * Encapsulates the "try a semantic selector, fall back to a source-bounds
+ * coordinate tap" pattern that native Compose/SwiftUI surfaces require, plus
+ * evidence shortcuts. App screen objects extend this; nothing here is app-specific,
+ * so it travels with the framework as a standalone, reusable core.
+ */
+export declare abstract class Screen {
+    /** Current Appium page source (best-effort; empty string on driver error). */
+    source(): Promise<string>;
+    isPresent(pattern: RegExp): Promise<boolean>;
+    /**
+     * Assert a pattern is visible via the Appium source, falling back to a raw
+     * `adb uiautomator dump` for nodes hidden from the Appium accessibility tree.
+     */
+    assertVisible(pattern: RegExp, message: string): Promise<{
+        source: string;
+        sourceKind: "appium" | "adb-uiautomator";
+    }>;
+    /**
+     * Tap an Android control by `content-desc`, falling back to a coordinate tap
+     * computed from the page-source bounds when the accessibility node is present
+     * but not directly clickable.
+     */
+    tapContentDesc(contentDesc: string, timeout?: number): Promise<void>;
+    protected tapBounds(bounds: Bounds): Promise<void>;
+    /** Dismiss an open bottom sheet via the system back affordance. */
+    dismissBottomSheet(): Promise<void>;
+    protected captureScreenshot: typeof captureScreenshot;
+    protected captureText: typeof captureText;
+    protected captureState: typeof captureState;
+}

package/dist/screen.js

@@ -0,0 +1,67 @@
+import { browser } from "@wdio/globals";
+import { adbDump } from "./adb.js";
+import { captureScreenshot, captureState, captureText } from "./evidence.js";
+import { tapAt } from "./gestures.js";
+import { boundsForContentDesc } from "./source.js";
+import { waitAndClick } from "./wait.js";
+/**
+ * Base class for all Screen Objects.
+ *
+ * Encapsulates the "try a semantic selector, fall back to a source-bounds
+ * coordinate tap" pattern that native Compose/SwiftUI surfaces require, plus
+ * evidence shortcuts. App screen objects extend this; nothing here is app-specific,
+ * so it travels with the framework as a standalone, reusable core.
+ */
+export class Screen {
+    /** Current Appium page source (best-effort; empty string on driver error). */
+    async source() {
+        return browser.getPageSource().catch(() => "");
+    }
+    async isPresent(pattern) {
+        return pattern.test(await this.source());
+    }
+    /**
+     * Assert a pattern is visible via the Appium source, falling back to a raw
+     * `adb uiautomator dump` for nodes hidden from the Appium accessibility tree.
+     */
+    async assertVisible(pattern, message) {
+        const source = await this.source();
+        if (pattern.test(source))
+            return { source, sourceKind: "appium" };
+        const dump = adbDump();
+        if (pattern.test(dump))
+            return { source: dump, sourceKind: "adb-uiautomator" };
+        throw new Error(`${message}; source was: ${source}\n--- adb ---\n${dump}`);
+    }
+    /**
+     * Tap an Android control by `content-desc`, falling back to a coordinate tap
+     * computed from the page-source bounds when the accessibility node is present
+     * but not directly clickable.
+     */
+    async tapContentDesc(contentDesc, timeout = 10000) {
+        try {
+            await waitAndClick(`android=new UiSelector().description("${contentDesc}")`, timeout);
+        }
+        catch {
+            const bounds = boundsForContentDesc(await this.source(), contentDesc);
+            if (!bounds) {
+                throw new Error(`Expected to find a control with content-desc "${contentDesc}"`);
+            }
+            await tapAt(bounds.centerX, bounds.centerY);
+        }
+    }
+    async tapBounds(bounds) {
+        await tapAt(bounds.centerX, bounds.centerY);
+    }
+    /** Dismiss an open bottom sheet via the system back affordance. */
+    async dismissBottomSheet() {
+        await browser.back().catch(async () => {
+            await tapAt(540, 850);
+        });
+        await browser.pause(1000);
+    }
+    // Evidence shortcuts ------------------------------------------------------
+    captureScreenshot = captureScreenshot;
+    captureText = captureText;
+    captureState = captureState;
+}

package/dist/source.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Page-source geometry helpers.
+ *
+ * Android UiAutomator and iOS XCUITest both expose an XML page source with
+ * `bounds="[x1,y1][x2,y2]"` attributes. When semantic selectors are unavailable
+ * or unreliable, the screens parse those bounds to compute a tap point. Keeping
+ * this parsing in one framework module is what makes the brittle-selector problem
+ * a single, replaceable seam rather than scattered regexes.
+ */
+export type Bounds = {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    width: number;
+    height: number;
+    centerX: number;
+    centerY: number;
+};
+export declare function parseBounds(bounds: string | undefined | null): Bounds | null;
+/** Bounds of the first element whose `bounds` follows the given attribute match. */
+export declare function boundsForAttribute(source: string, attribute: string, value: string): Bounds | null;
+/** Bounds of an element addressed by Android `content-desc`. */
+export declare function boundsForContentDesc(source: string, contentDesc: string): Bounds | null;
+/** Bounds of an element addressed by visible `text`. */
+export declare function boundsForText(source: string, text: string): Bounds | null;
+/**
+ * The smallest clickable ancestor that fully contains the given text node — used
+ * to turn a non-clickable Compose `TextView` into a reliable tap target (e.g. the
+ * "Members (3)" list rows).
+ */
+export declare function clickableAncestorBoundsForText(source: string, text: string): Bounds | null;

package/dist/source.js

@@ -0,0 +1,60 @@
+/**
+ * Page-source geometry helpers.
+ *
+ * Android UiAutomator and iOS XCUITest both expose an XML page source with
+ * `bounds="[x1,y1][x2,y2]"` attributes. When semantic selectors are unavailable
+ * or unreliable, the screens parse those bounds to compute a tap point. Keeping
+ * this parsing in one framework module is what makes the brittle-selector problem
+ * a single, replaceable seam rather than scattered regexes.
+ */
+export function parseBounds(bounds) {
+    const match = /\[(\d+),(\d+)\]\[(\d+),(\d+)\]/.exec(bounds ?? "");
+    if (!match)
+        return null;
+    const x1 = Number(match[1]);
+    const y1 = Number(match[2]);
+    const x2 = Number(match[3]);
+    const y2 = Number(match[4]);
+    return {
+        x1,
+        y1,
+        x2,
+        y2,
+        width: x2 - x1,
+        height: y2 - y1,
+        centerX: Math.round((x1 + x2) / 2),
+        centerY: Math.round((y1 + y2) / 2),
+    };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Bounds of the first element whose `bounds` follows the given attribute match. */
+export function boundsForAttribute(source, attribute, value) {
+    const match = new RegExp(`${attribute}="${escapeRegExp(value)}"[^>]*bounds="([^"]+)"`).exec(source);
+    return match ? parseBounds(match[1]) : null;
+}
+/** Bounds of an element addressed by Android `content-desc`. */
+export function boundsForContentDesc(source, contentDesc) {
+    return boundsForAttribute(source, "content-desc", contentDesc);
+}
+/** Bounds of an element addressed by visible `text`. */
+export function boundsForText(source, text) {
+    return boundsForAttribute(source, "text", text);
+}
+/**
+ * The smallest clickable ancestor that fully contains the given text node — used
+ * to turn a non-clickable Compose `TextView` into a reliable tap target (e.g. the
+ * "Members (3)" list rows).
+ */
+export function clickableAncestorBoundsForText(source, text) {
+    const textBounds = boundsForText(source, text);
+    if (!textBounds)
+        return null;
+    const clickable = [...source.matchAll(/clickable="true"[^>]*bounds="([^"]+)"/g)]
+        .map((m) => parseBounds(m[1]))
+        .filter((b) => b !== null)
+        .filter((b) => b.x1 <= textBounds.x1 && b.x2 >= textBounds.x2 && b.y1 <= textBounds.y1 && b.y2 >= textBounds.y2)
+        .sort((a, b) => a.width * a.height - b.width * b.height);
+    return clickable[0] ?? textBounds;
+}

package/dist/test.d.ts

@@ -0,0 +1,13 @@
+import { type BehaviourRegistrar, type ScenarioFixture } from "./fixtures.js";
+/**
+ * The Playwright-flavoured test surface.
+ *
+ * `test.describe(title, scenario, (test) => { test("…", async ({ … }) => …) })` binds a
+ * scenario's fixture context to a block; each `test(name, body)` is one behaviour with
+ * that context injected — fully typed, with no setup/teardown in the spec. The registrar
+ * is passed into the block (rather than being a module global) so the fixture context
+ * types flow into every body; otherwise it reads like Playwright.
+ */
+export declare const test: {
+    describe<Ctx>(title: string, scenario: ScenarioFixture<Ctx>, define: (test: BehaviourRegistrar<Ctx>) => void): void;
+};

package/dist/test.js

@@ -0,0 +1,15 @@
+import { describeScenario } from "./fixtures.js";
+/**
+ * The Playwright-flavoured test surface.
+ *
+ * `test.describe(title, scenario, (test) => { test("…", async ({ … }) => …) })` binds a
+ * scenario's fixture context to a block; each `test(name, body)` is one behaviour with
+ * that context injected — fully typed, with no setup/teardown in the spec. The registrar
+ * is passed into the block (rather than being a module global) so the fixture context
+ * types flow into every body; otherwise it reads like Playwright.
+ */
+export const test = {
+    describe(title, scenario, define) {
+        describeScenario(title, scenario, define);
+    },
+};

package/dist/text.d.ts

@@ -0,0 +1,18 @@
+import { $ } from "@wdio/globals";
+export declare function exactText(text: string): string;
+export declare function textContaining(text: string): string;
+export declare function accessibleName(text: string): string;
+/** A trimmed, non-empty environment credential, or undefined when not configured. */
+export declare function configuredCredential(name: string): string | undefined;
+export declare function firstTextInput(): string;
+export declare function firstPasswordInput(): string;
+export declare function tapVisibleText(text: string, timeout?: number): Promise<void>;
+export declare function tapTextIfVisible(text: string, timeout?: number): Promise<boolean>;
+export declare function expectVisibleText(text: string, timeout?: number): Promise<void>;
+export declare function waitForAnyVisibleText(labels: string[], timeout?: number): Promise<{
+    label: string;
+    element: ReturnType<typeof $>;
+}>;
+export declare function waitForPageSourceToMention(phrases: string[], timeout?: number): Promise<void>;
+export declare function expectPageSourceToMention(phrases: string[]): Promise<void>;
+export declare function typeInto(selector: string, value: string): Promise<void>;