nativeproof 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.7.0
+
+Role selectors — `getByRole` matches by element role, not just name.
+
+**Added**
+
+- **`getByRole(role)` / `by.role(role)` match by element class/type** when no `name` is given —
+  `checkbox`, `switch`, `button`, `textfield`, `image`. Maps to the Android widget `class` / iOS
+  XCUITest `type` as a substring, so `SwitchCompat`, `MaterialButton`, and Compose's
+  `android.widget.CheckBox` all resolve. Combine with `.nth()` / `expect(locator).toBeChecked()`.
+  `getByRole(role, { name })` is unchanged (matches the accessibility label); an unknown role throws
+  with the supported list. New `nodesForRole` source helper.
+
 ## 0.6.0
 
 Playwright-parity additions to locators, assertions, fixtures, and evidence.

package/README.md

@@ -60,11 +60,11 @@ 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. 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.
+  `tap()` / `fill()` / `check()` for interaction. Each takes a string (exact) or a **`RegExp`**
+  (`getByText(/Save( draft)?/)`); `.nth()` / `.first()` / `.last()` / `.count()` handle multiple matches.
+- **Auto-waiting `expect`** — `expect(locator).toBeVisible()/toShow()/toHaveText()/toBeChecked()/
+  toHaveCount()` 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.
 - **Network interception** — a first-party HTTP + WebSocket mock server with
   `route().fulfill/reject/abort` (like `page.route()`) and `expect(mock).toHaveSent()/
   toHaveReceived()` traffic assertions. No per-app adapter.
@@ -371,14 +371,28 @@ const app = defineApp({
     member: ({ driver }) => ({ messages: page(driver).getByTestId("message-list") }),
     guest: ({ driver }) => ({ banner: page(driver).getByTestId("signup-banner") }),
   },
+
+  // optional lifecycle hooks:
+  teardown: async ({ driver }) => { /* release app resources before the session is deleted */ },
+  onFailure: async (ctx, { title, error }) => { await captureState(`fail-${title}`); }, // evidence on any failed behaviour
 });
 ```
 
 ```ts
-test.describe("a signed-in member", "member", () => { /* uses { member, mock } */ });
+test.describe("a signed-in member", "member", () => {
+  test.beforeEach(async ({ member }) => { /* reset to a known state before each behaviour */ });
+  test.afterEach(async ({ member }) => { /* per-behaviour cleanup, if any */ });
+  test("renders the latest message", async ({ member, mock }) => { /* … */ });
+});
 test.describe("a guest", "guest", () => { /* uses { guest, mock } */ });
 ```
 
+The session fixture is provisioned **once** per `describe` (the slow login + join) and shared across
+its behaviours; `beforeEach` / `afterEach` run around each behaviour with the context injected — a
+repeatable reset without per-spec boilerplate. `teardown` runs before the mock stops and the session
+is deleted (e.g. force-stop the app); `onFailure` runs when a behaviour throws, before the failure
+propagates, so on-failure evidence lives in one place instead of every behaviour.
+
 > NativeProof locators **read, tap and fill** (text entry). For input `fill()` doesn't cover
 > (clearing a field first, custom keyboards, key chords), drive WebdriverIO's `$(...).setValue(...)`
 > directly inside `login` (the `@wdio/globals` `browser`/`$` are available in the live session).
@@ -391,19 +405,26 @@ you address elements the way a person describes them, not by `content-desc` vs `
 ```ts
 const p = page(driver);
 p.getByText("Sign in");                  // visible text
+p.getByText(/Sign ?in/i);                // ...or a RegExp, matched against the element's decoded value
 p.getByTestId("login-button");           // your test id
 p.getByLabel("Sign out");                // accessibility label
 p.getById("message-list");               // resource id
-p.getByRole("button", { name: "Send" }); // accessible name (role is advisory on native)
+p.getByRole("button", { name: "Send" }); // accessible name
+p.getByRole("checkbox");                 // by role/class — checkbox/switch/button/textfield/image
 p.locator(by.desc("Open menu"));         // escape hatch: a raw selector
 ```
 
