nativeproof 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.9.0
+
+Regex frame matching — `expect(mock)` matches traffic by pattern.
+
+**Added**
+
+- **`toHaveSent` / `toHaveReceived` (and `FrameMatch`) accept a `RegExp`** for `path`, `type`, and any
+  payload field — `expect(mock).toHaveSent({ path: /\/users/, type: "request" })` matches a
+  query-suffixed or otherwise variable path, mirroring regex selectors on the locator side. A string
+  stays an exact match (deep equality for payload objects); a RegExp tests the actual string value.
+
+## 0.8.0
+
+Relative locators — `Locator.near` scopes to the match nearest an anchor.
+
+**Added**
+
+- **`Locator.near(anchor, { maxDistance? })`** — orders this locator's matches by bounds-centre
+  distance to the `anchor` locator's match, nearest first, so a control is addressed by the element
+  beside it: `getByRole("checkbox").near(getByText("Wi-Fi"))` is the checkbox in the Wi-Fi row.
+  `maxDistance` (px) drops farther matches, so an absent control resolves to nothing. Composes with
+  `.nth()` / `.check()` / `expect(locator).toBeChecked()`. Together with role selectors this retires
+  source-bounds geometry for "the control next to this label".
+
 ## 0.7.0
 
 Role selectors — `getByRole` matches by element role, not just name.

package/README.md

@@ -449,8 +449,15 @@ await p.getByText("Item").count();       // how many elements match
 await p.getByText("Item").nth(1).tap();  // the 2nd match (.first() / .last(); negative counts from the end)
 await member.terms.check();              // checkbox/switch → tap to checked (no-op if already there); also uncheck()
 await member.terms.isChecked();          // boolean
