nativeproof 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,69 @@ All notable changes to NativeProof are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/) and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## 0.5.0
+
+Two additive, backward-compatible seams so an app can drive more of its lifecycle and
+traffic assertions through the framework instead of around it.
+
+**Added**
+
+- **`expect(...)` accepts any frame source, not just a full `MockBackend`** — a new
+  `FrameLog` interface (`{ frames() }`, which `MockBackend` extends) is all the traffic
+  matchers need. An app whose mock predates `MockBackend` can expose a frames-only adapter
+  over its existing request/socket log and get auto-waiting `expect(traffic).toHaveSent({
+  path, type, ...payload })` / `.toHaveReceived(...)` — no `route`/`stop` to implement.
+- **`defineApp({ teardown })`** — an optional app-level teardown hook, run on session
+  teardown BEFORE the mock stops and before the runner deletes the device session (e.g.
+  force-stop the app so its background sockets are gone before `deleteSession`). The mock
+  is still stopped even if the hook throws.
+
+## 0.4.0
+
+Dead-code removal. The dropped exports were undocumented and unused by the framework, but
+since they were technically part of the published surface this is a minor bump.
+
+**Removed**
+
+- **`src/text.ts`** — a legacy WebdriverIO-`$`-based selector/text layer (`exactText`,
+  `tapVisibleText`, `typeInto`, `waitForAnyVisibleText`, …) superseded by the `Driver` / `Locator` /
+  `page` stack. Use `page(driver).getByText(...)` / `Locator.fill(...)` instead.
+- **`src/screen.ts`** — the unused `Screen` base class (nothing extended it).
+- **`src/wait.ts`** — `waitAndClick` / `waitForAnyDisplayed`, only ever used by `Screen`.
+- **`readLog`** (from `log.ts`) and **`waitForFrame`** (from `mock.ts`) — unused exports. The
+  documented mock-traffic API (`expect(mock).toHaveSent/toHaveReceived`) is unaffected.
+
+## 0.3.1
+
+Correctness and robustness fixes; no API changes.
+
+**Fixed**
+
+- **`expect(mock)` now matches object/array payload fields by deep equality** — `matchesFrame`
+  used reference equality, so `toHaveSent({ data: { id: 1 } })` / `{ tags: ["a"] }` could never
+  match and surfaced only as a misleading timeout. Now uses `isDeepStrictEqual`.
+- **`textContent()` prefers the first non-empty label attribute** — an iOS node with
+  `value="" label="Submit"` (or an Android Compose node with `text="" content-desc="…"`) read as
+  `""`; it now returns the populated value, in the same precedence `attributeFor` uses.
+- **Bounds parsing no longer assumes attribute order** — `boundsForAttribute` /
+  `smallestClickableAncestorBounds` match the element tag first, then extract `bounds`, so a source
+  that emits `bounds` before the selector attribute still resolves.
+- **`parseBounds` accepts negative coordinates** — off-screen / RTL-shifted nodes (`[-5,0]…`) now
+  parse instead of becoming untappable.
+- **`--appium-port` is validated** — a non-numeric / out-of-range value throws a clear error instead
+  of producing an opaque `http://host:NaN/…` connection failure.
+- **`toContain` throws a usage error** on a non-string/array actual instead of silently failing.
+- **Page-source capture failures are logged** — `wdioDriver().source()` and `captureState` warn on a
+  `getPageSource` error before degrading to empty, so a dead session isn't mistaken for an empty screen.
+
+**Internal**
+
+- Deduplicated `escapeRegExp` (now shared from `source.ts`).
+
+## 0.3.0
+
+Maintenance release — version bump only; no functional changes since 0.2.0.
+
 ## 0.2.0
 
 Locator interaction, generic assertions, and Compose/SwiftUI robustness — plus the docs for each.

package/README.md

@@ -641,9 +641,9 @@ jobs:
   android-e2e:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with: { node-version: 24 }
       - run: npm ci
       - run: npx appium driver install uiautomator2
       - uses: reactivecircus/android-emulator-runner@v2
@@ -659,9 +659,9 @@ jobs:
   ios-e2e:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with: { node-version: 24 }
       - run: npm ci
       - run: npx appium driver install xcuitest
       - run: xcrun simctl boot "iPhone 15" || true

package/dist/app.d.ts

