@testspectra/matchers 1.1.0 → 1.1.8-rc.1

package/dist/types.d.ts

@@ -37,6 +37,25 @@ export type Direction = 'up' | 'down' | 'left' | 'right';
  * ```
  */
 export type ElementTarget = string | SingleElementProxy | Promise<SingleElementProxy>;
+/**
+ * Internal descriptor for a selector resolved relative to a parent element, produced by
+ * `element.get()` / `element.getAll()` chaining (see `SingleElementProxy.get`). Recursive so
+ * arbitrarily deep chains (e.g. `Spectra.getAll('.card').nth(2).get('.buy-btn')`) carry their
+ * full ancestry down to the driver.
+ *
+ * Resolution differs per platform: web (CDP) nests real DOM `.querySelector()` calls against the
+ * resolved parent; Android has no ancestor/descendant API, so the parent's bounds rectangle is
+ * used to filter candidates via containment (a child is "within" the parent if its bounds sit
+ * inside the parent's).
+ */
+export interface ScopedSelector {
+    /** This level's own selector string (`~`/`#` shorthand or raw CSS/xpath), not the full chain. */
+    selector: string;
+    /** Positional index at this level, or null. */
+    index: number | null;
+    /** The element this selector is scoped within, or undefined for a root-level selector. */
+    parent?: ScopedSelector;
+}
 /**
  * Configuration options for scroll actions.
  *
@@ -105,6 +124,25 @@ export interface TypeOptions {
     /** Whether to clear existing input value before typing new text (default: false) */
     clearFirst?: boolean;
 }
+/**
+ * Per-call override for how long an assertion polls before failing, mirroring Playwright's
+ * `{ timeout }` option on web-first assertions (`expect(locator).toHaveText(x, { timeout })`).
+ *
+ * Defaults to the adaptive assertion timeout (`Spectra`'s fail-fast cap, distinct from
+ * `implicitWait`) when omitted — pass this when a specific assertion is known to need longer,
+ * e.g. right after a deliberately delayed `Spectra.intercept(..., { delayMs })` mock, without
+ * raising the timeout for every other assertion in the test.
+ *
+ * @example
+ * ```ts
+ * const mock = await Spectra.intercept('/api/report', { response: { delayMs: 4000, body } });
+ * await ReportPage.statusBadge.shouldHaveText('Ready', { timeoutMs: 5000 });
+ * ```
+ */
+export interface AssertionOptions {
+    /** Maximum time (in milliseconds) to keep polling before the assertion fails. */
+    timeoutMs?: number;
+}
 /**
  * Canonical assertion matcher keys for single element verification.
  * Dispatched internally by semantic receiver methods (`.shouldBeVisible()`, `.shouldHaveText()`, etc.).
@@ -129,7 +167,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await LoginPage.submitButton.shouldBeVisible();
      * ```
      */
