nativeproof 0.3.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,93 @@ 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.6.0
+
+Playwright-parity additions to locators, assertions, fixtures, and evidence.
+
+**Added**
+
+- **Checkbox/switch state** — `Locator.isChecked()`, `Locator.check()` / `uncheck()` (tap to the
+  desired state, a no-op if already there), and auto-waiting `expect(locator).toBeChecked()` (+ `.not`),
+  reading `checked="true"` on the matched node.
+- **Multi-match locators** — `Locator.nth(i)` / `first()` / `last()` (negative `i` counts from the end),
+  `Locator.count()`, and auto-waiting `expect(locator).toHaveCount(n)`. An unindexed locator still
+  resolves to the first match. New `nodesForAttribute` source helper backs it.
+- **Scenario `beforeEach` / `afterEach`** — `test.beforeEach(fn)` / `test.afterEach(fn)` (and the
+  `describeScenario` registrar's `.beforeEach` / `.afterEach`) register per-behaviour hooks that
+  receive the provisioned fixture context — a repeatable reset between behaviours without leaving the
+  harness. `BddHooks` gained optional `beforeEach` / `afterEach` (present on Mocha and node:test).
+- **`onFailure` evidence hook** — `ScenarioFixture.onFailure` and `defineApp({ onFailure })` run when a
+  behaviour throws, before the failure propagates, so on-failure evidence (e.g. `captureState(...)`)
+  lives in one place instead of every behaviour. The hook receives the context + `{ title, error }`;
+  its own errors are swallowed (logged) so they never mask the real failure.
+- **`by.*` and every `page().getBy*` accept a `RegExp`** as well as a string —
+  `getByText(/Save( draft)?/)`, `getByLabel(/^Remove /)`, `getByRole("checkbox", { name: /terms/i })`.
+  A string matches the element's value exactly; a RegExp is tested against the element's **decoded**
+  value, so a human pattern matches the entity-escaped source and tolerant labels
+  (`/complete(d)? phrases/`) no longer need source-scraping. Matching, `bounds`, `textContent`,
+  `tap`/`fill`, and `expect(locator)` all honour it. New `nodeForAttribute` / `attributeMatches`
+  source helpers back it (`boundsForAttribute` now takes `string | RegExp`).
+
+## 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.

package/README.md

@@ -60,7 +60,8 @@ nativeproof --platform android
 - **Locators** — `by.text/testId/label/desc/id` and `page(driver).getByText/getByTestId/
   getByLabel/getById/getByRole`, each mapped to the right native attribute per platform (so you
   never guess `content-desc` vs `accessibilityIdentifier`), with built-in auto-waiting and
-  `tap()` / `fill()` for interaction.
+  `tap()` / `fill()` for interaction. Each takes a string (exact) or a **`RegExp`**
+  (`getByText(/Save( draft)?/)`), tested against the element's decoded value.
 - **Auto-waiting `expect`** — `expect(locator).toBeVisible()/toShow()/toHaveText()` and
   `.not`, each polling until the condition holds (default 10s); plus synchronous `expect(value)`
   matchers (`toBe`/`toEqual`/`toContain`/…) so non-UI checks need no second assertion library.
@@ -641,9 +642,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 +660,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

@@ -1,5 +1,5 @@
 import type { Driver } from "./driver.js";
-import type { ScenarioFixture } from "./fixtures.js";
+import type { FailureInfo, ScenarioFixture } from "./fixtures.js";
 import type { MockBackend } from "./mock.js";
 /**
  * `defineApp` — the single seam script.
@@ -37,6 +37,19 @@ 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;
+    /**
+     * Invoked when a behaviour throws, before the failure propagates — wire on-failure
+     * evidence here (e.g. `captureState(...)`) so capture lives in one place, not in every
+     * behaviour. Its own errors are swallowed so they never mask the real failure.
+     */
+    onFailure?: (context: SessionContext<S>, info: FailureInfo) => 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,9 +25,16 @@ export function defineApp(definition) {
                     }
                 },
                 async teardown(context) {
-                    if (context)
+                    if (!context)
+                        return;
+                    try {
+                        await definition.teardown?.(context);
+                    }
+                    finally {
                         await context.mock.stop();
+                    }
                 },
