nativeproof 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.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/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.1",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",