@@ -37,6 +37,13 @@ export interface AppDefinition<S extends ScreenFactories> {
     join?: (context: FlowContext) => Promise<void>;
     /** Screen-object factories, bound to the device context. */
     screens: S;
+    /**
+     * Release app-level resources acquired across the session, run on teardown BEFORE the
+     * mock stops and before the runner deletes the device session — e.g. force-stop the app
+     * so its background sockets are gone before `deleteSession`. The mock is still stopped
+     * even if this throws.
+     */
+    teardown?: (context: SessionContext<S>) => Promise<void> | void;
 }
 /** The fixture context a session injects: the device handles plus each app screen. */
 export type SessionContext<S extends ScreenFactories> = DeviceContext & {

package/dist/app.js

@@ -25,8 +25,14 @@ export function defineApp(definition) {
                     }
                 },
                 async teardown(context) {
-                    if (context)
+                    if (!context)
+                        return;
+                    try {
+                        await definition.teardown?.(context);
+                    }
+                    finally {
                         await context.mock.stop();
+                    }
                 },
             };
         },

package/dist/cli.js

@@ -60,7 +60,12 @@ export function parseArgs(argv) {
         }
         else if (arg === "--appium-port") {
             i += 1;
-            args.appiumPort = Number(valueFor(argv, i, "--appium-port"));
+            const raw = valueFor(argv, i, "--appium-port");
+            const port = Number(raw);
+            if (!Number.isInteger(port) || port < 0 || port > 65535) {
+                throw new Error(`--appium-port must be an integer between 0 and 65535, got "${raw}"`);
+            }
+            args.appiumPort = port;
         }
         else if (arg === "--appium-path") {
             i += 1;

package/dist/driver.js

@@ -6,7 +6,12 @@ export function wdioDriver() {
         get platform() {
             return browser.isAndroid ? "android" : "ios";
         },
-        source: () => browser.getPageSource().catch(() => ""),
+        source: () => browser.getPageSource().catch((err) => {
+            // Don't let a dead/unreachable session masquerade as "element not visible";
+            // surface it so a timeout's cause is visible, then degrade to empty source.
+            console.warn(`[nativeproof] getPageSource failed: ${err}`);
+            return "";
+        }),
         pause: (ms) => browser.pause(ms),
         tapAt: (x, y) => tapAt(x, y),
         typeText: (text) => browser.keys(text),

package/dist/evidence.js

@@ -33,7 +33,11 @@ export async function captureScreenshot(filename) {
 }
 /** Capture a screenshot + redacted source pair under one prefix; returns the source. */
 export async function captureState(prefix) {
-    const source = await browser.getPageSource().catch(() => "");
+    const source = await browser.getPageSource().catch((err) => {
+        // A failed capture must not look like a clean empty screen in the evidence trail.
+        console.warn(`[nativeproof] getPageSource failed during captureState("${prefix}"): ${err}`);
+        return "";
+    });
     await captureScreenshot(`${prefix}.png`);
     await captureText(`${prefix}.xml`, source);
     return source;

package/dist/expect.d.ts

@@ -1,5 +1,5 @@
 import { Locator, type WaitOptions } from "./locator.js";
-import { type FrameMatch, type MockBackend } from "./mock.js";
+import { type FrameLog, type FrameMatch, type MockBackend } from "./mock.js";
 /**
  * Playwright-style assertions with built-in auto-waiting — the "easy visibility"
  * layer. `expect(locator)` asserts UI state; `expect(mock)` asserts backend traffic.
@@ -42,4 +42,5 @@ export interface ValueAssertions<T> {
 }
 export declare function expect(target: Locator): LocatorAssertions;
 export declare function expect(target: MockBackend): MockAssertions;
+export declare function expect(target: FrameLog): MockAssertions;
 export declare function expect<T>(target: T): ValueAssertions<T>;

package/dist/expect.js

@@ -86,11 +86,12 @@ class ValueExpectation {
         this.assert(isDeepStrictEqual(this.actual, expected), "toEqual", describeValue(expected));
     }
     toContain(expected) {
+        if (typeof this.actual !== "string" && !Array.isArray(this.actual)) {
+            throw new TypeError(`expect(...).toContain(...) needs a string or array actual, got ${describeValue(this.actual)}`);
+        }
         const ok = typeof this.actual === "string"
             ? this.actual.includes(String(expected))
-            : Array.isArray(this.actual)
-                ? this.actual.includes(expected)
-                : false;
+            : this.actual.includes(expected);
         this.assert(ok, "toContain", describeValue(expected));
     }
     toBeTruthy() {
@@ -113,18 +114,18 @@ class ValueExpectation {
         throw new Error(`expect(${describeValue(this.actual)})${not}.${matcher}(${expectedDesc}) — assertion not met`);
     }
 }
-/** Structural guard: a {@link MockBackend} is anything with `frames`/`route`/`stop`. */
-function isMockBackend(target) {
-    return (typeof target === "object" &&
-        target !== null &&
-        typeof target.frames === "function" &&
-        typeof target.route === "function" &&
-        typeof target.stop === "function");
+/**
+ * Structural guard: anything with a `frames()` method is a {@link FrameLog} we can
+ * assert traffic on — a full {@link MockBackend} or a frames-only adapter alike. The
+ * traffic matchers only read `frames()`, so `route`/`stop` are not required here.
+ */
+function isFrameLog(target) {
+    return typeof target === "object" && target !== null && typeof target.frames === "function";
 }
 export function expect(target) {
     if (target instanceof Locator)
         return new LocatorExpectation(target);
-    if (isMockBackend(target))
+    if (isFrameLog(target))
         return new MockExpectation(target);
     return new ValueExpectation(target);
 }

package/dist/index.d.ts

@@ -23,8 +23,5 @@ export * from "./mock.js";
 export * from "./mock-server.js";
 export * from "./page.js";
 export * from "./runner.js";
-export * from "./screen.js";
 export * from "./source.js";
 export * from "./test.js";
-export * from "./text.js";
-export * from "./wait.js";

package/dist/index.js

@@ -23,8 +23,5 @@ export * from "./mock.js";
 export * from "./mock-server.js";
 export * from "./page.js";
 export * from "./runner.js";
-export * from "./screen.js";
 export * from "./source.js";
 export * from "./test.js";
-export * from "./text.js";
-export * from "./wait.js";

package/dist/locator.js

@@ -1,4 +1,4 @@
-import { boundsForAttribute, decodeXmlEntities, encodeXmlEntities, smallestClickableAncestorBounds, } from "./source.js";
+import { boundsForAttribute, decodeXmlEntities, encodeXmlEntities, escapeRegExp, smallestClickableAncestorBounds, } from "./source.js";
 /**
  * Build selectors Playwright-style. The cross-platform attribute each maps to is resolved
  * per platform (see {@link attributeFor}), so you never have to know whether it's a
@@ -17,9 +17,6 @@ export const by = {
 export function describeSelector(selector) {
     return `by.${selector.by}(${JSON.stringify(selector.value)})`;
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 /**
  * The page-source attribute a selector resolves to on each platform. `text` is an
  * alternation, because a visible label surfaces as `text` OR `content-desc` on Android
@@ -87,9 +84,16 @@ export class Locator {
         const node = new RegExp(`<[^>]*${this.attribute()}="${selectorPattern}"[^>]*>`).exec(source)?.[0];
         if (!node)
             return null;
-        const textAttr = this.driver.platform === "ios" ? "value|label" : "text";
-        const raw = new RegExp(`(?:${textAttr})="([^"]*)"`).exec(node)?.[1];
-        return raw == null ? null : decodeXmlEntities(raw);
+        // A visible label can live in either of two attributes per platform, in the same
+        // precedence `attributeFor` uses (iOS label→value, Android text→content-desc). Prefer
+        // the first NON-empty one, so a node like `value="" label="Submit"` reads "Submit",
+        // falling back to the first present (possibly empty) attribute.
+        const attrs = this.driver.platform === "ios" ? ["label", "value"] : ["text", "content-desc"];
+        const present = attrs
+            .map((attr) => new RegExp(`${attr}="([^"]*)"`).exec(node)?.[1])
+            .filter((v) => v !== undefined);
+        const raw = present.find((v) => v !== "") ?? present[0];
+        return raw === undefined ? null : decodeXmlEntities(raw);
     }
     /** True if the selector is present AND `text` appears in the source. */
     async shows(text) {

package/dist/log.d.ts

@@ -6,7 +6,6 @@
  * Playwright-`page.route()` equivalent that native Appium otherwise lacks.
  * App-agnostic; app-specific frame semantics live in the consumer's assertions.
  */
-export declare function readLog(logPath: string): Promise<string>;
 export declare function countMatches(text: string, pattern: RegExp): number;
 /**
  * Tokens that must never appear in captured evidence. App-agnostic by default

package/dist/log.js

@@ -1,4 +1,3 @@
-import fs from "node:fs/promises";
 /**
  * Network-evidence log helpers.
  *
@@ -7,9 +6,6 @@ import fs from "node:fs/promises";
  * Playwright-`page.route()` equivalent that native Appium otherwise lacks.
  * App-agnostic; app-specific frame semantics live in the consumer's assertions.
  */
-export async function readLog(logPath) {
-    return fs.readFile(logPath, "utf8").catch(() => "");
-}
 export function countMatches(text, pattern) {
     const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
     return (text.match(new RegExp(pattern.source, flags)) ?? []).length;

package/dist/mock.d.ts

@@ -1,4 +1,3 @@
-import { type WaitOptions } from "./locator.js";
 /**
  * Backend mocking that feels like Playwright's `page.route()`.
  *
@@ -34,9 +33,17 @@ export interface MockRoute {
     /** Drop the connect/request entirely. */
     abort(): void;
 }
-export interface MockBackend {
+/**
+ * A read-only source of observed frames — the minimum `expect(...)` needs to assert
+ * traffic. A full {@link MockBackend} is one, but so is any adapter that produces the
+ * frames an app exchanged (e.g. a view over an existing request/socket log), so a mock
+ * that predates {@link MockBackend} can be asserted on without implementing `route`/`stop`.
+ */
+export interface FrameLog {
     /** Every frame observed so far, in order, both directions. */
     frames(): Promise<readonly MockFrame[]>;
+}
+export interface MockBackend extends FrameLog {
     /** Intercept a path and control its reply. */
     route(path: string): MockRoute;
     /** Release the backend (stop the server, close sockets). */
@@ -49,6 +56,4 @@ export interface MockBackend {
 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>;
+export declare function frameExists(source: FrameLog, direction: FrameDirection, match: FrameMatch): Promise<boolean>;

package/dist/mock.js

@@ -1,4 +1,4 @@
-import { waitUntil } from "./locator.js";
+import { isDeepStrictEqual } from "node:util";
 /**
  * True if `frame` satisfies every field of `match`: `path` / `type` at the top level,
  * every other key against the frame's payload.
@@ -11,7 +11,7 @@ export function matchesFrame(frame, match) {
     for (const [key, value] of Object.entries(match)) {
         if (key === "path" || key === "type")
             continue;
-        if (frame.payload?.[key] !== value)
+        if (!isDeepStrictEqual(frame.payload?.[key], value))
             return false;
     }
     return true;
@@ -20,11 +20,7 @@ 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();
+export async function frameExists(source, direction, match) {
+    const frames = await source.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/source.d.ts

@@ -18,6 +18,7 @@ export type Bounds = {
     centerY: number;
 };
 export declare function parseBounds(bounds: string | undefined | null): Bounds | null;
+export declare function escapeRegExp(value: string): string;
 /**
  * Decode the XML entities UiAutomator/XCUITest escape attribute values with
  * (`&amp;` → `&`, `&lt;` → `<`, …). `&amp;` is decoded LAST so `&amp;lt;` round-trips
@@ -30,7 +31,11 @@ export declare function decodeXmlEntities(value: string): string;
  * (`text="Terms &amp; Conditions"`). `&` is encoded first to avoid double-encoding.
  */
 export declare function encodeXmlEntities(value: string): string;
-/** Bounds of the first element whose `bounds` follows the given attribute match. */
+/**
+ * Bounds of the first element carrying the given attribute match. The element tag is
+ * matched first, then `bounds` is extracted from within it regardless of attribute order —
+ * so a source that emits `bounds` before the selector attribute still resolves.
+ */
 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;

package/dist/source.js

@@ -8,7 +8,7 @@
  * a single, replaceable seam rather than scattered regexes.
  */
 export function parseBounds(bounds) {
-    const match = /\[(\d+),(\d+)\]\[(\d+),(\d+)\]/.exec(bounds ?? "");
+    const match = /\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/.exec(bounds ?? "");
     if (!match)
         return null;
     const x1 = Number(match[1]);
@@ -26,7 +26,7 @@ export function parseBounds(bounds) {
         centerY: Math.round((y1 + y2) / 2),
     };
 }
-function escapeRegExp(value) {
+export function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 /**
@@ -50,11 +50,17 @@ export function decodeXmlEntities(value) {
 export function encodeXmlEntities(value) {
     return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-/** Bounds of the first element whose `bounds` follows the given attribute match. */
+/**
+ * Bounds of the first element carrying the given attribute match. The element tag is
+ * matched first, then `bounds` is extracted from within it regardless of attribute order —
+ * so a source that emits `bounds` before the selector attribute still resolves.
+ */
 export function boundsForAttribute(source, attribute, value) {
     const escaped = escapeRegExp(encodeXmlEntities(value));
-    const match = new RegExp(`${attribute}="${escaped}"[^>]*bounds="([^"]+)"`).exec(source);
-    return match ? parseBounds(match[1]) : null;
+    const node = new RegExp(`<[^>]*${attribute}="${escaped}"[^>]*>`).exec(source)?.[0];
+    if (!node)
+        return null;
+    return parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]);
 }
 /** Bounds of an element addressed by Android `content-desc`. */
 export function boundsForContentDesc(source, contentDesc) {
@@ -70,8 +76,8 @@ export function boundsForText(source, text) {
  * into a reliable tap target (e.g. the "Members (3)" list rows).
  */
 export function smallestClickableAncestorBounds(source, nodeBounds) {
-    const clickable = [...source.matchAll(/clickable="true"[^>]*bounds="([^"]+)"/g)]
-        .map((m) => parseBounds(m[1]))
+    const clickable = [...source.matchAll(/<[^>]*clickable="true"[^>]*>/g)]
+        .map((m) => parseBounds(/bounds="([^"]+)"/.exec(m[0])?.[1]))
         .filter((b) => b !== null)
         .filter((b) => b.x1 <= nodeBounds.x1 && b.x2 >= nodeBounds.x2 && b.y1 <= nodeBounds.y1 && b.y2 >= nodeBounds.y2)
         .sort((a, b) => a.width * a.height - b.width * b.height);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nativeproof",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",

package/dist/screen.d.ts

@@ -1,35 +0,0 @@
-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

@@ -1,67 +0,0 @@
-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/text.d.ts

@@ -1,18 +0,0 @@
-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>;

package/dist/text.js

@@ -1,129 +0,0 @@
-import { $, browser, driver, expect } from "@wdio/globals";
-/**
- * Cross-platform text/selector layer.
- *
- * Resolves the same human-readable control name to the right native selector on
- * each platform (Android `UiSelector`, iOS predicate strings), preferring
- * accessibility names with visible-text fallbacks. This is the single place a
- * brittle selector becomes a stable automation id once the app teams add them.
- * App-agnostic framework core.
- */
-const DEFAULT_WAIT_MS = 15_000;
-export function exactText(text) {
-    if (driver.isAndroid) {
-        return `android=new UiSelector().text(${JSON.stringify(text)})`;
-    }
-    const literal = iosLiteral(text);
-    return `-ios predicate string:name == ${literal} OR label == ${literal} OR value == ${literal}`;
-}
-export function textContaining(text) {
-    if (driver.isAndroid) {
-        return `android=new UiSelector().textContains(${JSON.stringify(text)})`;
-    }
-    const literal = iosLiteral(text);
-    return `-ios predicate string:name CONTAINS ${literal} OR label CONTAINS ${literal} OR value CONTAINS ${literal}`;
-}
-export function accessibleName(text) {
-    return `~${text}`;
-}
-/** A trimmed, non-empty environment credential, or undefined when not configured. */
-export function configuredCredential(name) {
-    const value = process.env[name]?.trim();
-    return value && value.length > 0 ? value : undefined;
-}
-export function firstTextInput() {
-    if (driver.isAndroid) {
-        return 'android=new UiSelector().className("android.widget.EditText").instance(0)';
-    }
-    return "-ios class chain:**/XCUIElementTypeTextField[1]";
-}
-export function firstPasswordInput() {
-    if (driver.isAndroid) {
-        return 'android=new UiSelector().className("android.widget.EditText").instance(1)';
-    }
-    return "-ios class chain:**/XCUIElementTypeSecureTextField[1]";
-}
-export async function tapVisibleText(text, timeout = DEFAULT_WAIT_MS) {
-    const element = await visibleElementMatchingText(text, timeout);
-    await element.click();
-}
-export async function tapTextIfVisible(text, timeout = 1_000) {
-    try {
-        const element = await visibleElementMatchingText(text, timeout);
-        await element.click();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export async function expectVisibleText(text, timeout = DEFAULT_WAIT_MS) {
-    const element = await visibleElementMatchingText(text, timeout);
-    await expect(element).toBeDisplayed();
-}
-export async function waitForAnyVisibleText(labels, timeout = DEFAULT_WAIT_MS) {
-    const deadline = Date.now() + timeout;
-    let lastError;
-    while (Date.now() < deadline) {
-        for (const label of labels) {
-            try {
-                const element = await visibleElementMatchingText(label, 500);
-                return { label, element };
-            }
-            catch (error) {
-                lastError = error;
-            }
-        }
-        await browser.pause(500);
-    }
-    throw new Error(`None of these labels became visible: ${labels.join(", ")}${lastError instanceof Error ? `; last error: ${lastError.message}` : ""}`);
-}
-export async function waitForPageSourceToMention(phrases, timeout = DEFAULT_WAIT_MS) {
-    await browser.waitUntil(async () => {
-        const source = await driver.getPageSource();
-        return phrases.some((phrase) => source.toLowerCase().includes(phrase.toLowerCase()));
-    }, { timeout, timeoutMsg: `Page source did not mention any of: ${phrases.join(", ")}` });
-}
-export async function expectPageSourceToMention(phrases) {
-    const source = await driver.getPageSource();
-    const matched = phrases.some((phrase) => source.toLowerCase().includes(phrase.toLowerCase()));
-    await expect(matched).toBe(true);
-}
-export async function typeInto(selector, value) {
-    const input = await $(selector);
-    await input.waitForDisplayed({ timeout: DEFAULT_WAIT_MS });
-    await input.click();
-    await input.setValue(value);
-}
-async function visibleElementMatchingText(text, timeout) {
-    const deadline = Date.now() + timeout;
-    let lastError;
-    while (Date.now() < deadline) {
-        for (const selector of [accessibleName(text), exactText(text)]) {
-            try {
-                const element = await $(selector);
-                if ((await element.isDisplayed()) && (await elementCenterIsInsideViewport(element))) {
-                    return element;
-                }
-            }
-            catch (error) {
-                lastError = error;
-            }
-        }
-        await browser.pause(300);
-    }
-    throw new Error(`No visible element for "${text}"${lastError instanceof Error ? `; last error: ${lastError.message}` : ""}`);
-}
-async function elementCenterIsInsideViewport(element) {
-    const [location, size, viewport] = await Promise.all([
-        element.getLocation(),
-        element.getSize(),
-        driver.getWindowRect(),
-    ]);
-    const centerX = location.x + size.width / 2;
-    const centerY = location.y + size.height / 2;
-    return centerX >= 0 && centerX <= viewport.width && centerY >= 0 && centerY <= viewport.height;
-}
-function iosLiteral(text) {
-    return `"${text.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
-}

package/dist/wait.d.ts

@@ -1,14 +0,0 @@
-import { $ } from "@wdio/globals";
-/**
- * Selector waiting helpers built on the WebdriverIO runner globals.
- *
- * `waitForAnyDisplayed` resolves the first of several candidate selectors to
- * appear — essential on screens that render one of multiple possible states
- * (e.g. an onboarding "Later" sheet vs. the role-selection home).
- */
-export type DisplayedMatch = {
-    selector: string;
-    element: ReturnType<typeof $>;
-};
-export declare function waitAndClick(selector: string, timeout?: number): Promise<void>;
-export declare function waitForAnyDisplayed(selectors: string[], timeout?: number): Promise<DisplayedMatch>;

package/dist/wait.js

@@ -1,26 +0,0 @@
-import { $, browser } from "@wdio/globals";
-export async function waitAndClick(selector, timeout = 10000) {
-    const element = await $(selector);
-    await element.waitForDisplayed({ timeout });
-    await element.click();
-}
-export async function waitForAnyDisplayed(selectors, timeout = 30000) {
-    let matched;
-    await browser.waitUntil(async () => {
-        for (const selector of selectors) {
-            const element = $(selector);
-            const displayed = await element.isDisplayed().catch(() => false);
-            if (displayed) {
-                matched = { selector, element };
-                return true;
-            }
-        }
-        return false;
-    }, {
-        timeout,
-        interval: 500,
-        timeoutMsg: `None of the selectors became displayed within ${timeout}ms: ${selectors.join(", ")}`,
-    });
-    // waitUntil only resolves once the predicate set `matched`.
-    return matched;
-}