@testspectra/matchers 1.0.69 → 1.1.0

package/dist/types.d.ts

@@ -2,12 +2,12 @@
  * Canonical action keys supported across TestSpectra runner and database models.
  * @see backend/src/models/test_step.rs
  */
-export type ActionKey = "navigate" | "click" | "type" | "clear" | "select" | "scroll" | "swipe" | "wait" | "waitForElement" | "pressKey" | "longPress" | "doubleClick" | "hover" | "dragDrop" | "back" | "refresh";
+export type ActionKey = 'navigate' | 'click' | 'type' | 'clear' | 'select' | 'scroll' | 'swipe' | 'wait' | 'waitForElement' | 'pressKey' | 'longPress' | 'doubleClick' | 'hover' | 'dragDrop' | 'back' | 'refresh';
 /**
  * Canonical assertion keys supported across TestSpectra runner and database models.
  * @see backend/src/models/test_step.rs
  */
-export type AssertionKey = "elementDisplayed" | "elementNotDisplayed" | "elementExists" | "elementEnabled" | "elementDisabled" | "textContains" | "textEquals" | "textNotContains" | "urlContains" | "urlEquals" | "valueEquals" | "valueContains" | "attributeEquals" | "attributeContains" | "hasClass" | "hasAttribute" | "isSelected" | "elementCount" | "elementCountGreaterThan" | "pageLoaded" | "noErrors";
+export type AssertionKey = 'elementDisplayed' | 'elementNotDisplayed' | 'elementExists' | 'elementNotExists' | 'elementClickable' | 'elementNotClickable' | 'elementEnabled' | 'elementDisabled' | 'elementChecked' | 'elementNotChecked' | 'elementFocused' | 'elementNotFocused' | 'textEquals' | 'textNotEquals' | 'textContains' | 'textNotContains' | 'valueEquals' | 'valueNotEquals' | 'valueContains' | 'valueNotContains' | 'attributeEquals' | 'attributeNotEquals' | 'hasClass' | 'notHasClass' | 'hasCss' | 'notHasCss' | 'collectionLengthEquals' | 'collectionLengthNotEquals' | 'collectionLengthGreaterThan' | 'collectionLengthLessThan' | 'collectionEmpty' | 'collectionNotEmpty' | 'urlEquals' | 'urlContains' | 'titleEquals' | 'titleContains' | 'pageLoaded' | 'noConsoleErrors';
 /**
  * Supported keyboard key names for `Spectra.pressKey(key)`.
  *
@@ -17,15 +17,15 @@ export type AssertionKey = "elementDisplayed" | "elementNotDisplayed" | "element
  * await Spectra.pressKey("Tab");
  * ```
  */
-export type KeyOption = "Enter" | "Tab" | "Escape" | "Backspace" | "Delete" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Space";
+export type KeyOption = 'Enter' | 'Tab' | 'Escape' | 'Backspace' | 'Delete' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Space';
 /**
  * Cardinal directions for gestures such as swipe and scroll.
  */
-export type Direction = "up" | "down" | "left" | "right";
+export type Direction = 'up' | 'down' | 'left' | 'right';
 /**
  * Target reference for locating an element.
- * Can be a CSS/XPath selector string, a resolved `WebdriverIO.Element`,
- * or a chainable element promise `ChainablePromiseElement`.
+ * Can be a CSS/XPath selector string, a resolved `SpectraElement` proxy,
+ * or a chainable element promise `Promise<SpectraElement>`.
  *
  * @example
  * ```ts
@@ -36,7 +36,7 @@ export type Direction = "up" | "down" | "left" | "right";
  * Spectra.get(LoginPage.submitButton);
  * ```
  */
-export type ElementTarget = string | WebdriverIO.Element | ChainablePromiseElement;
+export type ElementTarget = string | SingleElementProxy | Promise<SingleElementProxy>;
 /**
  * Configuration options for scroll actions.
  *
@@ -91,7 +91,7 @@ export interface ClickOptions {
     /** Optional inner text filter */
     text?: string;
     /** Click type: standard single click or double click */
-    clickType?: "single" | "double";
+    clickType?: 'single' | 'double';
 }
 /**
  * Configuration options for typing input into form elements.
@@ -106,26 +106,1193 @@ export interface TypeOptions {
     clearFirst?: boolean;
 }
 /**
- * Fluent assertion matcher strings for single element verification.
- * Used in `Spectra.get(target).should(matcher, ...args)`.
- *
- * @example
- * ```ts
- * await Spectra.get("#username").should("be.visible");
- * await Spectra.get("#greeting").should("have.text", "Welcome back");
- * await Spectra.get("#status").should("have.class", "active");
- * ```
+ * Canonical assertion matcher keys for single element verification.
+ * Dispatched internally by semantic receiver methods (`.shouldBeVisible()`, `.shouldHaveText()`, etc.).
  */