+Every `getBy*` (and `by.*`) takes a **string** (exact match) or a **`RegExp`** (tested against the
+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.
+
 How each maps to the page source:
 
 | Locator | Android attribute | iOS attribute |
 |---|---|---|
 | `getByText` / `by.text` | `text` or `content-desc` | `label` or `value` |
 | `getByLabel` / `by.label` / `getByRole({name})` | `content-desc` | `label` |
+| `getByRole(role)` / `by.role` (no name) | widget `class` | XCUITest `type` |
 | `getByTestId` / `by.testId` | `resource-id` | `name` |
 | `getById` / `by.id` | `resource-id` | `name` |
 | `by.desc` | `content-desc` | `name` |
@@ -423,6 +444,11 @@ await member.sendButton.tap();          // wait for it, then tap its centre
 await member.sendButton.tap({ timeout: 2_000, interval: 100 }); // tune the wait
 await member.row.tap({ clickableAncestor: true }); // tap the clickable parent of a non-clickable label
 await member.composer.fill("Hello team"); // focus the field (tap), then type
+
+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
 ```
 
 `tap()` resolves the element's bounds from the page source and taps the centre — a coordinate
@@ -447,12 +473,16 @@ Assertions **auto-wait** (poll until the condition holds or the timeout elapses,
 await expect(member.messages).toBeVisible();
 await expect(member.messages).toShow("Welcome to the room");   // present + text anywhere on screen
 await expect(member.roomTitle).toHaveText(/Room: \w+/);        // the node's OWN text (substring or regex)
+await expect(member.terms).toBeChecked();                      // checkbox / switch is on
+await expect(member.results).toHaveCount(3);                   // exactly 3 elements match
 await expect(member.spinner).not.toBeVisible({ timeout: 5_000 });
 ```
 
 - `toBeVisible(opts?)` — the selector matches a node in the source.
 - `toShow(text, opts?)` — the selector is present **and** `text` appears in the source.
 - `toHaveText(text, opts?)` — the matched node's **own** text contains / matches `text`.
+- `toBeChecked(opts?)` — the matched checkbox / switch is checked (`checked="true"`).
+- `toHaveCount(n, opts?)` — exactly `n` elements match the selector.
 - `opts` is `{ timeout?, interval? }` (ms).
 
 **Value matchers** — `expect(value)` also takes a plain value, for the non-UI assertions a spec
@@ -573,6 +603,11 @@ const app = defineApp({
 The framework depends only on the `MockBackend` interface, never a concrete server — so
 `expect(mock).toHaveSent(...)` reads your backend's traffic with no other changes.
 
+> **Just need the assertions?** If your mock can't implement `route` / `stop` (e.g. it only writes a
+> request/socket log), expose a frames-only **`FrameLog`** — `{ frames(): Promise<MockFrame[]> }`,
+> which `MockBackend` extends — and pass *that* to `expect(...)`: `expect(traffic).toHaveSent({ path, type })`
+> / `.toHaveReceived(...)` auto-wait over it, no `route`/`stop` needed.
+
 ### Gestures & scrolling
 
 For motion the locator layer doesn't cover (scrolling a list, swiping a carousel), use the
@@ -724,15 +759,17 @@ The framework's own unit suite (`npm test`) needs **no device** and runs anywher
 
 ## API reference
 
-- `defineApp(definition)` → `app` — the seam; `app.session(role?)` is a scenario fixture.
-- `createHarness(app)` → `{ test, expect }` — typed, app-bound test surface.
+- `defineApp(definition)` → `app` — the seam; `app.session(role?)` is a scenario fixture. `definition` also
+  takes optional `teardown(ctx)` (before mock stop / session delete) and `onFailure(ctx, { title, error })`.
+- `createHarness(app)` → `{ test, expect }` — typed, app-bound test surface; `test.beforeEach` / `test.afterEach`
+  register per-behaviour hooks with the context injected.
 - `defineConfig({ app, projects, testDir?, testMatch?, appium?, mochaTimeout? })` — the config the CLI runs.
-- `by.text/desc/id/testId/label`, `page(driver).getByText/getByTestId/getByLabel/getById/getByRole`,
+- `by.text/desc/id/testId/label` (string **or** `RegExp`), `page(driver).getByText/getByTestId/getByLabel/getById/getByRole`,
   `page(driver).locator(selector)`, `new Locator(driver, selector)` — locators
-  (`isVisible`, `textContent`, `bounds`, `shows`, `waitFor`, `tap`, `fill` — `tap({ clickableAncestor })`
-  for non-clickable labels).
-- `expect(locator)` → `toBeVisible` / `toShow` / `toHaveText` (+ `.not`), each `(value?, { timeout?, interval? })`.
-- `expect(mock)` → `toHaveSent` / `toHaveReceived` (+ `.not`), matched by partial frame.
+  (`isVisible`, `textContent`, `bounds`, `shows`, `waitFor`, `tap`, `fill`, `isChecked`, `check`, `uncheck`,
+  `count`, `nth`, `first`, `last` — `tap({ clickableAncestor })` for non-clickable labels).
+- `expect(locator)` → `toBeVisible` / `toShow` / `toHaveText` / `toBeChecked` / `toHaveCount` (+ `.not`), each `(value?, { timeout?, interval? })`.
+- `expect(mock | frameLog)` → `toHaveSent` / `toHaveReceived` (+ `.not`), matched by partial frame; accepts any `FrameLog` (`{ frames() }`).
 - `expect(value)` → `toBe` / `toEqual` / `toContain` / `toBeTruthy` / `toBeFalsy` / `toBeDefined` / `toBeNull` (+ `.not`) — synchronous matchers for plain values.
 - `startMockServer({ port?, host? })` → a `MockServer` (`url`, `wsUrl`, `route()`, `frames()`, `send()`, `stop()`).
 - `swipe`, `tapAt`, `pause` — low-level pointer gestures.

package/dist/locator.d.ts

@@ -24,6 +24,9 @@ export type Selector = {
 } | {
     readonly by: "label";
     readonly value: string | RegExp;
+} | {
+    readonly by: "role";
+    readonly value: string;
 };
 /**
  * Build selectors Playwright-style. The cross-platform attribute each maps to is resolved
@@ -40,6 +43,8 @@ export declare const by: {
     readonly testId: (value: string | RegExp) => Selector;
     /** The accessibility label (Android `content-desc`, iOS `label`). */
     readonly label: (value: string | RegExp) => Selector;
+    /** A semantic role, matched by element class/type — `checkbox`, `switch`, `button`, `textfield`, `image`. */
+    readonly role: (value: string) => Selector;
 };
 export declare function describeSelector(selector: Selector): string;
 export interface WaitOptions {
@@ -73,6 +78,8 @@ export declare class Locator {
     /** When set, the locator resolves to the nth match (negative counts from the end). */
     index?: 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. */
     private matchedNodes;
     /** The single node this locator resolves to (the nth match, or the first when unindexed). */

package/dist/locator.js

@@ -1,4 +1,4 @@
-import { decodeXmlEntities, encodeXmlEntities, escapeRegExp, nodesForAttribute, parseBounds, smallestClickableAncestorBounds, } from "./source.js";
+import { decodeXmlEntities, encodeXmlEntities, escapeRegExp, nodesForAttribute, nodesForRole, 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
@@ -14,6 +14,8 @@ export const by = {
     testId: (value) => ({ by: "testId", value }),
     /** The accessibility label (Android `content-desc`, iOS `label`). */
     label: (value) => ({ by: "label", value }),
+    /** A semantic role, matched by element class/type — `checkbox`, `switch`, `button`, `textfield`, `image`. */
+    role: (value) => ({ by: "role", value }),
 };
 export function describeSelector(selector) {
     const value = selector.value instanceof RegExp ? String(selector.value) : JSON.stringify(selector.value);
@@ -26,6 +28,9 @@ export function describeSelector(selector) {
  * the toolkit put it, not just the node's own `text` attribute.
  */
 function attributeFor(selector, platform) {
+    if (selector.by === "role") {
+        throw new Error("role selectors match by element class/type, not a single attribute");
+    }
     const android = {
         text: "(?:text|content-desc)",
         desc: "content-desc",
@@ -72,9 +77,15 @@ export class Locator {
     attribute() {
         return attributeFor(this.selector, this.driver.platform);
     }
+    /** Node tags this selector matches in `source`, in document order (role- or attribute-based). */
+    nodesIn(source) {
+        return this.selector.by === "role"
+            ? 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. */
     async matchedNodes() {
-        return nodesForAttribute(await this.driver.source(), this.attribute(), this.selector.value);
+        return this.nodesIn(await this.driver.source());
     }
     /** The single node this locator resolves to (the nth match, or the first when unindexed). */
     pick(nodes) {
@@ -127,7 +138,7 @@ export class Locator {
     /** True if the selector is present AND `text` appears in the source. */
     async shows(text) {
         const source = await this.driver.source();
-        if (this.pick(nodesForAttribute(source, this.attribute(), this.selector.value)) === null)
+        if (this.pick(this.nodesIn(source)) === null)
             return false;
         const pattern = typeof text === "string" ? new RegExp(escapeRegExp(encodeXmlEntities(text))) : text;
         return pattern.test(source);

package/dist/page.d.ts

@@ -14,12 +14,12 @@ export interface Page {
     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 }` — a string for exact match, or a RegExp.
+     * Match by role. With `{ name }`, matches the element's accessibility label (a string or RegExp) —
+     * the dependable signal on native. Without a name, matches by element class/type
+     * (`checkbox`, `switch`, `button`, `textfield`, `image`) — e.g. `getByRole("checkbox")`.
      */
-    getByRole(role: string, options: {
-        name: string | RegExp;
+    getByRole(role: string, options?: {
+        name?: string | RegExp;
     } & WaitOptions): Locator;
 }
 export declare function page(driver: Driver): Page;

package/dist/page.js

@@ -6,12 +6,14 @@ export function page(driver) {
         getByTestId: (testId, options = {}) => locator(driver, by.testId(testId), options),
         getByLabel: (label, options = {}) => locator(driver, by.label(label), options),
         getById: (id, options = {}) => locator(driver, by.id(id), options),
-        getByRole: (role, options) => {
+        getByRole: (role, options = {}) => {
             const { name, ...wait } = options;
-            if (!name) {
-                throw new Error(`getByRole(${JSON.stringify(role)}) needs { name } on native — it matches the accessible label`);
+            if (name === "") {
+                throw new Error(`getByRole(${JSON.stringify(role)}, { name: "" }) — name must be non-empty; omit it to match by role`);
             }
-            return locator(driver, by.label(name), wait);
+            return name !== undefined
+                ? locator(driver, by.label(name), wait) // name is the dependable signal on native
+                : locator(driver, by.role(role), wait); // no name → match by element class/type
         },
     };
 }

package/dist/source.d.ts

@@ -40,6 +40,13 @@ export declare function encodeXmlEntities(value: string): string;
 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[];
+/** Roles `by.role` / `getByRole(role)` can match without a name. */
+export declare const KNOWN_ROLES: string[];
+/**
+ * Every element whose class (Android) / type (iOS) backs `role`, in document order.
+ * Throws on an unknown role, listing the supported set.
+ */
+export declare function nodesForRole(source: string, role: string, platform: "android" | "ios"): 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;
 /**

package/dist/source.js

@@ -77,6 +77,33 @@ export function nodesForAttribute(source, attribute, value) {
     }
     return nodes;
 }
+/**
+ * Element classes/types that back a semantic role, per platform — Android exposes a widget
+ * `class`, iOS an XCUITest `type`. Matched as a substring, so framework variants
+ * (`SwitchCompat`, `MaterialButton`, Compose's `android.widget.CheckBox`) all resolve.
+ */
+const ROLE_PATTERNS = {
+    checkbox: { android: "CheckBox", ios: "XCUIElementTypeSwitch" },
+    switch: { android: "Switch", ios: "XCUIElementTypeSwitch" },
+    button: { android: "Button", ios: "XCUIElementTypeButton" },
+    textfield: { android: "EditText", ios: "XCUIElementTypeTextField" },
+    image: { android: "ImageView", ios: "XCUIElementTypeImage" },
+};
+/** Roles `by.role` / `getByRole(role)` can match without a name. */
+export const KNOWN_ROLES = Object.keys(ROLE_PATTERNS);
+/**
+ * Every element whose class (Android) / type (iOS) backs `role`, in document order.
+ * Throws on an unknown role, listing the supported set.
+ */
+export function nodesForRole(source, role, platform) {
+    const patterns = ROLE_PATTERNS[role.toLowerCase()];
+    if (!patterns) {
+        throw new Error(`Unknown role "${role}". Known roles: ${KNOWN_ROLES.join(", ")}. Use getByLabel / getByText for arbitrary elements.`);
+    }
+    const attribute = platform === "ios" ? "type" : "class";
+    const pattern = escapeRegExp(platform === "ios" ? patterns.ios : patterns.android);
+    return [...source.matchAll(new RegExp(`<[^>]*${attribute}="[^"]*${pattern}[^"]*"[^>]*>`, "g"))].map((m) => m[0]);
+}
 /** 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;

package/package.json

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