nativeproof 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.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,7 +60,8 @@ 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.
+  `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.

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,35 @@ 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;
+    readonly value: string | RegExp;
 };
 /**
  * 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;
 };
 export declare function describeSelector(selector: Selector): string;
 export interface WaitOptions {
@@ -66,9 +67,24 @@ 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;
+    /** 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 +103,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, 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 }),
@@ -15,7 +16,8 @@ export const by = {
     label: (value) => ({ by: "label", 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
@@ -58,30 +60,57 @@ 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))}"`);
+    /** 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);
+    }
+    /** 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 +127,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(nodesForAttribute(source, this.attribute(), this.selector.value)) === null)
             return false;
         const pattern = typeof text === "string" ? new RegExp(escapeRegExp(encodeXmlEntities(text))) : text;
         return pattern.test(source);
@@ -135,6 +164,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 }`.
+     * accessibility label). Pass `{ name }` — a string for exact match, or a RegExp.
      */
     getByRole(role: string, options: {
-        name: string;
+        name: string | RegExp;
     } & WaitOptions): Locator;
 }
 export declare function page(driver: Driver): Page;

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,23 @@ 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[];
+/** 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,45 @@ 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;
+}
+/** 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.6.0",
   "license": "MIT",
   "type": "module",
   "description": "Native Mobile E2E test framework inspired by Playwright (fixtures, locators, expect, route-style mocking) on Appium/WebdriverIO.",