@testspectra/matchers 1.1.0-rc.0 → 1.1.0-rc.1

package/dist/contract.d.ts

@@ -7,7 +7,7 @@
  * (`WebCdpDriverBridge`, `AndroidTcpDriverBridge`) implements this interface so that the
  * DSL layer contains zero platform branching.
  */
-import type { CDPNetworkEntry, MockInterceptHandle, MockRule, ScrollOptions, SpectraBrowserBridge, SwipeOptions } from './types.js';
+import type { CDPNetworkEntry, MockInterceptHandle, MockRule, ScopedSelector, ScrollOptions, SpectraBrowserBridge, SwipeOptions } from './types.js';
 /**
  * Runtime configuration injected by the Rust orchestrator via `globalThis.__TESTSPECTRA_CONFIG__`.
  */
@@ -39,6 +39,15 @@ export interface RuntimeWorkerConfig {
     implicitWaitMs?: number;
     timeoutMs?: number;
     stepDelayMs?: number;
+    /** Mirrors `spectra.config.ts`'s `executionConfig.networkMonitoringEnabled` (default: true). */
+    networkMonitoringEnabled?: boolean;
+    /** Mirrors `spectra.config.ts`'s `executionConfig.monitoredDomains`. Empty/absent = capture all. */
+    monitoredDomains?: {
+        domain: string;
+        enabled: boolean;
+    }[];
+    /** Mirrors `spectra.config.ts`'s `executionConfig.environmentVariables`. */
+    environmentVariables?: Record<string, string>;
 }
 /**
  * Cross-cutting shared runtime state injected into the assembled worker script.
@@ -60,16 +69,19 @@ export interface RuntimeContext {
     getImplicitWaitMs(): number;
     getAssertionTimeoutMs(): number;
     matchesUrlPattern(pattern: string, url: string): boolean;
+    /** Whether a captured network request/response for `url` should be recorded, per
+     * `config.networkMonitoringEnabled` / `config.monitoredDomains`. */
+    shouldRecordNetworkEntry(url: string): boolean;
     createMockHandle(rule: MockRule): MockInterceptHandle;
     parseMockRule(patternOrOptions?: any, maybeMethodOrHandler?: any, maybeFixture?: any, maybeOptions?: any): MockRule;
     recordDuration?: (label: string, category: string, durationMs: number, extra?: Record<string, unknown>) => void;
     withDuration?: <T>(label: string, category: string, fn: () => Promise<T>, extra?: Record<string, unknown>) => Promise<T>;
     durationLogPath?: string | null;
-    createElementActions?: (selector: string, index: number | null) => Record<string, any>;
-    createElementState?: (selector: string, index: number | null) => Record<string, any>;
-    createElementAssertions?: (selector: string, index: number | null, state: Record<string, any>) => Record<string, any>;
-    createElementProxy?: (selector: string, index?: number | null) => any;
-    createCollectionProxy?: (selector: string) => any;
+    createElementActions?: (selector: string | ScopedSelector, index: number | null) => Record<string, any>;
+    createElementState?: (selector: string | ScopedSelector, index: number | null) => Record<string, any>;
+    createElementAssertions?: (selector: string | ScopedSelector, index: number | null, state: Record<string, any>) => Record<string, any>;
+    createElementProxy?: (selector: string | ScopedSelector, index?: number | null) => any;
+    createCollectionProxy?: (selector: string | ScopedSelector) => any;
     resolveTargetProxy?: (target: any) => any;
     buildSpectra?: () => any;
     cdpBridgeClass?: any;