-export type SingleElementMatcher = "be.visible" | "not.be.visible" | "exist" | "not.exist" | "be.enabled" | "be.disabled" | "be.checked" | "not.be.checked" | "be.selected" | "not.be.selected" | "have.value" | "contain.value" | "have.text" | "contain.text" | "have.class" | "have.attr" | "have.url" | "contain.url" | "have.title" | "contain.title";
+export type SingleElementMatcher = 'be.visible' | 'not.be.visible' | 'exist' | 'not.exist' | 'be.clickable' | 'not.be.clickable' | 'be.enabled' | 'be.disabled' | 'be.checked' | 'not.be.checked' | 'be.selected' | 'not.be.selected' | 'be.focused' | 'not.be.focused' | 'have.value' | 'not.have.value' | 'contain.value' | 'not.contain.value' | 'have.text' | 'not.have.text' | 'contain.text' | 'not.contain.text' | 'have.class' | 'not.have.class' | 'have.attr' | 'not.have.attr' | 'have.css' | 'not.have.css' | 'have.url' | 'contain.url' | 'have.title' | 'contain.title';
 /**
- * Fluent assertion matcher strings for multi-element collections.
- * Used in `Spectra.getAll(selector).should(matcher, ...args)`.
- *
- * @example
- * ```ts
- * await Spectra.getAll(".product-item").should("have.length", 4);
- * await Spectra.getAll(".product-item").should("have.length.greaterThan", 0);
- * await Spectra.getAll(".badge").should("not.be.empty");
- * ```
+ * Canonical assertion matcher keys for multi-element collections.
+ * Dispatched internally by semantic collection methods (`.shouldHaveLength()`, `.shouldBeEmpty()`, etc.).
+ */
+export type MultiElementMatcher = 'have.length' | 'not.have.length' | 'have.length.greaterThan' | 'have.length.lessThan' | 'be.empty' | 'not.be.empty' | 'exist';
+/**
+ * Receiver-oriented element assertion methods.
+ * Attached directly to SingleElementProxy instances.
+ */
+export interface ElementReceiverAssertions<TReturn = Promise<void>> {
+    /**
+     * Asserts that the target element is visible and displayed on the page.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#submit-btn').shouldBeVisible();
+     * await LoginPage.submitButton.shouldBeVisible();
+     * ```
+     */
+    shouldBeVisible(): TReturn;
+    /**
+     * Asserts that the target element is hidden, detached, or not displayed on the page.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('.loading-spinner').shouldNotBeVisible();
+     * ```
+     */
+    shouldNotBeVisible(): TReturn;
+    /**
+     * Asserts that the target element exists in the DOM.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#cookie-consent-modal').shouldExist();
+     * ```
+     */
+    shouldExist(): TReturn;
+    /**
+     * Asserts that the target element does not exist in the DOM.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#deleted-record-row').shouldNotExist();
+     * ```
+     */
+    shouldNotExist(): TReturn;
+    /**
+     * Asserts that the target element is visible, enabled, and clickable.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('button[type="submit"]').shouldBeClickable();
+     * ```
+     */
+    shouldBeClickable(): TReturn;
+    /**
+     * Asserts that the target element is disabled, covered, or not clickable.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('button.disabled-action').shouldNotBeClickable();
+     * ```
+     */
+    shouldNotBeClickable(): TReturn;
+    /**
+     * Asserts that the target form input/button is enabled (not disabled).
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#username-field').shouldBeEnabled();
+     * ```
+     */
+    shouldBeEnabled(): TReturn;
+    /**
+     * Asserts that the target form input/button has the disabled state/attribute.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#submit-order-btn').shouldBeDisabled();
+     * ```
+     */
+    shouldBeDisabled(): TReturn;
+    /**
+     * Asserts that the target checkbox or radio input is checked/selected.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#terms-checkbox').shouldBeChecked();
+     * ```
+     */
+    shouldBeChecked(): TReturn;
+    /**
+     * Asserts that the target checkbox or radio input is unchecked/deselected.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#subscribe-newsletter').shouldNotBeChecked();
+     * ```
+     */
+    shouldNotBeChecked(): TReturn;
+    /**
+     * Asserts that the target element currently holds active document focus.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#search-input').shouldBeFocused();
+     * ```
+     */
+    shouldBeFocused(): TReturn;
+    /**
+     * Asserts that the target element does not hold active document focus.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#blur-input').shouldNotBeFocused();
+     * ```
+     */
+    shouldNotBeFocused(): TReturn;
+    /**
+     * Asserts that the target element's text content matches the expected string or regular expression.
+     *
+     * @param expected Exact string or RegExp pattern to match against element text.
+     * @example
+     * ```ts
+     * await Spectra.get('h1.page-title').shouldHaveText('Dashboard Overview');
+     * await Spectra.get('.badge').shouldHaveText(/Active|Pending/);
+     * ```
+     */
+    shouldHaveText(expected: string | RegExp): TReturn;
+    /**
+     * Asserts that the target element's text content does not match the expected string or regular expression.
+     *
+     * @param expected String or RegExp pattern that the element text must NOT match.
+     * @example
+     * ```ts
+     * await Spectra.get('.status-label').shouldNotHaveText('Error');
+     * ```
+     */
+    shouldNotHaveText(expected: string | RegExp): TReturn;
+    /**
+     * Asserts that the target element's text content contains the specified substring.
+     *
+     * @param substring Substring expected to be present within the element text.
+     * @example
+     * ```ts
+     * await Spectra.get('.toast-message').shouldContainText('Successfully saved');
+     * ```
+     */
+    shouldContainText(substring: string): TReturn;
+    /**
+     * Asserts that the target element's text content does not contain the specified substring.
+     *
+     * @param substring Substring that must NOT be present within the element text.
+     * @example
+     * ```ts
+     * await Spectra.get('.log-output').shouldNotContainText('Fatal Exception');
+     * ```
+     */
+    shouldNotContainText(substring: string): TReturn;
+    /**
+     * Asserts that the form input or textarea element's value exactly equals the specified string.
+     *
+     * @param value Expected input field value.
+     * @example
+     * ```ts
+     * await Spectra.get('input[name="email"]').shouldHaveValue('admin@testspectra.dev');
+     * ```
+     */
+    shouldHaveValue(value: string): TReturn;
+    /**
+     * Asserts that the form input or textarea element's value does not equal the specified string.
+     *
+     * @param value Value that the input field must NOT equal.
+     * @example
+     * ```ts
+     * await Spectra.get('input[name="role"]').shouldNotHaveValue('guest');
+     * ```
+     */
+    shouldNotHaveValue(value: string): TReturn;
+    /**
+     * Asserts that the form input or textarea element's value contains the specified substring.
+     *
+     * @param substring Substring expected to be contained within the input value.
+     * @example
+     * ```ts
+     * await Spectra.get('input[name="email"]').shouldContainValue('@testspectra.dev');
+     * ```
+     */
+    shouldContainValue(substring: string): TReturn;
+    /**
+     * Asserts that the form input or textarea element's value does not contain the specified substring.
+     *
+     * @param substring Substring that must NOT be contained within the input value.
+     * @example
+     * ```ts
+     * await Spectra.get('input[name="url"]').shouldNotContainValue('http://');
+     * ```
+     */
+    shouldNotContainValue(substring: string): TReturn;
+    /**
+     * Asserts that the element has the specified attribute, and optionally that its value matches.
+     *
+     * @param name Attribute name to inspect.
+     * @param value Optional expected attribute value string.
+     * @example
+     * ```ts
+     * await Spectra.get('a.external-link').shouldHaveAttribute('target', '_blank');
+     * await Spectra.get('input.required-field').shouldHaveAttribute('required');
+     * ```
+     */
+    shouldHaveAttribute(name: string, value?: string): TReturn;
+    /**
+     * Asserts that the element does not have the specified attribute.
+     *
+     * @param name Attribute name that must NOT exist on the element.
+     * @example
+     * ```ts
+     * await Spectra.get('button#action-btn').shouldNotHaveAttribute('disabled');
+     * ```
+     */
+    shouldNotHaveAttribute(name: string): TReturn;
+    /**
+     * Asserts that the element contains the specified CSS class name.
+     *
+     * @param className CSS class name expected in the element's classList.
+     * @example
+     * ```ts
+     * await Spectra.get('.nav-tab').shouldHaveClass('active');
+     * ```
+     */
+    shouldHaveClass(className: string): TReturn;
+    /**
+     * Asserts that the element does not contain the specified CSS class name.
+     *
+     * @param className CSS class name that must NOT be in the element's classList.
+     * @example
+     * ```ts
+     * await Spectra.get('.modal-backdrop').shouldNotHaveClass('hidden');
+     * ```
+     */
+    shouldNotHaveClass(className: string): TReturn;
+    /**
+     * Asserts that the computed CSS style property of the element equals the specified value.
+     *
+     * @param property CSS style property name (e.g. 'color', 'display', 'opacity').
+     * @param value Expected computed CSS property value.
+     * @example
+     * ```ts
+     * await Spectra.get('.badge-success').shouldHaveCss('color', 'rgb(0, 128, 0)');
+     * ```
+     */
+    shouldHaveCss(property: string, value: string): TReturn;
+    /**
+     * Asserts that the computed CSS style property of the element does not equal the specified value.
+     *
+     * @param property CSS style property name.
+     * @param value Value that the computed CSS property must NOT equal.
+     * @example
+     * ```ts
+     * await Spectra.get('.main-content').shouldNotHaveCss('display', 'none');
+     * ```
+     */
+    shouldNotHaveCss(property: string, value: string): TReturn;
+}
+/**
+ * Receiver-oriented collection assertion methods.
+ * Attached directly to CollectionProxy and collection prototypes.
+ */
+export interface CollectionReceiverAssertions<TReturn = Promise<void>> {
+    /**
+     * Asserts that the collection contains exactly the specified number of matching elements.
+     *
+     * @param count Expected exact count of elements.
+     * @example
+     * ```ts
+     * await Spectra.getAll('.user-table-row').shouldHaveLength(10);
+     * ```
+     */
+    shouldHaveLength(count: number): TReturn;
+    /**
+     * Asserts that the collection does not contain the specified number of matching elements.
+     *
+     * @param count Count that the element collection must NOT equal.
+     * @example
+     * ```ts
+     * await Spectra.getAll('.error-item').shouldNotHaveLength(0);
+     * ```
+     */
+    shouldNotHaveLength(count: number): TReturn;
+    /**
+     * Asserts that the collection contains strictly more than `min` matching elements.
+     *
+     * @param min Minimum threshold (exclusive).
+     * @example
+     * ```ts
+     * await Spectra.getAll('.search-result-card').shouldHaveLengthGreaterThan(0);
+     * ```
+     */
+    shouldHaveLengthGreaterThan(min: number): TReturn;
+    /**
+     * Asserts that the collection contains strictly fewer than `max` matching elements.
+     *
+     * @param max Maximum threshold (exclusive).
+     * @example
+     * ```ts
+     * await Spectra.getAll('.warning-banner').shouldHaveLengthLessThan(5);
+     * ```
+     */
+    shouldHaveLengthLessThan(max: number): TReturn;
+    /**
+     * Asserts that the collection contains zero matching elements.
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll('.unread-notification-badge').shouldBeEmpty();
+     * ```
+     */
+    shouldBeEmpty(): TReturn;
+    /**
+     * Asserts that the collection contains at least one matching element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll('.product-card').shouldNotBeEmpty();
+     * ```
+     */
+    shouldNotBeEmpty(): TReturn;
+}
+/**
+ * Browser-level context assertion methods.
+ * Hosted on Spectra.browser and the global browser object.
+ */
+export interface BrowserReceiverAssertions {
+    /**
+     * Asserts that current browser URL exactly matches the expected URL.
+     *
+     * @param expectedUrl Full expected URL string.
+     * @example
+     * ```ts
+     * await Spectra.browser.shouldHaveUrl('https://app.testspectra.dev/dashboard');
+     * ```
+     */
+    shouldHaveUrl(expectedUrl: string): Promise<void>;
+    /**
+     * Asserts that current browser URL contains the specified substring.
+     *
+     * @param expectedSubstr Substring expected in browser URL.
+     * @example
+     * ```ts
+     * await Spectra.browser.shouldContainUrl('/dashboard');
+     * ```
+     */
+    shouldContainUrl(expectedSubstr: string): Promise<void>;
+    /**
+     * Asserts that current page title exactly matches the expected title.
+     *
+     * @param expectedTitle Full expected page title string.
+     * @example
+     * ```ts
+     * await Spectra.browser.shouldHaveTitle('Dashboard - TestSpectra');
+     * ```
+     */
+    shouldHaveTitle(expectedTitle: string): Promise<void>;
+    /**
+     * Asserts that current page title contains the specified substring.
+     *
+     * @param expectedSubstr Substring expected in page title.
+     * @example
+     * ```ts
+     * await Spectra.browser.shouldContainTitle('Dashboard');
+     * ```
+     */
+    shouldContainTitle(expectedSubstr: string): Promise<void>;
+    /**
+     * Asserts that the browser document `readyState` is 'complete' or 'interactive'.
+     *
+     * @example
+     * ```ts
+     * await Spectra.browser.shouldBeLoaded();
+     * ```
+     */
+    shouldBeLoaded(): Promise<void>;
+    /**
+     * Asserts that no severe or unhandled JavaScript errors occurred in the browser console.
+     *
+     * @example
+     * ```ts
+     * await Spectra.browser.shouldHaveNoConsoleErrors();
+     * ```
+     */
+    shouldHaveNoConsoleErrors(): Promise<void>;
+    /**
+     * Clears all browser cookies for the active domain.
+     *
+     * @example
+     * ```ts
+     * await Spectra.browser.clearCookies();
+     * ```
+     */
+    clearCookies(): Promise<void>;
+    /**
+     * Clears all key-value entries in browser `localStorage`.
+     *
+     * @example
+     * ```ts
+     * await Spectra.browser.clearLocalStorage();
+     * ```
+     */
+    clearLocalStorage(): Promise<void>;
+}
+/**
+ * Native proxy interface for interacting with a single DOM / UI element.
+ */
+export interface SingleElementProxy extends ElementReceiverAssertions<Promise<void>> {
+    /** Target CSS or XPath selector string for this element. */
+    selector: string;
+    /** Positional index when matched from a collection (or null for standalone selectors). */
+    index: number | null;
+    /**
+     * Waits until the element exists in the DOM within the specified timeout.
+     *
+     * @param timeoutMs Timeout in milliseconds (default: 5000ms).
+     */
+    waitForElement(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Clicks on the element.
+     *
+     * @param options Optional click interaction options.
+     * @example
+     * ```ts
+     * await Spectra.get('#submit-btn').click();
+     * ```
+     */
+    click(options?: ClickOptions): Promise<void>;
+    /**
+     * Performs a double-click interaction on the element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('.editable-cell').doubleClick();
+     * ```
+     */
+    doubleClick(): Promise<void>;
+    /**
+     * Performs a context-click (right-click) on the element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('.file-item').rightClick();
+     * ```
+     */
+    rightClick(): Promise<void>;
+    /**
+     * Sets or replaces the value of a form input element.
+     *
+     * @param value Text value to set.
+     * @example
+     * ```ts
+     * await Spectra.get('#username').setValue('admin');
+     * ```
+     */
+    setValue(value: unknown): Promise<void>;
+    /**
+     * Types text keystrokes into the element, optionally clearing existing content first.
+     *
+     * @param value Text string to type.
+     * @param options Optional type options (e.g. `{ clearFirst: true }`).
+     * @example
+     * ```ts
+     * await LoginPage.emailInput.type('admin@testspectra.dev', { clearFirst: true });
+     * ```
+     */
+    type(value: unknown, options?: TypeOptions): Promise<void>;
+    /**
+     * Clears the current text value from an input or textarea element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#search-bar').clearValue();
+     * ```
+     */
+    clearValue(): Promise<void>;
+    /**
+     * Clears the current text value from an input or textarea element (alias to `clearValue()`).
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#search-bar').clear();
+     * ```
+     */
+    clear(): Promise<void>;
+    /**
+     * Selects an option in a `<select>` element by its visible text or value.
+     *
+     * @param option Visible text or value of the option to select.
+     * @example
+     * ```ts
+     * await Spectra.get('#country-dropdown').select('Indonesia');
+     * ```
+     */
+    select(option: string): Promise<void>;
+    /**
+     * Selects an option in a `<select>` dropdown by its visible text.
+     *
+     * @param text Visible text label of the option.
+     */
+    selectByVisibleText(text: string): Promise<void>;
+    /**
+     * Hovers the mouse cursor over the center of the element.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('.dropdown-trigger').hover();
+     * ```
+     */
+    hover(): Promise<void>;
+    /**
+     * Focuses the target element (triggers focus event and active document focus).
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#email-input').focus();
+     * ```
+     */
+    focus(): Promise<void>;
+    /**
+     * Moves the mouse cursor to the element (alias to `hover()`).
+     */
+    moveTo(): Promise<void>;
+    /**
+     * Drags this element and drops it onto the target element destination.
+     *
+     * @param target Destination element target selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.get('#drag-source').dragDrop('#drop-zone');
+     * ```
+     */
+    dragDrop(target: ElementTarget): Promise<void>;
+    /**
+     * Drags this element and drops it onto the target element destination (alias to `dragDrop()`).
+     */
+    dragAndDrop(target: ElementTarget): Promise<void>;
+    /**
+     * Scrolls the page until this element is aligned into the visible viewport.
+     *
+     * @example
+     * ```ts
+     * await Spectra.get('#footer-links').scrollIntoView();
+     * ```
+     */
+    scrollIntoView(): Promise<void>;
+    /**
+     * Long-presses on the element for touch/mobile gestures.
+     *
+     * @param options Long-press duration in milliseconds or configuration object.
+     * @example
+     * ```ts
+     * await Spectra.get('.draggable-card').longPress({ duration: 1500 });
+     * ```
+     */
+    longPress(options?: number | LongPressOptions): Promise<void>;
+    /**
+     * Waits until the element is displayed and visible in the viewport.
+     *
+     * @param opts Optional timeout configuration object.
+     */
+    waitForDisplayed(opts?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
+     * Returns the inner text content of the element.
+     *
+     * @example
+     * ```ts
+     * const headingText = await Spectra.get('h1').getText();
+     * ```
+     */
+    getText(): Promise<string>;
+    /**
+     * Returns the current `value` property of an input or textarea element.
+     *
+     * @example
+     * ```ts
+     * const query = await Spectra.get('input#search').getValue();
+     * ```
+     */
+    getValue(): Promise<string>;
+    /**
+     * Returns true if the element is currently visible and rendered in the DOM.
+     */
+    isDisplayed(): Promise<boolean>;
+    /**
+     * Returns true if the element is currently visible (alias to `isDisplayed()`).
+     */
+    isVisible(): Promise<boolean>;
+    /**
+     * Returns true if the element exists in the DOM.
+     */
+    isExisting(): Promise<boolean>;
+    /**
+     * Returns true if the element is enabled (not disabled).
+     */
+    isEnabled(): Promise<boolean>;
+    /**
+     * Returns true if the checkbox, radio, or `<option>` is selected.
+     */
+    isSelected(): Promise<boolean>;
+    /**
+     * Returns true if the checkbox or radio button is checked.
+     */
+    isChecked(): Promise<boolean>;
+    /**
+     * Returns true if the element is the active focused element in document.
+     */
+    isFocused(): Promise<boolean>;
+    /**
+     * Retrieves the value of a specified HTML attribute from the element.
+     *
+     * @param name Attribute name (e.g. 'href', 'src', 'data-id').
+     * @example
+     * ```ts
+     * const linkUrl = await Spectra.get('a#download').getAttribute('href');
+     * ```
+     */
+    getAttribute(name: string): Promise<string | null>;
+    /**
+     * Retrieves the computed CSS property value of the element.
+     *
+     * @param name CSS property name (e.g. 'background-color', 'font-size').
+     * @example
+     * ```ts
+     * const color = await Spectra.get('.btn-primary').getCSSProperty('background-color');
+     * ```
+     */
+    getCSSProperty(name: string): Promise<{
+        value: string;
+    }>;
+}
+/**
+ * TestSpectra native element interface alias.
+ */
+export type SpectraElement = SingleElementProxy;
+/**
+ * Native proxy interface for interacting with multiple matching elements in a collection.
+ */
+export interface CollectionProxy extends CollectionReceiverAssertions<Promise<void>> {
+    /** Target CSS or XPath selector string for this collection. */
+    selector: string;
+    /**
+     * Returns the total count of elements matching this collection selector.
+     *
+     * @example
+     * ```ts
+     * const totalRows = await Spectra.getAll('.table-row').count();
+     * ```
+     */
+    count(): Promise<number>;
+    /**
+     * Total count of elements matching this collection selector (Promise).
+     */
+    readonly length: Promise<number>;
+    /**
+     * Returns a `SingleElementProxy` pointing to the first matching element in the collection (index 0).
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll('.list-item').first().click();
+     * ```
+     */
+    first(): SingleElementProxy;
+    /**
+     * Returns a `SingleElementProxy` pointing to the last matching element in the collection.
+     *
+     * @example
+     * ```ts
+     * await Spectra.getAll('.list-item').last().click();
+     * ```
+     */
+    last(): SingleElementProxy;
+    /**
+     * Returns a `SingleElementProxy` pointing to the matching element at the specified zero-based index.
+     *
+     * @param index Zero-based index of the target element.
+     * @example
+     * ```ts
+     * await Spectra.getAll('.list-item').nth(2).click();
+     * ```
+     */
+    nth(index: number): SingleElementProxy;
+}
+/**
+ * TestSpectra native collection interface alias.
+ */
+export type SpectraCollection = CollectionProxy;
+/**
+ * Native browser bridge interface for page navigation, execution, and network interception.
+ */
+export interface SpectraBrowserBridge extends BrowserReceiverAssertions {
+    /**
+     * Navigates the browser to the specified absolute or relative URL.
+     *
+     * @param targetUrl Target destination URL.
+     * @example
+     * ```ts
+     * await Spectra.browser.url('/auth/login');
+     * ```
+     */
+    url(targetUrl: string): Promise<void>;
+    /**
+     * Retrieves the current browser URL.
+     *
+     * @example
+     * ```ts
+     * const currentUrl = await Spectra.browser.getUrl();
+     * ```
+     */
+    getUrl(): Promise<string>;
+    /**
+     * Retrieves the current page title.
+     *
+     * @example
+     * ```ts
+     * const title = await Spectra.browser.getTitle();
+     * ```
+     */
+    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.
+     *
+     * @param fn Function or script string to execute.
+     * @param args Arguments to pass into the function.
+     * @example
+     * ```ts
+     * const docWidth = await Spectra.browser.execute(() => document.body.clientWidth);
+     * ```
+     */
+    execute<R = unknown>(fn: ((...args: unknown[]) => R) | string, ...args: unknown[]): Promise<R>;
+    /**
+     * Evaluates a JavaScript expression string in the browser context.
+     *
+     * @param expr JavaScript expression string.
+     * @example
+     * ```ts
+     * const isReady = await Spectra.browser.evaluate('document.readyState === "complete"');
+     * ```
+     */
+    evaluate<R = unknown>(expr: string): Promise<R>;
+    /**
+     * Repeatedly polls a condition function until it returns true or times out.
+     *
+     * @param fn Condition function returning a boolean or boolean promise.
+     * @param opts Optional timeout and message options.
+     * @example
+     * ```ts
+     * await Spectra.browser.waitUntil(async () => (await Spectra.get('#status').getText()) === 'Ready', {
+     *   timeout: 5000,
+     *   timeoutMsg: 'Status never reached Ready',
+     * });
+     * ```
+     */
+    waitUntil(fn: () => Promise<boolean> | boolean, opts?: {
+        timeout?: number;
+        timeoutMsg?: string;
+    }): Promise<boolean>;
+    /**
+     * Retrieves captured browser console log entries.
+     *
+     * @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>;
+}
+/**
+ * Mock rule configuration for CDP network request interception.
  */
-export type MultiElementMatcher = "have.length" | "have.length.greaterThan" | "be.empty" | "exist";
+export interface MockRule {
+    /** URL pattern or substring to match. */
+    pattern: string;
+    /** HTTP method (e.g. GET, POST). */
+    method: string;
+    /** Mock response payload. */
+    response: unknown;
+    /** HTTP status code (e.g. 200, 404). */
+    statusCode: number;
+    /** Custom HTTP response headers. */
+    headers?: Record<string, string>;
+    /** Total times this mock rule matched and intercepted requests. */
+    callCount: number;
+}
+/**
+ * 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.
+     *
+     * @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>;
+    }) => Promise<void>;
+    /**
+     * Returns the number of times this mock intercepted network requests.
+     */
+    callCount: () => number;
+}
+/**
+ * Audit log entry for captured CDP network requests.
+ */
+export interface CDPNetworkEntry {
+    /** Unique CDP request ID. */
+    requestId: string;
+    /** Target request URL. */
+    url: string;
+    /** HTTP request method. */
+    method: string;
+    /** Resource type (e.g. 'Fetch', 'XHR', 'Document', 'Stylesheet'). */
+    type: string;
+    /** HTTP response status code. */
+    status: number;
+    /** HTTP response status message. */
+    statusText: string;
+    /** Host domain name. */
+    domain: string;
+    /** Protocol name (e.g. 'h2', 'http/1.1'). */
+    protocol: string;
+    /** Request timing metrics in milliseconds. */
+    timing: {
+        waiting: number;
+        download: number;
+    };
+    /** Content body size in bytes. */
+    size: number;
+    /** Wire transfer size in bytes. */
+    transferSize: number;
+    /** Start timestamp epoch. */
+    startTime: number;
+}
+/**
+ * Main TestSpectra cross-platform automation and assertion interface contract.
+ */
+export interface SpectraStatic {
+    /**
+     * Locates a single DOM / UI element proxy by selector or target reference.
+     *
+     * @param target CSS selector string, XPath string, or element proxy.
+     * @example
+     * ```ts
+     * const submitBtn = Spectra.get('#btn-submit');
+     * await submitBtn.click();
+     * ```
+     */
+    get(target: ElementTarget): SingleElementProxy;
+    /**
+     * Locates a collection proxy of multiple matching DOM / UI elements by selector.
+     *
+     * @param selector CSS or XPath selector matching multiple elements.
+     * @example
+     * ```ts
+     * const rows = Spectra.getAll('table tr');
+     * await rows.shouldHaveLength(5);
+     * ```
+     */
+    getAll(selector: string): CollectionProxy;
+    /**
+     * Navigates the active browser window or mobile webview to the specified URL.
+     *
+     * @param url Absolute or relative URL destination.
+     * @example
+     * ```ts
+     * await Spectra.navigate('/dashboard');
+     * ```
+     */
+    navigate(url: string): Promise<void>;
+    /**
+     * Navigates one step backward in browser history.
+     *
+     * @example
+     * ```ts
+     * await Spectra.back();
+     * ```
+     */
+    back(): Promise<void>;
+    /**
+     * Navigates one step forward in browser history.
+     *
+     * @example
+     * ```ts
+     * await Spectra.forward();
+     * ```
+     */
+    forward(): Promise<void>;
+    /**
+     * Reloads / refreshes the current active page.
+     *
+     * @example
+     * ```ts
+     * await Spectra.refresh();
+     * ```
+     */
+    refresh(): 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.setViewport(1920, 1080);
+     * ```
+     */
+    setViewport(width: number, height: number): Promise<void>;
+    /**
+     * Clicks on the specified element target.
+     *
+     * @param target Element selector string, Page Object element, or proxy.
+     * @param textOrOptions Optional text filter or click options.
+     * @example
+     * ```ts
+     * await Spectra.click('#submit-btn');
+     * await Spectra.click(LoginPage.submitButton);
+     * ```
+     */
+    click(target: ElementTarget, textOrOptions?: string | ClickOptions): Promise<void>;
+    /**
+     * Performs a double-click interaction on the specified element target.
+     *
+     * @param target Target element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.doubleClick('.grid-cell');
+     * ```
+     */
+    doubleClick(target: ElementTarget): Promise<void>;
+    /**
+     * Performs a context-click (right-click) interaction on the specified element target.
+     *
+     * @param target Target element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.rightClick('#context-menu-area');
+     * ```
+     */
+    rightClick(target: ElementTarget): Promise<void>;
+    /**
+     * Types text keystrokes into the specified element target.
+     *
+     * @param target Target input or textarea element selector or proxy.
+     * @param text String content to type.
+     * @param options Optional typing configuration (e.g. `{ clearFirst: true }`).
+     * @example
+     * ```ts
+     * await Spectra.type('#username', 'john_doe', { clearFirst: true });
+     * ```
+     */
+    type(target: ElementTarget, text: string, options?: TypeOptions): Promise<void>;
+    /**
+     * Clears the current text value from an input or textarea element.
+     *
+     * @param target Target element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.clear('#search-input');
+     * ```
+     */
+    clear(target: ElementTarget): Promise<void>;
+    /**
+     * Selects an option in a `<select>` dropdown by its visible text or value.
+     *
+     * @param target Target select element selector or proxy.
+     * @param option Visible text label or value of the option.
+     * @example
+     * ```ts
+     * await Spectra.select('#country-dropdown', 'United States');
+     * ```
+     */
+    select(target: ElementTarget, option: string): Promise<void>;
+    /**
+     * Hovers the mouse cursor over the specified element target.
+     *
+     * @param target Target element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.hover('.profile-menu-trigger');
+     * ```
+     */
+    hover(target: ElementTarget): Promise<void>;
+    /**
+     * Focuses the target element (triggers focus event and active document focus).
+     *
+     * @param target Target element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.focus('#email-input');
+     * ```
+     */
+    focus(target: ElementTarget): Promise<void>;
+    /**
+     * Drags a source element and drops it onto a destination element target.
+     *
+     * @param source Draggable source element selector or proxy.
+     * @param destination Drop zone destination element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.dragDrop('#item-1', '#kanban-column-done');
+     * ```
+     */
+    dragDrop(source: ElementTarget, destination: ElementTarget): Promise<void>;
+    /**
+     * Scrolls the page until the specified element is aligned into the visible viewport.
+     *
+     * @param target Target element selector or proxy.
+     * @example
+     * ```ts
+     * await Spectra.scrollIntoView('#footer-contact');
+     * ```
+     */
+    scrollIntoView(target: ElementTarget): Promise<void>;
+    /**
+     * Performs a directional scroll on the page.
+     *
+     * @param options Scroll options (direction, pixel distance, or target selector).
+     * @example
+     * ```ts
+     * await Spectra.scroll({ direction: 'down', pixels: 400 });
+     * ```
+     */
+    scroll(options?: ScrollOptions): Promise<void>;
+    /**
+     * Performs a directional touch swipe gesture (mobile & web).
+     *
+     * @param options Swipe options (direction, distance in pixels, anchor selector).
+     * @example
+     * ```ts
+     * await Spectra.swipe({ direction: 'left', distance: 300 });
+     * ```
+     */
+    swipe(options: SwipeOptions): Promise<void>;
+    /**
+     * Performs a long-press touch gesture on the target element.
+     *
+     * @param target Target element selector or proxy.
+     * @param options Long-press duration in milliseconds or configuration object.
+     * @example
+     * ```ts
+     * await Spectra.longPress('#sortable-item', { duration: 1500 });
+     * ```
+     */
+    longPress(target: ElementTarget, options?: LongPressOptions | number): Promise<void>;
+    /**
+     * Presses a specific keyboard key into the active document element.
+     *
+     * @param key Key name to press (e.g. 'Enter', 'Tab', 'Escape', 'Backspace').
+     * @example
+     * ```ts
+     * await Spectra.pressKey('Enter');
+     * ```
+     */
+    pressKey(key: KeyOption | string): Promise<void>;
+    /**
+     * Pauses test execution for the specified number of milliseconds.
+     *
+     * @param ms Milliseconds to wait.
+     * @example
+     * ```ts
+     * await Spectra.wait(1000);
+     * ```
+     */
+    wait(ms: number): Promise<void>;
+    /**
+     * Waits for the specified element to appear and exist in the DOM.
+     *
+     * @param target Target element selector or proxy.
+     * @param timeoutMs Maximum time to wait in milliseconds (default: 5000ms).
+     * @example
+     * ```ts
+     * await Spectra.waitForElement('#dynamic-content', 10000);
+     * ```
+     */
+    waitForElement(target: ElementTarget, timeoutMs?: number): Promise<void>;
+    /**
+     * Direct access to browser context commands and page assertions.
+     */
+    browser: SpectraBrowserBridge;
+    /**
+     * Intercepts and mocks HTTP network requests matching the specified pattern or options.
+     *
+     * @param patternOrOptions URL pattern string or structured intercept configuration object.
+     * @param method HTTP method (GET, POST, etc.) when pattern string is used.
+     * @param fixture Mock response payload.
+     * @param options Additional response options (status code, custom headers).
+     * @example
+     * ```ts
+     * const mock = await Spectra.intercept('/api/v1/profile', 'GET', { name: 'Admin', role: 'root' });
+     * ```
+     */
+    intercept(patternOrOptions: string | {
+        url: string;
+        method?: string;
+        response?: unknown;
+    }, method?: string, fixture?: unknown, options?: {
+        statusCode?: number;
+        headers?: Record<string, string>;
+    }): Promise<MockInterceptHandle>;
+    /**
+     * Clears and resets all active CDP network interception rules.
+     *
+     * @example
+     * ```ts
+     * Spectra.clearMocks();
+     * ```
+     */
+    clearMocks(): void;
+}