nativeproof 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,47 @@ 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.
+
+**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

package/README.md

@@ -60,10 +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.
-- **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.
@@ -370,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).
@@ -390,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` |
@@ -422,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
@@ -446,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
@@ -572,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
@@ -723,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/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.
@@ -44,6 +44,12 @@ export interface AppDefinition<S extends ScreenFactories> {
      * 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

@@ -34,6 +34,7 @@ export function defineApp(definition) {
                         await context.mock.stop();
                     }
                 },
+                ...(definition.onFailure ? { onFailure: definition.onFailure } : {}),
             };
         },
     };

package/dist/expect.d.ts

@@ -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;

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) };

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

@@ -11,34 +11,40 @@ 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 | RegExp;
+} | {
+    readonly by: "role";
     readonly value: string;
 };
 /**
  * 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;
+    /** 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 {
@@ -66,9 +72,26 @@ 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;
+    /** 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). */
+    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 +110,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, escapeRegExp, 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
  * `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 }),
@@ -13,9 +14,12 @@ 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) {
-    return `by.${selector.by}(${JSON.stringify(selector.value)})`;
+    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
@@ -24,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",
@@ -58,30 +65,63 @@ 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))}"`);
+    /** 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 this.nodesIn(await this.driver.source());
+    }
+    /** 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;
         // A visible label can live in either of two attributes per platform, in the same
@@ -98,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.presencePattern().test(source))
+        if (this.pick(this.nodesIn(source)) === null)
             return false;
         const pattern = typeof text === "string" ? new RegExp(escapeRegExp(encodeXmlEntities(text))) : text;
         return pattern.test(source);
@@ -135,6 +175,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/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 }`.
+     * 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;
+    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/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

@@ -31,12 +31,30 @@ export declare function decodeXmlEntities(value: string): string;
  * (`text="Terms & Conditions"`). `&` is encoded first to avoid double-encoding.
  */
 export declare function encodeXmlEntities(value: string): string;
+/**
+ * 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[];
+/** 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;
 /**
  * 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): Bounds | null;
+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

@@ -50,17 +50,72 @@ export function decodeXmlEntities(value) {
 export function encodeXmlEntities(value) {
     return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+/**
+ * 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;
+}
+/**
+ * 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;
+}
 /**
  * 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 node = new RegExp(`<[^>]*${attribute}="${escaped}"[^>]*>`).exec(source)?.[0];
-    if (!node)
-        return null;
-    return parseBounds(/bounds="([^"]+)"/.exec(node)?.[1]);
+    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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nativeproof",
-  "version": "0.5.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.",