+await p.getByRole("checkbox").near(p.getByText("Wi-Fi")).check(); // the checkbox in the Wi-Fi row
 ```
 
+**Relative locators.** `getByRole(role)` matches by element class/type (`checkbox`, `switch`, `button`,
+`textfield`, `image`), and `Locator.near(anchor, { maxDistance? })` scopes to the match nearest an
+anchor's element — so a control beside a label is addressed by the label, not by coordinates:
+`page(driver).getByRole("checkbox").near(page(driver).getByText("Wi-Fi"))`. Compose with `.check()` /
+`expect(locator).toBeChecked()`.
+
 `tap()` resolves the element's bounds from the page source and taps the centre — a coordinate
 tap that works even on Compose / SwiftUI nodes Appium reports as non-clickable.
 
@@ -548,7 +555,8 @@ test.describe("chat room", "member", () => {
 - `mock.route(path).reject({ code })` — fail it (HTTP status, or WebSocket close code 3000–4999).
 - `mock.route(path).abort()` — drop the connect/request entirely.
 - `expect(mock).toHaveSent(match)` / `toHaveReceived(match)` — `match` is a partial frame:
-  `path` / `type` plus any payload fields.
+  `path` / `type` plus any payload fields. Each field is a string (exact / deep-equal) **or a `RegExp`**
+  (`toHaveSent({ path: /\/users/, type: "request" })`) to match a query-suffixed or variable path.
 
 **Frame types** — real protocol messages keep their own `type` (a WS JSON message's `type`); the
 server also synthesises types for primitives so you can assert on them:

package/dist/locator.d.ts

@@ -74,18 +74,36 @@ export declare class Locator {
     private readonly options;
     /** When set, the locator resolves to the nth match (negative counts from the end). */
     private readonly index?;
+    /** When set, matches are ordered by proximity to the anchor (and filtered by maxDistance). */
+    private readonly proximity?;
     constructor(driver: Driver, selector: Selector, options?: WaitOptions, 
     /** When set, the locator resolves to the nth match (negative counts from the end). */
-    index?: number | undefined);
+    index?: number | undefined, 
+    /** When set, matches are ordered by proximity to the anchor (and filtered by maxDistance). */
+    proximity?: {
+        anchor: Locator;
+        maxDistance?: number;
+    } | undefined);
     private attribute;
     /** Node tags this selector matches in `source`, in document order (role- or attribute-based). */
     private nodesIn;
-    /** All node tags this selector matches in the current source, in document order. */
+    /**
+     * All node tags this selector matches in the current source — document order, or, when a
+     * `near` anchor is set, ordered nearest-first by bounds-centre distance (filtered by maxDistance).
+     */
     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;
+    /**
+     * Scope to the match nearest `anchor` (by bounds-centre distance) — the relative locator for
+     * native: `getByRole("checkbox").near(getByText("Wi-Fi"))` is the checkbox in the Wi-Fi row.
+     * `maxDistance` (px) drops matches farther than that, so an absent control resolves to nothing.
+     */
+    near(anchor: Locator, options?: {
+        maxDistance?: number;
+    }): Locator;
     /** A locator scoped to the first match. */
     first(): Locator;
     /** A locator scoped to the last match. */

package/dist/locator.js

@@ -66,13 +66,17 @@ export class Locator {
     selector;
     options;
     index;
+    proximity;
     constructor(driver, selector, options = {}, 
     /** When set, the locator resolves to the nth match (negative counts from the end). */
-    index) {
+    index, 
+    /** When set, matches are ordered by proximity to the anchor (and filtered by maxDistance). */
+    proximity) {
         this.driver = driver;
         this.selector = selector;
         this.options = options;
         this.index = index;
+        this.proximity = proximity;
     }
     attribute() {
         return attributeFor(this.selector, this.driver.platform);
@@ -83,9 +87,28 @@ export class Locator {
             ? nodesForRole(source, this.selector.value, this.driver.platform)
             : nodesForAttribute(source, this.attribute(), this.selector.value);
     }
-    /** All node tags this selector matches in the current source, in document order. */
+    /**
+     * All node tags this selector matches in the current source — document order, or, when a
+     * `near` anchor is set, ordered nearest-first by bounds-centre distance (filtered by maxDistance).
+     */
     async matchedNodes() {
-        return this.nodesIn(await this.driver.source());
+        const nodes = this.nodesIn(await this.driver.source());
+        if (!this.proximity)
+            return nodes;
+        const anchor = await this.proximity.anchor.bounds();
+        if (!anchor)
+            return [];
+        const { maxDistance } = this.proximity;
+        return nodes
+            .map((node) => ({ node, bounds: parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]) }))
+            .filter((entry) => entry.bounds !== null)
+            .map((entry) => ({
+            node: entry.node,
+            distance: Math.hypot(entry.bounds.centerX - anchor.centerX, entry.bounds.centerY - anchor.centerY),
+        }))
+            .filter((entry) => maxDistance === undefined || entry.distance <= maxDistance)
+            .sort((a, b) => a.distance - b.distance)
+            .map((entry) => entry.node);
     }
     /** The single node this locator resolves to (the nth match, or the first when unindexed). */
     pick(nodes) {
@@ -96,7 +119,16 @@ export class Locator {
     }
     /** 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);
+        return new Locator(this.driver, this.selector, this.options, index, this.proximity);
+    }
+    /**
+     * Scope to the match nearest `anchor` (by bounds-centre distance) — the relative locator for
+     * native: `getByRole("checkbox").near(getByText("Wi-Fi"))` is the checkbox in the Wi-Fi row.
+     * `maxDistance` (px) drops matches farther than that, so an absent control resolves to nothing.
+     */
+    near(anchor, options = {}) {
+        const proximity = options.maxDistance === undefined ? { anchor } : { anchor, maxDistance: options.maxDistance };
+        return new Locator(this.driver, this.selector, this.options, this.index, proximity);
     }
     /** A locator scoped to the first match. */
     first() {

package/dist/mock.d.ts

@@ -18,8 +18,8 @@ export interface MockFrame {
 }
 /** A partial frame to match against: `path` / `type` plus any payload fields. */
 export interface FrameMatch {
-    path?: string;
-    type?: string;
+    path?: string | RegExp;
+    type?: string | RegExp;
     [key: string]: unknown;
 }
 /** Controls how an intercepted path replies — the Playwright `Route` equivalent. */

package/dist/mock.js

@@ -1,23 +1,33 @@
 import { isDeepStrictEqual } from "node:util";
+/**
+ * Match one field of an observed frame against an expected value: a `RegExp` tests the
+ * actual string (so paths with query/suffix match — `toHaveSent({ path: /\/users/ })`),
+ * anything else is deep structural equality.
+ */
+function fieldMatches(actual, expected) {
+    if (expected instanceof RegExp)
+        return typeof actual === "string" && expected.test(actual);
+    return isDeepStrictEqual(actual, expected);
+}
 /**
  * True if `frame` satisfies every field of `match`: `path` / `type` at the top level,
  * every other key against the frame's payload.
  */
 export function matchesFrame(frame, match) {
-    if (match.path !== undefined && frame.path !== match.path)
+    if (match.path !== undefined && !fieldMatches(frame.path, match.path))
         return false;
-    if (match.type !== undefined && frame.type !== match.type)
+    if (match.type !== undefined && !fieldMatches(frame.type, match.type))
         return false;
     for (const [key, value] of Object.entries(match)) {
         if (key === "path" || key === "type")
             continue;
-        if (!isDeepStrictEqual(frame.payload?.[key], value))
+        if (!fieldMatches(frame.payload?.[key], value))
             return false;
     }
     return true;
 }
 export function describeMatch(match) {
-    return JSON.stringify(match);
+    return JSON.stringify(match, (_key, value) => (value instanceof RegExp ? String(value) : value));
 }
 /** Single-shot check: does any observed frame match `match` in `direction`? */
 export async function frameExists(source, direction, match) {

package/package.json

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