@testspectra/matchers 1.1.0 → 1.1.8-rc.1

package/src/types.ts

@@ -106,6 +106,26 @@ 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.
  *
@@ -179,6 +199,26 @@ export interface TypeOptions {
   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.).
@@ -244,7 +284,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.
@@ -254,7 +294,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.
@@ -264,7 +304,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.
@@ -274,7 +314,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.
@@ -284,7 +324,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.
@@ -294,7 +334,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).
@@ -304,7 +344,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.
@@ -314,7 +354,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.
@@ -324,7 +364,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.
@@ -334,7 +374,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.
@@ -344,7 +384,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.
@@ -354,7 +394,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.
@@ -366,7 +406,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.
@@ -377,7 +417,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.
@@ -388,7 +428,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.
@@ -399,7 +439,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.
@@ -410,7 +450,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.
@@ -421,7 +461,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.
@@ -432,7 +472,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.
@@ -443,7 +483,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.
@@ -456,7 +496,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.
@@ -467,7 +507,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.
@@ -478,7 +518,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.
@@ -489,7 +529,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.
@@ -501,7 +541,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.
@@ -513,7 +553,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;
 }
 
 /**
@@ -530,7 +570,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.
@@ -541,7 +581,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.
@@ -552,7 +592,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.
@@ -563,7 +603,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.
@@ -573,7 +613,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.
@@ -583,7 +623,7 @@ export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
    * await Spectra.getAll('.product-card').shouldNotBeEmpty();
    * ```
    */
-  shouldNotBeEmpty(): TReturn;
+  shouldNotBeEmpty(options?: AssertionOptions): TReturn;
 }
 
 /**
@@ -600,7 +640,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.
@@ -611,7 +651,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.
@@ -622,7 +662,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.
@@ -633,7 +673,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'.
@@ -643,7 +683,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.
@@ -653,7 +693,7 @@ export interface BrowserReceiverAssertions {
    * await Spectra.browser.shouldHaveNoConsoleErrors();
    * ```
    */
-  shouldHaveNoConsoleErrors(): Promise<void>;
+  shouldHaveNoConsoleErrors(options?: AssertionOptions): Promise<void>;
 
   /**
    * Clears all browser cookies for the active domain.
@@ -665,6 +705,29 @@ 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`.
    *
@@ -686,6 +749,31 @@ export interface SingleElementProxy extends ElementReceiverAssertions<Promise<vo
   /** 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.
    *
@@ -982,10 +1070,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;
@@ -1001,15 +1094,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.
@@ -1031,59 +1129,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.
    *
@@ -1128,36 +1173,44 @@ export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
    * @param type Optional log type filter (e.g. 'browser', 'error').
    */
   getLogs(type?: string): Promise<Array<{ 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>;
+/**
+ * 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 network request interception.
+ * 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;
@@ -1165,8 +1218,20 @@ 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 }>;
 }
 
 /**
@@ -1174,20 +1239,50 @@ export interface MockRule {
  */
 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.
    */
   respondWith: (
     newFixture: unknown,
-    newOptions?: { statusCode?: number; headers?: Record<string, string> },
+    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[];
 }
 
 /**
@@ -1249,12 +1344,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>;
@@ -1462,6 +1561,21 @@ 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.
    *
@@ -1490,6 +1604,19 @@ export interface SpectraStatic {
    */
   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.
    *
@@ -1506,7 +1633,7 @@ export interface SpectraStatic {
     patternOrOptions: string | { url: string; method?: string; response?: unknown },
     method?: string,
     fixture?: unknown,
-    options?: { statusCode?: number; headers?: Record<string, string> },
+    options?: { statusCode?: number; headers?: Record<string, string>; delayMs?: number },
   ): Promise<MockInterceptHandle>;
 
   /**