-    shouldBeVisible(): TReturn;
+    shouldBeVisible(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element is hidden, detached, or not displayed on the page.
      *
@@ -138,7 +176,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.loading-spinner').shouldNotBeVisible();
      * ```
      */
-    shouldNotBeVisible(): TReturn;
+    shouldNotBeVisible(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element exists in the DOM.
      *
@@ -147,7 +185,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#cookie-consent-modal').shouldExist();
      * ```
      */
-    shouldExist(): TReturn;
+    shouldExist(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element does not exist in the DOM.
      *
@@ -156,7 +194,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#deleted-record-row').shouldNotExist();
      * ```
      */
-    shouldNotExist(): TReturn;
+    shouldNotExist(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element is visible, enabled, and clickable.
      *
@@ -165,7 +203,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('button[type="submit"]').shouldBeClickable();
      * ```
      */
-    shouldBeClickable(): TReturn;
+    shouldBeClickable(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element is disabled, covered, or not clickable.
      *
@@ -174,7 +212,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('button.disabled-action').shouldNotBeClickable();
      * ```
      */
-    shouldNotBeClickable(): TReturn;
+    shouldNotBeClickable(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target form input/button is enabled (not disabled).
      *
@@ -183,7 +221,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#username-field').shouldBeEnabled();
      * ```
      */
-    shouldBeEnabled(): TReturn;
+    shouldBeEnabled(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target form input/button has the disabled state/attribute.
      *
@@ -192,7 +230,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#submit-order-btn').shouldBeDisabled();
      * ```
      */
-    shouldBeDisabled(): TReturn;
+    shouldBeDisabled(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target checkbox or radio input is checked/selected.
      *
@@ -201,7 +239,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#terms-checkbox').shouldBeChecked();
      * ```
      */
-    shouldBeChecked(): TReturn;
+    shouldBeChecked(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target checkbox or radio input is unchecked/deselected.
      *
@@ -210,7 +248,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#subscribe-newsletter').shouldNotBeChecked();
      * ```
      */
-    shouldNotBeChecked(): TReturn;
+    shouldNotBeChecked(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element currently holds active document focus.
      *
@@ -219,7 +257,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#search-input').shouldBeFocused();
      * ```
      */
-    shouldBeFocused(): TReturn;
+    shouldBeFocused(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element does not hold active document focus.
      *
@@ -228,7 +266,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('#blur-input').shouldNotBeFocused();
      * ```
      */
-    shouldNotBeFocused(): TReturn;
+    shouldNotBeFocused(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element's text content matches the expected string or regular expression.
      *
@@ -239,7 +277,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.badge').shouldHaveText(/Active|Pending/);
      * ```
      */
-    shouldHaveText(expected: string | RegExp): TReturn;
+    shouldHaveText(expected: string | RegExp, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element's text content does not match the expected string or regular expression.
      *
@@ -249,7 +287,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.status-label').shouldNotHaveText('Error');
      * ```
      */
-    shouldNotHaveText(expected: string | RegExp): TReturn;
+    shouldNotHaveText(expected: string | RegExp, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element's text content contains the specified substring.
      *
@@ -259,7 +297,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.toast-message').shouldContainText('Successfully saved');
      * ```
      */
-    shouldContainText(substring: string): TReturn;
+    shouldContainText(substring: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the target element's text content does not contain the specified substring.
      *
@@ -269,7 +307,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.log-output').shouldNotContainText('Fatal Exception');
      * ```
      */
-    shouldNotContainText(substring: string): TReturn;
+    shouldNotContainText(substring: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the form input or textarea element's value exactly equals the specified string.
      *
@@ -279,7 +317,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('input[name="email"]').shouldHaveValue('admin@testspectra.dev');
      * ```
      */
-    shouldHaveValue(value: string): TReturn;
+    shouldHaveValue(value: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the form input or textarea element's value does not equal the specified string.
      *
@@ -289,7 +327,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('input[name="role"]').shouldNotHaveValue('guest');
      * ```
      */
-    shouldNotHaveValue(value: string): TReturn;
+    shouldNotHaveValue(value: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the form input or textarea element's value contains the specified substring.
      *
@@ -299,7 +337,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('input[name="email"]').shouldContainValue('@testspectra.dev');
      * ```
      */
-    shouldContainValue(substring: string): TReturn;
+    shouldContainValue(substring: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the form input or textarea element's value does not contain the specified substring.
      *
@@ -309,7 +347,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('input[name="url"]').shouldNotContainValue('http://');
      * ```
      */
-    shouldNotContainValue(substring: string): TReturn;
+    shouldNotContainValue(substring: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the element has the specified attribute, and optionally that its value matches.
      *
@@ -321,7 +359,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('input.required-field').shouldHaveAttribute('required');
      * ```
      */
-    shouldHaveAttribute(name: string, value?: string): TReturn;
+    shouldHaveAttribute(name: string, value?: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the element does not have the specified attribute.
      *
@@ -331,7 +369,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('button#action-btn').shouldNotHaveAttribute('disabled');
      * ```
      */
-    shouldNotHaveAttribute(name: string): TReturn;
+    shouldNotHaveAttribute(name: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the element contains the specified CSS class name.
      *
@@ -341,7 +379,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.nav-tab').shouldHaveClass('active');
      * ```
      */
-    shouldHaveClass(className: string): TReturn;
+    shouldHaveClass(className: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the element does not contain the specified CSS class name.
      *
@@ -351,7 +389,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.modal-backdrop').shouldNotHaveClass('hidden');
      * ```
      */
-    shouldNotHaveClass(className: string): TReturn;
+    shouldNotHaveClass(className: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the computed CSS style property of the element equals the specified value.
      *
@@ -362,7 +400,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.badge-success').shouldHaveCss('color', 'rgb(0, 128, 0)');
      * ```
      */
-    shouldHaveCss(property: string, value: string): TReturn;
+    shouldHaveCss(property: string, value: string, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the computed CSS style property of the element does not equal the specified value.
      *
@@ -373,7 +411,7 @@ export interface ElementReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.get('.main-content').shouldNotHaveCss('display', 'none');
      * ```
      */
-    shouldNotHaveCss(property: string, value: string): TReturn;
+    shouldNotHaveCss(property: string, value: string, options?: AssertionOptions): TReturn;
 }
 /**
  * Receiver-oriented collection assertion methods.
@@ -389,7 +427,7 @@ export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.getAll('.user-table-row').shouldHaveLength(10);
      * ```
      */
-    shouldHaveLength(count: number): TReturn;
+    shouldHaveLength(count: number, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the collection does not contain the specified number of matching elements.
      *
@@ -399,7 +437,7 @@ export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.getAll('.error-item').shouldNotHaveLength(0);
      * ```
      */
-    shouldNotHaveLength(count: number): TReturn;
+    shouldNotHaveLength(count: number, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the collection contains strictly more than `min` matching elements.
      *
@@ -409,7 +447,7 @@ export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.getAll('.search-result-card').shouldHaveLengthGreaterThan(0);
      * ```
      */
-    shouldHaveLengthGreaterThan(min: number): TReturn;
+    shouldHaveLengthGreaterThan(min: number, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the collection contains strictly fewer than `max` matching elements.
      *
@@ -419,7 +457,7 @@ export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.getAll('.warning-banner').shouldHaveLengthLessThan(5);
      * ```
      */
-    shouldHaveLengthLessThan(max: number): TReturn;
+    shouldHaveLengthLessThan(max: number, options?: AssertionOptions): TReturn;
     /**
      * Asserts that the collection contains zero matching elements.
      *
@@ -428,7 +466,7 @@ export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.getAll('.unread-notification-badge').shouldBeEmpty();
      * ```
      */
-    shouldBeEmpty(): TReturn;
+    shouldBeEmpty(options?: AssertionOptions): TReturn;
     /**
      * Asserts that the collection contains at least one matching element.
      *
@@ -437,7 +475,7 @@ export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
      * await Spectra.getAll('.product-card').shouldNotBeEmpty();
      * ```
      */
-    shouldNotBeEmpty(): TReturn;
+    shouldNotBeEmpty(options?: AssertionOptions): TReturn;
 }
 /**
  * Browser-level context assertion methods.
@@ -453,7 +491,7 @@ export interface BrowserReceiverAssertions {
      * await Spectra.browser.shouldHaveUrl('https://app.testspectra.dev/dashboard');
      * ```
      */
-    shouldHaveUrl(expectedUrl: string): Promise<void>;
+    shouldHaveUrl(expectedUrl: string, options?: AssertionOptions): Promise<void>;
     /**
      * Asserts that current browser URL contains the specified substring.
      *
@@ -463,7 +501,7 @@ export interface BrowserReceiverAssertions {
      * await Spectra.browser.shouldContainUrl('/dashboard');
      * ```
      */
-    shouldContainUrl(expectedSubstr: string): Promise<void>;
+    shouldContainUrl(expectedSubstr: string, options?: AssertionOptions): Promise<void>;
     /**
      * Asserts that current page title exactly matches the expected title.
      *
@@ -473,7 +511,7 @@ export interface BrowserReceiverAssertions {
      * await Spectra.browser.shouldHaveTitle('Dashboard - TestSpectra');
      * ```
      */
-    shouldHaveTitle(expectedTitle: string): Promise<void>;
+    shouldHaveTitle(expectedTitle: string, options?: AssertionOptions): Promise<void>;
     /**
      * Asserts that current page title contains the specified substring.
      *
@@ -483,7 +521,7 @@ export interface BrowserReceiverAssertions {
      * await Spectra.browser.shouldContainTitle('Dashboard');
      * ```
      */
-    shouldContainTitle(expectedSubstr: string): Promise<void>;
+    shouldContainTitle(expectedSubstr: string, options?: AssertionOptions): Promise<void>;
     /**
      * Asserts that the browser document `readyState` is 'complete' or 'interactive'.
      *
@@ -492,7 +530,7 @@ export interface BrowserReceiverAssertions {
      * await Spectra.browser.shouldBeLoaded();
      * ```
      */
-    shouldBeLoaded(): Promise<void>;
+    shouldBeLoaded(options?: AssertionOptions): Promise<void>;
     /**
      * Asserts that no severe or unhandled JavaScript errors occurred in the browser console.
      *
@@ -501,7 +539,7 @@ export interface BrowserReceiverAssertions {
      * await Spectra.browser.shouldHaveNoConsoleErrors();
      * ```
      */
-    shouldHaveNoConsoleErrors(): Promise<void>;
+    shouldHaveNoConsoleErrors(options?: AssertionOptions): Promise<void>;
     /**
      * Clears all browser cookies for the active domain.
      *
@@ -511,6 +549,28 @@ export interface BrowserReceiverAssertions {
      * ```
      */
     clearCookies(): Promise<void>;
+    /**
+     * Applies one or more raw `Set-Cookie` header values — exactly as received from a `fetch()`
+     * response, e.g. `response.headers.getSetCookie()` — to the browser's cookie jar. Operates at
+     * the CDP `Network` domain level rather than through `document.cookie`, so `HttpOnly` cookies
+     * are fully supported (set, not just read-blocked). Useful for seeding an authenticated session
+     * by logging in via a direct API call instead of driving the real login UI — see
+     * `docs/v2/features/authentication-and-session-seeding.md`.
+     *
+     * `url` is required to resolve `Domain`/`Path`/`Secure` defaults for any `Set-Cookie` value that
+     * doesn't specify them explicitly (an omitted `Domain` defaults to the issuing request's own
+     * host, per RFC 6265) — pass the URL the response actually came from.
+     *
+     * Web only — Android has no browser/cookie-jar concept; see the docs above for the mobile
+     * equivalent (deep-link-triggered, Keystore-backed session seeding).
+     *
+     * @example
+     * ```ts
+     * const res = await fetch('https://api.example.com/auth/login', { method: 'POST', body: ... });
+     * await Spectra.browser.setCookies(res.headers.getSetCookie(), res.url);
+     * ```
+     */
+    setCookies(setCookieHeaders: string | string[], url: string): Promise<void>;
     /**
      * Clears all key-value entries in browser `localStorage`.
      *
@@ -529,6 +589,29 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
     selector: string;
     /** Positional index when matched from a collection (or null for standalone selectors). */
     index: number | null;
+    /**
+     * Finds `childSelector` scoped to this element's subtree, mirroring Playwright's locator
+     * chaining (`parent.locator(child)`) instead of a separate `within()`/`findWithin()` verb.
+     * Resolution is a real DOM descendant query on web; on Android (no ancestor API) it's a
+     * bounds-containment heuristic over the flat accessibility-tree dump.
+     *
+     * @example
+     * ```ts
+     * const modal = Spectra.get('#modal');
+     * await modal.get('#save-btn').click();
+     * ```
+     */
+    get(childSelector: string, index?: number | null): SingleElementProxy;
+    /**
+     * Finds all elements matching `childSelector` scoped to this element's subtree — the
+     * collection equivalent of `get()`.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#modal').getAll('.list-item').shouldHaveLength(3);
+     * ```
+     */
+    getAll(childSelector: string): CollectionProxy;
     /**
      * Waits until the element exists in the DOM within the specified timeout.
      *
@@ -794,10 +877,15 @@ export interface CollectionProxy extends CollectionReceiverAssertions<Promise<vo
     /**
      * Returns a `SingleElementProxy` pointing to the matching element at the specified zero-based index.
      *
+     * When this collection itself came from a `.getAll()` chain, `first()`/`last()`/`nth()` carry
+     * that scope forward instead of reverting to an unscoped lookup — e.g. the button below is
+     * resolved within the 3rd `.card`, not just anywhere on the page:
+     *
      * @param index Zero-based index of the target element.
      * @example
      * ```ts
      * await Spectra.getAll('.list-item').nth(2).click();
+     * await Spectra.getAll('.card').nth(2).get('.buy-btn').click();
      * ```
      */
     nth(index: number): SingleElementProxy;
@@ -811,15 +899,20 @@ export type SpectraCollection = CollectionProxy;
  */
 export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
     /**
-     * Navigates the browser to the specified absolute or relative URL.
+     * All network requests recorded so far this session — both genuine (non-intercepted) traffic
+     * and requests an active `intercept()` mock fulfilled. Recording is always on; nothing needs
+     * to be explicitly enabled first. On Android, only requests routed through the worker's local
+     * mock proxy are recorded (see `Spectra.intercept`'s docs on why mobile needs an absolute URL
+     * rather than a relative path) — a request the app makes that never reaches the proxy at all
+     * won't appear here.
      *
-     * @param targetUrl Target destination URL.
      * @example
      * ```ts
-     * await Spectra.browser.url('/auth/login');
+     * await Spectra.get('~fetch-api-btn').click();
+     * const entry = Spectra.browser.recordedNetwork.find((e) => e.url.includes('/posts'));
      * ```
      */
-    url(targetUrl: string): Promise<void>;
+    recordedNetwork: CDPNetworkEntry[];
     /**
      * Retrieves the current browser URL.
      *
@@ -838,54 +931,6 @@ export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
      * ```
      */
     getTitle(): Promise<string>;
-    /**
-     * Navigates one step back in the browser history.
-     *
-     * @example
-     * ```ts
-     * await Spectra.browser.back();
-     * ```
-     */
-    back(): Promise<void>;
-    /**
-     * Navigates one step forward in the browser history.
-     *
-     * @example
-     * ```ts
-     * await Spectra.browser.forward();
-     * ```
-     */
-    forward(): Promise<void>;
-    /**
-     * Reloads / refreshes the current active page.
-     *
-     * @example
-     * ```ts
-     * await Spectra.browser.refresh();
-     * ```
-     */
-    refresh(): Promise<void>;
-    /**
-     * Pauses test execution for the specified number of milliseconds.
-     *
-     * @param ms Duration in milliseconds to pause.
-     * @example
-     * ```ts
-     * await Spectra.browser.pause(1000);
-     * ```
-     */
-    pause(ms: number): Promise<void>;
-    /**
-     * Sets the browser viewport dimensions (width and height in pixels).
-     *
-     * @param width Viewport width in pixels.
-     * @param height Viewport height in pixels.
-     * @example
-     * ```ts
-     * await Spectra.browser.setViewport(1920, 1080);
-     * ```
-     */
-    setViewport(width: number, height: number): Promise<void>;
     /**
      * Executes a JavaScript function or script snippet in the browser context and returns the result.
      *
@@ -933,32 +978,41 @@ export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
         level: string;
         message: string;
     }>>;
-    /**
-     * Intercepts and mocks HTTP network requests matching the specified URL pattern.
-     *
-     * @param pattern URL substring or glob pattern to intercept.
-     * @param method HTTP method (GET, POST, PUT, DELETE, etc.).
-     * @param fixture Mock response payload object or string.
-     * @param options Mock response options (status code, custom headers).
-     * @example
-     * ```ts
-     * const mock = await Spectra.browser.intercept('/api/v1/users', 'GET', [{ id: 1, name: 'Alice' }], {
-     *   statusCode: 200,
-     * });
-     * ```
-     */
-    intercept(pattern: string, method?: string, fixture?: unknown, options?: {
-        statusCode?: number;
-        headers?: Record<string, string>;
-    }): Promise<MockInterceptHandle>;
 }
 /**
- * Mock rule configuration for CDP network request interception.
+ * Intercepted HTTP request metadata captured during test execution.
+ */
+export interface InterceptedRequest {
+    /** Optional unique identifier for the request */
+    id?: string;
+    /** Target request URL */
+    url: string;
+    /** HTTP method */
+    method: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body / payload if available */
+    postData?: string;
+    /** Timestamp when intercepted */
+    timestamp: number;
+}
+/**
+ * Queued one-time mock response item for FIFO polling and retry flows.
+ */
+export interface QueuedMockResponse {
+    response: unknown;
+    statusCode: number;
+    headers?: Record<string, string>;
+    /** Milliseconds to wait before fulfilling this response — simulates a late/slow network reply. */
+    delayMs?: number;
+}
+/**
+ * Mock rule configuration for CDP & Mobile network request interception.
  */
 export interface MockRule {
     /** URL pattern or substring to match. */
     pattern: string;
-    /** HTTP method (e.g. GET, POST). */
+    /** HTTP method (e.g. GET, POST, ALL). */
     method: string;
     /** Mock response payload. */
     response: unknown;
@@ -966,15 +1020,30 @@ export interface MockRule {
     statusCode: number;
     /** Custom HTTP response headers. */
     headers?: Record<string, string>;
+    /** Milliseconds to wait before fulfilling the default response — simulates a late/slow reply. */
+    delayMs?: number;
     /** Total times this mock rule matched and intercepted requests. */
     callCount: number;
+    /** FIFO queue of one-time responses (respondOnce) */
+    respondOnceQueue: QueuedMockResponse[];
+    /** Whether requests matching this rule should be aborted / failed */
+    aborted?: boolean;
+    /** Specific error code for network abort simulation */
+    abortReason?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset';
+    /** Recorded list of intercepted requests matching this rule */
+    calls: InterceptedRequest[];
+    /** Internal pending waitForCall resolvers (keyed by expected call count). */
+    waitResolvers: Array<{
+        count: number;
+        resolve: (req: InterceptedRequest) => void;
+    }>;
 }
 /**
  * Handle returned by `Spectra.intercept()` to dynamically inspect and update mock responses.
  */
 export interface MockInterceptHandle {
     /**
-     * Dynamically updates the response payload for this active mock rule.
+     * Dynamically updates the default response payload for this active mock rule.
      *
      * @param newFixture New response payload object or string.
      * @param newOptions Optional status code and header overrides.
@@ -982,11 +1051,42 @@ export interface MockInterceptHandle {
     respondWith: (newFixture: unknown, newOptions?: {
         statusCode?: number;
         headers?: Record<string, string>;
+        delayMs?: number;
+    }) => Promise<void>;
+    /**
+     * Queues a one-time mock response for the next matching request (FIFO queue for polling/retries).
+     *
+     * @param newFixture One-time response payload object or string.
+     * @param newOptions Optional status code and header overrides.
+     */
+    respondOnce: (newFixture: unknown, newOptions?: {
+        statusCode?: number;
+        headers?: Record<string, string>;
+        delayMs?: number;
     }) => Promise<void>;
+    /**
+     * Simulates a network failure or connection abort for matching requests.
+     *
+     * @param errorCode Network failure reason (default: 'Failed').
+     */
+    abort: (errorCode?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset') => Promise<void>;
+    /**
+     * Awaits until the mock rule has intercepted at least `count` matching requests.
+     *
+     * @param options Timeout and expected request count.
+     */
+    waitForCall: (options?: {
+        timeout?: number;
+        count?: number;
+    }) => Promise<InterceptedRequest>;
     /**
      * Returns the number of times this mock intercepted network requests.
      */
-    callCount: () => number;
+    callCount: (() => number) & number;
+    /**
+     * Historical array of all intercepted requests matching this rule.
+     */
+    calls: InterceptedRequest[];
 }
 /**
  * Audit log entry for captured CDP network requests.
@@ -1047,12 +1147,16 @@ export interface SpectraStatic {
      */
     getAll(selector: string): CollectionProxy;
     /**
-     * Navigates the active browser window or mobile webview to the specified URL.
+     * Navigates the active browser window to the specified URL. On Android, deep-links directly
+     * into the app via `adb shell am start` instead — pass a full URI matching a scheme the app
+     * registers (e.g. `expo-router`'s `scheme` in `app.json`), not a bare path, since there's no
+     * configured base scheme to combine one against.
      *
-     * @param url Absolute or relative URL destination.
+     * @param url Absolute or relative URL on web; a full deep-link URI on Android.
      * @example
      * ```ts
-     * await Spectra.navigate('/dashboard');
+     * await Spectra.navigate('/dashboard'); // web
+     * await Spectra.navigate('testspectra-demo://permission-rationale'); // Android
      * ```
      */
     navigate(url: string): Promise<void>;
@@ -1241,6 +1345,20 @@ export interface SpectraStatic {
      * ```
      */
     pressKey(key: KeyOption | string): Promise<void>;
+    /**
+     * Grants an Android runtime permission on demand — typically called right after confirming an
+     * in-app rationale dialog, so a test can exercise its own permission-request UX instead of
+     * having every permission pre-granted before the app even launches. No-op on platforms without
+     * an OS-level runtime permission model (e.g. web).
+     *
+     * @param name Fully-qualified Android permission name (e.g. 'android.permission.CAMERA').
+     * @example
+     * ```ts
+     * await Spectra.get('~rationale-allow-btn').click();
+     * await Spectra.grantPermission('android.permission.CAMERA');
+     * ```
+     */
+    grantPermission(name: string): Promise<void>;
     /**
      * Pauses test execution for the specified number of milliseconds.
      *
@@ -1266,6 +1384,18 @@ export interface SpectraStatic {
      * Direct access to browser context commands and page assertions.
      */
     browser: SpectraBrowserBridge;
+    /**
+     * Typed environment variables from `spectra.config.ts`'s `executionConfig.environmentVariables`.
+     * Each configured key is generated into `.testspectra/types/env.d.ts` as a `SpectraEnv` member
+     * (TypeScript interface merging), so `Spectra.env.MY_KEY` resolves to `string` — never
+     * `string | undefined` like raw `process.env.MY_KEY` would.
+     *
+     * @example
+     * ```ts
+     * const mode = Spectra.env.API_MODE;
+     * ```
+     */
+    env: SpectraEnv;
     /**
      * Intercepts and mocks HTTP network requests matching the specified pattern or options.
      *
@@ -1285,6 +1415,7 @@ export interface SpectraStatic {
     }, method?: string, fixture?: unknown, options?: {
         statusCode?: number;
         headers?: Record<string, string>;
+        delayMs?: number;
     }): Promise<MockInterceptHandle>;
     /**
      * Clears and resets all active CDP network interception rules.