+                ...(definition.onFailure ? { onFailure: definition.onFailure } : {}),
             };
         },
     };

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.
@@ -14,6 +14,10 @@ export interface LocatorAssertions {
     toShow(text: string | RegExp, options?: WaitOptions): Promise<void>;
     /** The matched node's own text equals/contains/matches `text`. */
     toHaveText(text: string | RegExp, options?: WaitOptions): Promise<void>;
+    /** The matched checkbox/switch is checked (`checked="true"`). */
+    toBeChecked(options?: WaitOptions): Promise<void>;
+    /** Exactly `count` elements match the selector. */
+    toHaveCount(count: number, options?: WaitOptions): Promise<void>;
 }
 export interface MockAssertions {
     readonly not: MockAssertions;
@@ -42,4 +46,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

@@ -25,6 +25,12 @@ class LocatorExpectation {
             return typeof text === "string" ? content.includes(text) : text.test(content);
         }, `have text ${JSON.stringify(String(text))}`, options);
     }
+    toBeChecked(options = {}) {
+        return this.check(() => this.locator.isChecked(), "be checked", options);
+    }
+    toHaveCount(count, options = {}) {
+        return this.check(async () => (await this.locator.count()) === count, `have count ${count}`, options);
+    }
     async check(predicate, description, options) {
         const want = !this.negated;
         const opts = { ...options, sleep: (ms) => this.locator.driver.pause(ms) };
@@ -86,11 +92,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 +120,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/fixtures.d.ts

@@ -36,13 +36,32 @@ export interface ScenarioFixture<Ctx> {
      * produced and must be safe to call in that state.
      */
     teardown(context: Ctx | undefined): Promise<void>;
+    /**
+     * Invoked when a behaviour throws, before the failure propagates — the seam for
+     * on-failure evidence (e.g. `captureState(...)`), so capture lives here instead of in
+     * every behaviour. Receives the provisioned context and the failing behaviour's title +
+     * error. Its own errors are swallowed (logged) so they never mask the real failure.
+     */
+    onFailure?(context: Ctx, info: FailureInfo): void | Promise<void>;
+}
+/** The failing behaviour's title and the error it threw. */
+export interface FailureInfo {
+    title: string;
+    error: unknown;
 }
 /**
  * Registers one behaviour. The provisioned context is injected, so the body is pure
  * behaviour — no `before`/`after`, no threading a backend handle through assertions.
  * Read it Playwright-style: destructure the fixtures the behaviour needs.
  */
-export type BehaviourRegistrar<Ctx> = (title: string, body: (context: Ctx) => void | Promise<void>) => void;
+export interface BehaviourRegistrar<Ctx> {
+    /** Register one behaviour; the provisioned context is injected into its body. */
+    (title: string, body: (context: Ctx) => void | Promise<void>): void;
+    /** Run before each behaviour in the scenario, with the provisioned context. */
+    beforeEach(body: (context: Ctx) => void | Promise<void>): void;
+    /** Run after each behaviour in the scenario, with the provisioned context. */
+    afterEach(body: (context: Ctx) => void | Promise<void>): void;
+}
 /**
  * Define a behaviour scenario: a Mocha `describe` whose fixture context is
  * provisioned once, injected into every behaviour, and torn down once.

package/dist/fixtures.js

@@ -31,7 +31,8 @@ import { runner } from "./runner.js";
  * });
  */
 export function describeScenario(title, fixture, define) {
-    const { describe, before, after, it } = runner();
+    const hooks = runner();
+    const { describe, before, after, it } = hooks;
     describe(title, () => {
         let context;
         before(async () => {
@@ -40,14 +41,41 @@ export function describeScenario(title, fixture, define) {
         after(async () => {
             await fixture.teardown(context);
         });
-        const test = (behaviourTitle, body) => {
+        const requireContext = () => {
+            if (context === undefined) {
+                throw new Error(`Scenario "${title}" ran a behaviour before its fixture context was provisioned`);
+            }
+            return context;
+        };
+        const registerHook = (hook, name, body) => {
+            if (!hook) {
+                throw new Error(`The active runner has no ${name} hook; scenario ${name} is unavailable`);
+            }
+            hook(async () => {
+                await body(requireContext());
+            });
+        };
+        const test = ((behaviourTitle, body) => {
             it(behaviourTitle, async () => {
-                if (context === undefined) {
-                    throw new Error(`Scenario "${title}" ran a behaviour before its fixture context was provisioned`);
+                const context = requireContext();
+                try {
+                    await body(context);
+                }
+                catch (error) {
+                    if (fixture.onFailure) {
+                        try {
+                            await fixture.onFailure(context, { title: behaviourTitle, error });
+                        }
+                        catch (hookError) {
+                            console.warn(`[nativeproof] onFailure hook threw (ignored): ${hookError}`);
+                        }
+                    }
+                    throw error;
                 }
-                await body(context);
             });
-        };
+        });
+        test.beforeEach = (body) => registerHook(hooks.beforeEach, "beforeEach", body);
+        test.afterEach = (body) => registerHook(hooks.afterEach, "afterEach", body);
         define(test);
     });
 }

package/dist/harness.d.ts

@@ -24,6 +24,10 @@ export interface HarnessTest<S extends ScreenFactories> {
     describe(title: string, body: () => void): void;
     /** Open a scenario block for a specific role (e.g. "member" / "guest"). */
     describe(title: string, role: string, body: () => void): void;
+    /** Run before each behaviour in the open scenario, with the session context injected. */
+    beforeEach(body: (context: SessionContext<S>) => void | Promise<void>): void;
+    /** Run after each behaviour in the open scenario, with the session context injected. */
+    afterEach(body: (context: SessionContext<S>) => void | Promise<void>): void;
 }
 export interface Harness<S extends ScreenFactories> {
     test: HarnessTest<S>;

package/dist/harness.js

@@ -25,5 +25,13 @@ export function createHarness(app) {
             }
         });
     });
+    const requireActive = (hook) => {
+        if (!active) {
+            throw new Error(`test.${hook}(...) must be called inside test.describe(...)`);
+        }
+        return active;
+    };
+    test.beforeEach = (body) => requireActive("beforeEach").beforeEach(body);
+    test.afterEach = (body) => requireActive("afterEach").afterEach(body);
     return { test, expect };
 }

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.d.ts

@@ -11,34 +11,35 @@ import { type Bounds } from "./source.js";
 /** A cross-platform element selector. */
 export type Selector = {
     readonly by: "text";
-    readonly value: string;
+    readonly value: string | RegExp;
 } | {
     readonly by: "desc";
-    readonly value: string;
+    readonly value: string | RegExp;
 } | {
     readonly by: "id";
-    readonly value: string;
+    readonly value: string | RegExp;
 } | {
     readonly by: "testId";
-    readonly value: string;
+    readonly value: string | RegExp;
 } | {
     readonly by: "label";
-    readonly value: string;
+    readonly value: string | RegExp;
 };
 /**
  * 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
  * `content-desc` or a `name`: `by.text("Submit")`, `by.testId("login-button")`,
- * `by.label("Sign out")`, `by.id("message-list")`.
+ * `by.label("Sign out")`, `by.id("message-list")`. Each accepts a string (exact match) or
+ * a RegExp (`by.text(/Save( draft)?/)`), tested against the element's decoded value.
  */
 export declare const by: {
-    readonly text: (value: string) => Selector;
-    readonly desc: (value: string) => Selector;
-    readonly id: (value: string) => Selector;
+    readonly text: (value: string | RegExp) => Selector;
+    readonly desc: (value: string | RegExp) => Selector;
+    readonly id: (value: string | RegExp) => Selector;
     /** The app's test id (Android `resource-id` / Compose testTag, iOS accessibilityIdentifier). */
-    readonly testId: (value: string) => Selector;
+    readonly testId: (value: string | RegExp) => Selector;
     /** The accessibility label (Android `content-desc`, iOS `label`). */
-    readonly label: (value: string) => Selector;
+    readonly label: (value: string | RegExp) => Selector;
 };
 export declare function describeSelector(selector: Selector): string;
 export interface WaitOptions {
@@ -66,9 +67,24 @@ export declare class Locator {
     readonly driver: Driver;
     readonly selector: Selector;
     private readonly options;
-    constructor(driver: Driver, selector: Selector, options?: WaitOptions);
+    /** When set, the locator resolves to the nth match (negative counts from the end). */
+    private readonly index?;
+    constructor(driver: Driver, selector: Selector, options?: WaitOptions, 
+    /** When set, the locator resolves to the nth match (negative counts from the end). */
+    index?: number | undefined);
     private attribute;
-    private presencePattern;
+    /** All node tags this selector matches in the current source, in document order. */
+    private matchedNodes;
+    /** The single node this locator resolves to (the nth match, or the first when unindexed). */
+    private pick;
+    /** A locator scoped to the nth match (0-based; negative counts from the end). */
+    nth(index: number): Locator;
+    /** A locator scoped to the first match. */
+    first(): Locator;
+    /** A locator scoped to the last match. */
+    last(): Locator;
+    /** How many elements currently match the selector. */
+    count(): Promise<number>;
     /** True if the selector matches a node in the current source. */
     isVisible(): Promise<boolean>;
     /** Bounds of the matched node in the current source, or null if absent. */
@@ -87,6 +103,13 @@ export declare class Locator {
      * field — it does not clear existing content first.
      */
     fill(text: string, options?: WaitOptions): Promise<void>;
+    /** True if the matched node is a checked checkbox/switch (`checked="true"`). */
+    isChecked(): Promise<boolean>;
+    /** Tap to bring a checkbox/switch to checked; a no-op if it already is. */
+    check(options?: WaitOptions): Promise<void>;
+    /** Tap to bring a checkbox/switch to unchecked; a no-op if it already is. */
+    uncheck(options?: WaitOptions): Promise<void>;
+    private setChecked;
 }
 /** Convenience factory: `locator(driver, by.text("Submit"))`. */
 export declare function locator(driver: Driver, selector: Selector, options?: WaitOptions): Locator;

package/dist/locator.js

@@ -1,9 +1,10 @@
-import { boundsForAttribute, decodeXmlEntities, encodeXmlEntities, smallestClickableAncestorBounds, } from "./source.js";
+import { decodeXmlEntities, encodeXmlEntities, escapeRegExp, nodesForAttribute, parseBounds, 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
  * `content-desc` or a `name`: `by.text("Submit")`, `by.testId("login-button")`,
- * `by.label("Sign out")`, `by.id("message-list")`.
+ * `by.label("Sign out")`, `by.id("message-list")`. Each accepts a string (exact match) or
+ * a RegExp (`by.text(/Save( draft)?/)`), tested against the element's decoded value.
  */
 export const by = {
     text: (value) => ({ by: "text", value }),
@@ -15,10 +16,8 @@ export const by = {
     label: (value) => ({ by: "label", value }),
 };
 export function describeSelector(selector) {
-    return `by.${selector.by}(${JSON.stringify(selector.value)})`;
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const value = selector.value instanceof RegExp ? String(selector.value) : JSON.stringify(selector.value);
+    return `by.${selector.by}(${value})`;
 }
 /**
  * The page-source attribute a selector resolves to on each platform. `text` is an
@@ -61,40 +60,74 @@ export class Locator {
     driver;
     selector;
     options;
-    constructor(driver, selector, options = {}) {
+    index;
+    constructor(driver, selector, options = {}, 
+    /** When set, the locator resolves to the nth match (negative counts from the end). */
+    index) {
         this.driver = driver;
         this.selector = selector;
         this.options = options;
+        this.index = index;
     }
     attribute() {
         return attributeFor(this.selector, this.driver.platform);
     }
-    presencePattern() {
-        return new RegExp(`${this.attribute()}="${escapeRegExp(encodeXmlEntities(this.selector.value))}"`);
+    /** All node tags this selector matches in the current source, in document order. */
+    async matchedNodes() {
+        return nodesForAttribute(await this.driver.source(), this.attribute(), this.selector.value);
+    }
+    /** The single node this locator resolves to (the nth match, or the first when unindexed). */
+    pick(nodes) {
+        if (this.index === undefined)
+            return nodes[0] ?? null;
+        const at = this.index < 0 ? nodes.length + this.index : this.index;
+        return nodes[at] ?? null;
+    }
+    /** A locator scoped to the nth match (0-based; negative counts from the end). */
+    nth(index) {
+        return new Locator(this.driver, this.selector, this.options, index);
+    }
+    /** A locator scoped to the first match. */
+    first() {
+        return this.nth(0);
+    }
+    /** A locator scoped to the last match. */
+    last() {
+        return this.nth(-1);
+    }
+    /** How many elements currently match the selector. */
+    async count() {
+        return (await this.matchedNodes()).length;
     }
     /** True if the selector matches a node in the current source. */
     async isVisible() {
-        return this.presencePattern().test(await this.driver.source());
+        return this.pick(await this.matchedNodes()) !== null;
     }
     /** Bounds of the matched node in the current source, or null if absent. */
     async bounds() {
-        return boundsForAttribute(await this.driver.source(), this.attribute(), this.selector.value);
+        const node = this.pick(await this.matchedNodes());
+        return node ? parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]) : null;
     }
     /** The matched node's own visible text, or null if the node is absent. */
     async textContent() {
-        const source = await this.driver.source();
-        const selectorPattern = escapeRegExp(encodeXmlEntities(this.selector.value));
-        const node = new RegExp(`<[^>]*${this.attribute()}="${selectorPattern}"[^>]*>`).exec(source)?.[0];
+        const node = this.pick(await this.matchedNodes());
         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) {
         const source = await this.driver.source();
-        if (!this.presencePattern().test(source))
+        if (this.pick(nodesForAttribute(source, this.attribute(), this.selector.value)) === null)
             return false;
         const pattern = typeof text === "string" ? new RegExp(escapeRegExp(encodeXmlEntities(text))) : text;
         return pattern.test(source);
@@ -131,6 +164,30 @@ export class Locator {
         await this.tap(options);
         await this.driver.typeText(text);
     }
+    /** True if the matched node is a checked checkbox/switch (`checked="true"`). */
+    async isChecked() {
+        const node = this.pick(await this.matchedNodes());
+        return node !== null && /\bchecked="true"/.test(node);
+    }
+    /** Tap to bring a checkbox/switch to checked; a no-op if it already is. */
+    async check(options = {}) {
+        await this.setChecked(true, options);
+    }
+    /** Tap to bring a checkbox/switch to unchecked; a no-op if it already is. */
+    async uncheck(options = {}) {
+        await this.setChecked(false, options);
+    }
+    async setChecked(desired, options) {
+        if ((await this.isChecked()) === desired)
+            return;
+        await this.tap(options);
+        const opts = { ...this.options, ...options, sleep: (ms) => this.driver.pause(ms) };
+        const settled = await waitUntil(() => this.isChecked(), (value) => value === desired, opts);
+        if (settled !== desired) {
+            const state = desired ? "checked" : "unchecked";
+            throw new Error(`${describeSelector(this.selector)} did not become ${state} within ${opts.timeout ?? DEFAULTS.timeout}ms`);
+        }
+    }
 }
 /** Convenience factory: `locator(driver, by.text("Submit"))`. */
 export function locator(driver, selector, options = {}) {

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/page.d.ts

@@ -3,22 +3,23 @@ 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.
+ * and you never spell out which native attribute backs it. Every `getBy*` takes a string
+ * (exact match) or a RegExp (`getByText(/Save( draft)?/)`).
  */
 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;
+    getByText(text: string | RegExp, options?: WaitOptions): Locator;
+    getByTestId(testId: string | RegExp, options?: WaitOptions): Locator;
+    getByLabel(label: string | RegExp, options?: WaitOptions): Locator;
+    getById(id: string | RegExp, 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 }`.
+     * accessibility label). Pass `{ name }` — a string for exact match, or a RegExp.
      */
     getByRole(role: string, options: {
-        name: string;
+        name: string | RegExp;
     } & WaitOptions): Locator;
 }
 export declare function page(driver: Driver): Page;

package/dist/runner.d.ts

@@ -1,16 +1,10 @@
-/**
- * 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;
+    /** Optional per-behaviour hooks; present on Mocha and node:test. */
+    beforeEach?(fn: () => void | Promise<void>): void;
+    afterEach?(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. */

package/dist/runner.js

@@ -5,7 +5,7 @@ export function useRunner(hooks) {
 }
 function fromGlobals() {
     const globals = globalThis;
-    const { describe, before, after, it } = globals;
+    const { describe, before, after, beforeEach, afterEach, it } = globals;
     if (typeof describe === "function" &&
         typeof before === "function" &&
         typeof after === "function" &&
@@ -15,6 +15,8 @@ function fromGlobals() {
             before: before,
             after: after,
             it: it,
+            ...(typeof beforeEach === "function" ? { beforeEach: beforeEach } : {}),
+            ...(typeof afterEach === "function" ? { afterEach: afterEach } : {}),
         };
     }
     return null;

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,8 +31,23 @@ 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. */
-export declare function boundsForAttribute(source: string, attribute: string, value: string): Bounds | null;
+/**
+ * The first element tag exposing `attribute` with a value matching `value`. `attribute`
+ * may be a regex alternation (e.g. `"(?:text|content-desc)"`). A string matches the
+ * entity-escaped source exactly; a RegExp is tested against each candidate's DECODED
+ * value, so `by.text(/Save( draft)?/)` matches whether the source XML-escaped it or not.
+ */
+export declare function nodeForAttribute(source: string, attribute: string, value: string | RegExp): string | null;
+/** Every element tag exposing `attribute` with a value matching `value`, in document order. */
+export declare function nodesForAttribute(source: string, attribute: string, value: string | RegExp): string[];
+/** True if any element exposes `attribute` with a value matching `value` (string exact or RegExp). */
+export declare function attributeMatches(source: string, attribute: string, value: string | RegExp): boolean;
+/**
+ * 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 | RegExp): 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`. */

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,45 @@ 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. */
+/**
+ * The first element tag exposing `attribute` with a value matching `value`. `attribute`
+ * may be a regex alternation (e.g. `"(?:text|content-desc)"`). A string matches the
+ * entity-escaped source exactly; a RegExp is tested against each candidate's DECODED
+ * value, so `by.text(/Save( draft)?/)` matches whether the source XML-escaped it or not.
+ */
+export function nodeForAttribute(source, attribute, value) {
+    return nodesForAttribute(source, attribute, value)[0] ?? null;
+}
+/** Every element tag exposing `attribute` with a value matching `value`, in document order. */
+export function nodesForAttribute(source, attribute, value) {
+    if (typeof value === "string") {
+        const escaped = escapeRegExp(encodeXmlEntities(value));
+        return [...source.matchAll(new RegExp(`<[^>]*${attribute}="${escaped}"[^>]*>`, "g"))].map((m) => m[0]);
+    }
+    // A `g`-flagged RegExp is stateful across `.test()` calls; use a non-global copy so the
+    // per-candidate test is order-independent.
+    const test = value.global ? new RegExp(value.source, value.flags.replace("g", "")) : value;
+    const candidate = new RegExp(`${attribute}="([^"]*)"`);
+    const nodes = [];
+    for (const tag of source.matchAll(/<[^>]*>/g)) {
+        const attr = candidate.exec(tag[0]);
+        if (attr && test.test(decodeXmlEntities(attr[1] ?? "")))
+            nodes.push(tag[0]);
+    }
+    return nodes;
+}
+/** True if any element exposes `attribute` with a value matching `value` (string exact or RegExp). */
+export function attributeMatches(source, attribute, value) {
+    return nodeForAttribute(source, attribute, value) !== null;
+}
+/**
+ * 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 = nodeForAttribute(source, attribute, value);
+    return node ? parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]) : null;
 }
 /** Bounds of an element addressed by Android `content-desc`. */
 export function boundsForContentDesc(source, contentDesc) {
@@ -70,8 +104,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.3.0",
+  "version": "0.6.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;
-}