@testspectra/matchers 1.0.70 → 1.1.0

package/src/types.ts

@@ -3,49 +3,66 @@
  * @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";
+  | '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";
+  | '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)`.
@@ -57,26 +74,26 @@ export type AssertionKey =
  * ```
  */
 export type KeyOption =
-  | "Enter"
-  | "Tab"
-  | "Escape"
-  | "Backspace"
-  | "Delete"
-  | "ArrowUp"
-  | "ArrowDown"
-  | "ArrowLeft"
-  | "ArrowRight"
-  | "Space";
+  | '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
@@ -87,7 +104,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.
@@ -146,7 +163,7 @@ export interface ClickOptions {
   /** Optional inner text filter */
   text?: string;
   /** Click type: standard single click or double click */
-  clickType?: "single" | "double";
+  clickType?: 'single' | 'double';
 }
 
 /**
@@ -163,52 +180,1342 @@ export interface TypeOptions {
 }
 
 /**
- * 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";
-
-/**
- * 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");
- * ```
+  | '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';
+
+/**
+ * Canonical assertion matcher keys for multi-element collections.
+ * Dispatched internally by semantic collection methods (`.shouldHaveLength()`, `.shouldBeEmpty()`, etc.).
  */
 export type MultiElementMatcher =
-  | "have.length"
-  | "have.length.greaterThan"
-  | "be.empty"
-  | "exist";
+  | '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 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;
+}