@@ -96,31 +108,51 @@ export interface PlatformDriverBridge extends SpectraBrowserBridge {
     close(): Promise<void>;
     /** Navigates to target URL (Web) or Activity / Deep Link (Android). */
     navigate(targetUrl: string): Promise<void>;
-    click(selector: string, index?: number | null): Promise<void>;
-    doubleClick(selector: string, index?: number | null): Promise<void>;
-    rightClick(selector: string, index?: number | null): Promise<void>;
-    setValue(selector: string, value: unknown, index?: number | null): Promise<void>;
-    clearValue(selector: string, index?: number | null): Promise<void>;
-    select(selector: string, option: string, index?: number | null): Promise<void>;
-    hover(selector: string, index?: number | null): Promise<void>;
-    focus(selector: string, index?: number | null): Promise<void>;
-    dragDrop(sourceSelector: string, targetSelector: string, sourceIndex?: number | null): Promise<void>;
-    longPress(selector: string, duration: number, index?: number | null): Promise<void>;
-    scrollIntoView(selector: string, index?: number | null): Promise<void>;
-    getText(selector: string, index?: number | null): Promise<string>;
-    getValue(selector: string, index?: number | null): Promise<string>;
-    isDisplayed(selector: string, index?: number | null): Promise<boolean>;
-    isExisting(selector: string, index?: number | null): Promise<boolean>;
-    isEnabled(selector: string, index?: number | null): Promise<boolean>;
-    isSelected(selector: string, index?: number | null): Promise<boolean>;
-    isFocused(selector: string, index?: number | null): Promise<boolean>;
-    isClickable(selector: string, index?: number | null): Promise<boolean>;
-    hasClass(selector: string, className: string, index?: number | null): Promise<boolean>;
-    getAttribute(selector: string, name: string, index?: number | null): Promise<string | null>;
-    getCSSProperty(selector: string, name: string, index?: number | null): Promise<{
+    /** Navigates one step backward in browser/navigation history. */
+    back(): Promise<void>;
+    /** Navigates one step forward in browser/navigation history. */
+    forward(): Promise<void>;
+    /** Reloads / refreshes the current active page. */
+    refresh(): Promise<void>;
+    /** Sets the browser viewport dimensions (width and height in pixels). */
+    setViewport(width: number, height: number): Promise<void>;
+    /** Pauses execution for the given duration in milliseconds. */
+    pause(ms: number): Promise<void>;
+    /** Intercepts and mocks HTTP network requests matching the specified pattern or options. */
+    intercept(patternOrOptions: string | {
+        url: string;
+        method?: string;
+        response?: unknown;
+    }, method?: string, fixture?: unknown, options?: {
+        statusCode?: number;
+        headers?: Record<string, string>;
+        delayMs?: number;
+    }): Promise<MockInterceptHandle>;
+    click(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    doubleClick(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    rightClick(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    setValue(selector: string | ScopedSelector, value: unknown, index?: number | null): Promise<void>;
+    clearValue(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    select(selector: string | ScopedSelector, option: string, index?: number | null): Promise<void>;
+    hover(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    focus(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    dragDrop(sourceSelector: string | ScopedSelector, targetSelector: string, sourceIndex?: number | null): Promise<void>;
+    longPress(selector: string | ScopedSelector, duration: number, index?: number | null): Promise<void>;
+    scrollIntoView(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    getText(selector: string | ScopedSelector, index?: number | null): Promise<string>;
+    getValue(selector: string | ScopedSelector, index?: number | null): Promise<string>;
+    isDisplayed(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isExisting(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isEnabled(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isSelected(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isFocused(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isClickable(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    hasClass(selector: string | ScopedSelector, className: string, index?: number | null): Promise<boolean>;
+    getAttribute(selector: string | ScopedSelector, name: string, index?: number | null): Promise<string | null>;
+    getCSSProperty(selector: string | ScopedSelector, name: string, index?: number | null): Promise<{
         value: string;
     }>;
-    count(selector: string): Promise<number>;
+    count(selector: string | ScopedSelector): Promise<number>;
     pressKey(key: string | number): Promise<void>;
     scroll(options?: ScrollOptions): Promise<void>;
     swipe(options: SwipeOptions): Promise<void>;

package/dist/proto.d.ts

@@ -16,6 +16,14 @@ declare global {
      * Global step library injected by TestSpectra runner.
      */
     var Step: Record<string, any>;
+    /**
+     * Typed shape of `Spectra.env`. Empty by default — each `spectra.config.ts`
+     * `executionConfig.environmentVariables` key is merged in as a `readonly <KEY>: string` member
+     * by the CLI's generated `.testspectra/types/env.d.ts` (plain TypeScript interface merging, the
+     * same mechanism `@types/node` uses to let projects augment `NodeJS.ProcessEnv`).
+     */
+    interface SpectraEnv {
+    }
     namespace WebdriverIO {
         interface Browser extends SpectraBrowserBridge {
         }

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;
@@ -1296,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.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/matchers",
-  "version": "1.1.0-rc.0",
+  "version": "1.1.0-rc.1",
   "description": "Canonical TypeScript contracts and ambient type definitions for TestSpectra",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",