nativeproof 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.10.2
+
+Generic mock typing and built-in evidence-on-failure.
+
+**Added**
+
+- `defineApp` (and `createHarness` / `defineConfig`) are now generic over the mock type. An app
+  whose mock extends the base contract gets that concrete type through screens, login/join,
+  teardown, `onFailure` and the session context — no casts. Existing single-type-arg uses are
+  unchanged (the mock type defaults to `MockBackend`).
+- The synthesised runner config captures evidence on a failed behaviour out of the box — a
+  screenshot + redacted page source named after the spec — so apps need no hand-written
+  `afterTest`. Best-effort: a capture error never masks the real failure.
+
+## 0.10.1
+
+Cross-platform locator resolution fixes.
+
+**Fixed**
+
+- `by.text` / `getByText` with a `RegExp` now matches a label exposed via `content-desc`
+  (e.g. Compose). The RegExp path previously tested only the first attribute in the
+  `text`/`content-desc` alternation, so a label was missed when an empty `text=""` preceded it.
+- Locators now resolve iOS element geometry (XCUITest `x`/`y`/`width`/`height`), so `tap()`,
+  `bounds()` and `near()` work on iOS — not just Android `bounds="[x1,y1][x2,y2]"`.
+
 ## 0.10.0
 
 Element enabled-state assertions.

package/README.md

@@ -418,6 +418,13 @@ Every `getBy*` (and `by.*`) takes a **string** (exact match) or a **`RegExp`** (
 element's decoded value), so a human pattern matches even entity-escaped source — `getByText(/Save( draft)?/)`,
 `getByLabel(/^Remove /)`, `getByRole("checkbox", { name: /terms/i })`. The Playwright muscle memory carries over.
 
+> **A string selector is exact — case-, space- and punctuation-sensitive.** `getByText("Sign In")`
+> does **not** match a `Sign in` label; it just times out as "not found", with no hint that you were
+> one capital letter away. When you don't yet know a label verbatim — porting an existing suite, or
+> writing the spec before you've seen the screen — reach for a `RegExp` (`getByText(/sign in/i)`) or
+> read the real label off the page source first (see [Troubleshooting](#troubleshooting)). A wrong
+> guess fails the same way a genuinely-missing element does, so confirm the string against the device.
+
 How each maps to the page source:
 
 | Locator | Android attribute | iOS attribute |
@@ -763,9 +770,21 @@ The framework's own unit suite (`npm test`) needs **no device** and runs anywher
 | `no nativeproof.config.ts or wdio.conf.ts found` | Run from the project root, or pass `--config <path>`. |
 | "No specs found" | Specs must match `testDir`/`testMatch` (default `tests/**/*.spec.ts`), or pass `--spec`. |
 | App can't reach the mock | Emulator → use `10.0.2.2`; real device → your machine's LAN IP. Bind the mock with `host: "0.0.0.0"`. |
-| `expect(...)` times out | The selector never matched — confirm the attribute mapping (see the [Locators](#locators) table) and the value; raise `{ timeout }` for slow screens. |
+| `expect(...)` times out | The selector never matched — confirm the attribute mapping (see the [Locators](#locators) table) and the **exact** value (see below); raise `{ timeout }` for slow screens. |
 | iOS first run hangs | WebDriverAgent is building/signing. Set `appium:wdaLaunchTimeout` and, on a real device, the signing capabilities. |
 
+**A selector won't match? Read the source — don't re-guess.** A string that's off by a capital letter,
+a trailing space, or `(1)` vs ` (1)` fails as a silent timeout, identical to a genuinely-absent element.
+The fix is always the same: look at what the device actually exposes.
+
+- On any failure, the `onFailure` hook / `captureState(prefix)` writes the page source to your artifacts
+  dir. Grep it for the real label: `grep -oE 'text="[^"]+"' <file>` and `content-desc="…"` on Android,
+  `label="…"` / `value="…"` on iOS — then match it exactly, or with a `RegExp` if it varies.
+- Or read it live mid-spec: `console.log(await wdioDriver().source())`.
+
+This one-step loop — *fail → read the real attribute → match it* — is behind most "element not found"
+mysteries, and it beats guessing label strings every time.
+
 ## API reference
 
 - `defineApp(definition)` → `app` — the seam; `app.session(role?)` is a scenario fixture. `definition` also

package/dist/app.d.ts

@@ -10,31 +10,36 @@ import type { MockBackend } from "./mock.js";
  * framework core imports nothing from the app; the app describes itself here once.
  * `app.session(role)` turns that into a {@link ScenarioFixture} the `test` facade runs.
  */
-/** The device handles every session provides before app screens are layered on. */
-export interface DeviceContext {
+/**
+ * The device handles every session provides before app screens are layered on.
+ * Generic over the mock type `M` (default {@link MockBackend}) so an app with a richer
+ * mock — extra socket/presence controls beyond the base contract — gets `mock` typed as
+ * that richer type throughout, with no casts. Existing one-arg uses keep the base mock.
+ */
+export interface DeviceContext<M extends MockBackend = MockBackend> {
     driver: Driver;
-    mock: MockBackend;
+    mock: M;
 }
 /** A screen-object factory: given the device context, build that screen's locators/actions. */
-export type ScreenFactory<S> = (context: DeviceContext) => S;
-export type ScreenFactories = Record<string, ScreenFactory<unknown>>;
+export type ScreenFactory<S, M extends MockBackend = MockBackend> = (context: DeviceContext<M>) => S;
+export type ScreenFactories<M extends MockBackend = MockBackend> = Record<string, ScreenFactory<unknown, M>>;
 /** Context passed to the login/join flows. */
-export type FlowContext = DeviceContext & {
+export type FlowContext<M extends MockBackend = MockBackend> = DeviceContext<M> & {
     role: string;
 };
-export interface AppDefinition<S extends ScreenFactories> {
+export interface AppDefinition<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
     /** Acquire the device/driver (e.g. wdioDriver()). */
     driver: () => Driver | Promise<Driver>;
-    /** Start the app's mock backend. */
-    mock: () => MockBackend | Promise<MockBackend>;
+    /** Start the app's mock backend (its concrete type `M` flows through the whole session). */
+    mock: () => M | Promise<M>;
     /** App-specific secret patterns to keep out of evidence (injected, never baked into the core). */
     secrets?: readonly RegExp[];
     /** App-specific evidence-redaction patterns. */
     redact?: readonly RegExp[];
     /** Reach a logged-in state for the role. */
-    login?: (context: FlowContext) => Promise<void>;
+    login?: (context: FlowContext<M>) => Promise<void>;
     /** Enter the role's main surface. */
-    join?: (context: FlowContext) => Promise<void>;
+    join?: (context: FlowContext<M>) => Promise<void>;
     /** Screen-object factories, bound to the device context. */
     screens: S;
     /**
@@ -43,20 +48,20 @@ export interface AppDefinition<S extends ScreenFactories> {
      * so its background sockets are gone before `deleteSession`. The mock is still stopped
      * even if this throws.
      */
-    teardown?: (context: SessionContext<S>) => Promise<void> | void;
+    teardown?: (context: SessionContext<S, M>) => 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;
+    onFailure?: (context: SessionContext<S, M>, 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 & {
+export type SessionContext<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> = DeviceContext<M> & {
     [K in keyof S]: ReturnType<S[K]>;
 };
-export interface App<S extends ScreenFactories> {
+export interface App<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
     /** A scenario fixture that provisions a logged-in, joined session for `role`. */
-    session(role?: string): ScenarioFixture<SessionContext<S>>;
+    session(role?: string): ScenarioFixture<SessionContext<S, M>>;
 }
-export declare function defineApp<S extends ScreenFactories>(definition: AppDefinition<S>): App<S>;
+export declare function defineApp<S extends ScreenFactories<M>, M extends MockBackend = MockBackend>(definition: AppDefinition<S, M>): App<S, M>;

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import type { App, ScreenFactories } from "./app.js";
+import type { MockBackend } from "./mock.js";
 /**
  * The Playwright-style config: one `nativeproof.config.ts` declares the app, the device
  * projects, and where the tests live. The `nativeproof` CLI auto-discovers it and
@@ -43,12 +44,12 @@ export interface RunnerConfig {
     /** Per-test timeout in ms (default 240000). */
     mochaTimeout?: number;
 }
-export interface NativeProofConfig<S extends ScreenFactories = ScreenFactories> extends RunnerConfig {
+export interface NativeProofConfig<S extends ScreenFactories<M> = ScreenFactories, M extends MockBackend = MockBackend> extends RunnerConfig {
     /** The app under test (from `defineApp`). */
-    app: App<S>;
+    app: App<S, M>;
 }
 /** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
-export declare function defineConfig<S extends ScreenFactories>(config: NativeProofConfig<S>): NativeProofConfig<S>;
+export declare function defineConfig<S extends ScreenFactories<M> = ScreenFactories, M extends MockBackend = MockBackend>(config: NativeProofConfig<S, M>): NativeProofConfig<S, M>;
 /** Selection inputs (from the CLI / env) used to resolve the active project + connection. */
 export interface RunnerEnv {
     platform?: string;

package/dist/config.js

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
+import { captureState, failureEvidenceName } from "./evidence.js";
 /** Identity helper for typed config + editor autocomplete (mirrors Playwright's `defineConfig`). */
 export function defineConfig(config) {
     return config;
@@ -43,6 +44,15 @@ export function buildWdioConfig(config, env = {}, cwd = process.cwd()) {
         framework: "mocha",
         reporters: ["spec"],
         mochaOpts: { ui: "bdd", timeout: config.mochaTimeout ?? 240_000 },
+        // Evidence on failure, out of the box: on a failed behaviour, snapshot a screenshot +
+        // redacted page source into the artifact dir, named after the spec. Best-effort — a
+        // capture error never masks the real failure — and consumers get it without writing
+        // their own afterTest hook.
+        afterTest: async (test, _context, result) => {
+            if (result.passed)
+                return;
+            await captureState(failureEvidenceName(test)).catch(() => { });
+        },
     };
 }
 const CONFIG_NAMES = [

package/dist/evidence.d.ts

@@ -3,3 +3,13 @@ export declare function captureText(filename: string, contents: string): Promise
 export declare function captureScreenshot(filename: string): Promise<string>;
 /** Capture a screenshot + redacted source pair under one prefix; returns the source. */
 export declare function captureState(prefix: string): Promise<string>;
+/**
+ * A filesystem-safe evidence prefix for a failed behaviour — `failure-<describe>-<test>`
+ * with runs of non-word characters collapsed to `_` and capped at 120 chars. Used by the
+ * runner's built-in on-failure capture so a failing spec leaves a screenshot + source pair
+ * named after it, with no per-spec wiring.
+ */
+export declare function failureEvidenceName(test: {
+    parent: string;
+    title: string;
+}): string;

package/dist/evidence.js

@@ -42,3 +42,12 @@ export async function captureState(prefix) {
     await captureText(`${prefix}.xml`, source);
     return source;
 }
+/**
+ * A filesystem-safe evidence prefix for a failed behaviour — `failure-<describe>-<test>`
+ * with runs of non-word characters collapsed to `_` and capped at 120 chars. Used by the
+ * runner's built-in on-failure capture so a failing spec leaves a screenshot + source pair
+ * named after it, with no per-spec wiring.
+ */
+export function failureEvidenceName(test) {
+    return `failure-${test.parent}-${test.title}`.replace(/[^\w.-]+/g, "_").slice(0, 120);
+}

package/dist/harness.d.ts

@@ -1,5 +1,6 @@
 import type { App, ScreenFactories, SessionContext } from "./app.js";
 import { expect } from "./expect.js";
+import type { MockBackend } from "./mock.js";
 /**
  * `createHarness(app)` — the Playwright `@playwright/test` pattern.
  *
@@ -18,19 +19,19 @@ import { expect } from "./expect.js";
  * });
  * ```
  */
-export interface HarnessTest<S extends ScreenFactories> {
-    (name: string, body: (context: SessionContext<S>) => void | Promise<void>): void;
+export interface HarnessTest<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
+    (name: string, body: (context: SessionContext<S, M>) => void | Promise<void>): void;
     /** Open a scenario block for the default role. */
     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;
+    beforeEach(body: (context: SessionContext<S, M>) => 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;
+    afterEach(body: (context: SessionContext<S, M>) => void | Promise<void>): void;
 }
-export interface Harness<S extends ScreenFactories> {
-    test: HarnessTest<S>;
+export interface Harness<S extends ScreenFactories<M>, M extends MockBackend = MockBackend> {
+    test: HarnessTest<S, M>;
     expect: typeof expect;
 }
-export declare function createHarness<S extends ScreenFactories>(app: App<S>): Harness<S>;
+export declare function createHarness<S extends ScreenFactories<M>, M extends MockBackend = MockBackend>(app: App<S, M>): Harness<S, M>;

package/dist/locator.js

@@ -1,4 +1,4 @@
-import { decodeXmlEntities, encodeXmlEntities, escapeRegExp, nodesForAttribute, nodesForRole, parseBounds, smallestClickableAncestorBounds, } from "./source.js";
+import { decodeXmlEntities, encodeXmlEntities, escapeRegExp, nodesForAttribute, nodesForRole, parseNodeBounds, 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
@@ -100,7 +100,7 @@ export class Locator {
             return [];
         const { maxDistance } = this.proximity;
         return nodes
-            .map((node) => ({ node, bounds: parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]) }))
+            .map((node) => ({ node, bounds: parseNodeBounds(node) }))
             .filter((entry) => entry.bounds !== null)
             .map((entry) => ({
             node: entry.node,
@@ -149,7 +149,7 @@ export class Locator {
     /** Bounds of the matched node in the current source, or null if absent. */
     async bounds() {
         const node = this.pick(await this.matchedNodes());
-        return node ? parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]) : null;
+        return node ? parseNodeBounds(node) : null;
     }
     /** The matched node's own visible text, or null if the node is absent. */
     async textContent() {

package/dist/source.d.ts

@@ -18,6 +18,14 @@ export type Bounds = {
     centerY: number;
 };
 export declare function parseBounds(bounds: string | undefined | null): Bounds | null;
+/**
+ * Bounds of a single element node, cross-platform. Android UiAutomator exposes geometry as
+ * `bounds="[x1,y1][x2,y2]"`; iOS XCUITest exposes separate `x`/`y`/`width`/`height` attributes
+ * (no `bounds`). Tries the Android form first, then falls back to the iOS attributes — so locators
+ * resolve a tap point on both platforms. Without this, iOS elements have null bounds and `tap()`
+ * never finds a target.
+ */
+export declare function parseNodeBounds(node: string): Bounds | null;
 export declare function escapeRegExp(value: string): string;
 /**
  * Decode the XML entities UiAutomator/XCUITest escape attribute values with

package/dist/source.js

@@ -26,6 +26,38 @@ export function parseBounds(bounds) {
         centerY: Math.round((y1 + y2) / 2),
     };
 }
+/**
+ * Bounds of a single element node, cross-platform. Android UiAutomator exposes geometry as
+ * `bounds="[x1,y1][x2,y2]"`; iOS XCUITest exposes separate `x`/`y`/`width`/`height` attributes
+ * (no `bounds`). Tries the Android form first, then falls back to the iOS attributes — so locators
+ * resolve a tap point on both platforms. Without this, iOS elements have null bounds and `tap()`
+ * never finds a target.
+ */
+export function parseNodeBounds(node) {
+    const android = parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]);
+    if (android)
+        return android;
+    const attr = (name) => {
+        const m = new RegExp(`\\b${name}="(-?\\d+(?:\\.\\d+)?)"`).exec(node);
+        return m ? Number(m[1]) : null;
+    };
+    const x = attr("x");
+    const y = attr("y");
+    const w = attr("width");
+    const h = attr("height");
+    if (x === null || y === null || w === null || h === null)
+        return null;
+    return {
+        x1: Math.round(x),
+        y1: Math.round(y),
+        x2: Math.round(x + w),
+        y2: Math.round(y + h),
+        width: Math.round(w),
+        height: Math.round(h),
+        centerX: Math.round(x + w / 2),
+        centerY: Math.round(y + h / 2),
+    };
+}
 export function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -68,12 +100,19 @@ export function nodesForAttribute(source, attribute, value) {
     // 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}="([^"]*)"`);
+    // `attribute` may be an alternation (e.g. `(?:text|content-desc)`), and a node can carry
+    // more than one of them — Android often exposes both `text=""` and `content-desc="…"`. Test
+    // the pattern against EVERY matching attribute's value, not just the first: otherwise a label
+    // that lives in `content-desc` is missed whenever an empty `text=""` precedes it in the tag.
+    const candidates = new RegExp(`${attribute}="([^"]*)"`, "g");
     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]);
+        for (const attr of tag[0].matchAll(candidates)) {
+            if (test.test(decodeXmlEntities(attr[1] ?? ""))) {
+                nodes.push(tag[0]);
+                break;
+            }
+        }
     }
     return nodes;
 }
@@ -115,7 +154,7 @@ export function attributeMatches(source, attribute, value) {
  */
 export function boundsForAttribute(source, attribute, value) {
     const node = nodeForAttribute(source, attribute, value);
-    return node ? parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]) : null;
+    return node ? parseNodeBounds(node) : null;
 }
 /** Bounds of an element addressed by Android `content-desc`. */
 export function boundsForContentDesc(source, contentDesc) {
@@ -132,7 +171,7 @@ export function boundsForText(source, text) {
  */
 export function smallestClickableAncestorBounds(source, nodeBounds) {
     const clickable = [...source.matchAll(/<[^>]*clickable="true"[^>]*>/g)]
-        .map((m) => parseBounds(/bounds="([^"]+)"/.exec(m[0])?.[1]))
+        .map((m) => parseNodeBounds(m[0]))
         .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.10.0",
+  "version": "0.10.2",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",