@testspectra/matchers 1.0.70 → 1.1.0

package/dist/runner/single.js

@@ -1,31 +1,46 @@
-import { executeSingleMatcher, resolveElement } from "../matchers.js";
+import { executeSingleMatcher, resolveElement } from '../matchers.js';
+import { trackCommand } from '../reporter.js';
+function getRawTarget(target) {
+    if (!target)
+        return '';
+    if (typeof target === 'string')
+        return target;
+    if (target.selector)
+        return target.selector;
+    if (target.constructor && target.constructor.name && target.constructor.name !== 'Object')
+        return target.constructor.name;
+    return String(target);
+}
 /**
  * Fluent interaction and assertion runner for a single element or browser context.
  *
- * Implements `PromiseLike<void>`, allowing it to be awaited directly or chained with
- * multiple actions and `.should(...)` assertions.
+ * Implements `PromiseLike<void>` and `ElementReceiverAssertions<SingleElementRunner>`,
+ * allowing it to be awaited directly or chained with multiple actions and direct `.should...` assertions.
  *
  * @example
  * ```ts
  * // Direct action + chained assertion
  * await Spectra.get("#submit-btn")
  *   .click()
- *   .should("not.be.visible");
+ *   .shouldNotBeVisible();
  *
  * // Query + multiple assertions
  * await Spectra.get(LoginPage.usernameInput)
- *   .should("be.visible")
- *   .should("be.enabled")
- *   .should("have.value", "admin");
+ *   .shouldBeVisible()
+ *   .shouldBeEnabled()
+ *   .shouldHaveValue("admin");
  * ```
  */
 export class SingleElementRunner {
     _target;
     _action = null;
+    _actionPayload = null;
     _assertions = [];
-    constructor(target, action) {
+    constructor(target, action, actionPayload) {
         this._target = target;
         this._action = action || null;
+        this._actionPayload =
+            actionPayload || (action ? { type: 'action', key: 'action', target: getRawTarget(target), args: [] } : null);
     }
     // --- Chained Actions on current target ---
     /**
@@ -38,7 +53,8 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     click() {
-        const target = this.requireTarget("click");
+        const target = this.requireTarget('click');
+        this._actionPayload = { type: 'action', key: 'click', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
             await el.click();
@@ -55,7 +71,8 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     doubleClick() {
-        const target = this.requireTarget("doubleClick");
+        const target = this.requireTarget('doubleClick');
+        this._actionPayload = { type: 'action', key: 'doubleClick', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
             await el.doubleClick();
@@ -73,14 +90,12 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     longPress(durationMs = 1000) {
-        const target = this.requireTarget("longPress");
+        const target = this.requireTarget('longPress');
+        this._actionPayload = { type: 'action', key: 'longPress', target: getRawTarget(target), args: [durationMs] };
         this._action = async () => {
             const el = await resolveElement(target);
-            if (typeof el.touchAction === "function") {
-                await el.touchAction([
-                    { action: "longPress", ms: durationMs },
-                    { action: "release" },
-                ]);
+            if (typeof el.touchAction === 'function') {
+                await el.touchAction([{ action: 'longPress', ms: durationMs }, { action: 'release' }]);
             }
             else {
                 await el.click();
@@ -100,7 +115,8 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     type(value, options) {
-        const target = this.requireTarget("type");
+        const target = this.requireTarget('type');
+        this._actionPayload = { type: 'action', key: 'type', target: getRawTarget(target), args: [value] };
         this._action = async () => {
             const el = await resolveElement(target);
             if (options?.clearFirst) {
@@ -120,7 +136,8 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     clear() {
-        const target = this.requireTarget("clear");
+        const target = this.requireTarget('clear');
+        this._actionPayload = { type: 'action', key: 'clear', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
             await el.clearValue();
@@ -138,7 +155,8 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     select(value) {
-        const target = this.requireTarget("select");
+        const target = this.requireTarget('select');
+        this._actionPayload = { type: 'action', key: 'selectOption', target: getRawTarget(target), args: [value] };
         this._action = async () => {
             const el = await resolveElement(target);
             await el.selectByVisibleText(value);
@@ -155,7 +173,8 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     hover() {
-        const target = this.requireTarget("hover");
+        const target = this.requireTarget('hover');
+        this._actionPayload = { type: 'action', key: 'hover', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
             await el.moveTo();
@@ -173,40 +192,223 @@ export class SingleElementRunner {
      * @returns Current runner instance for method chaining.
      */
     waitForElement(timeoutMs = 10000) {
-        const target = this.requireTarget("waitForElement");
+        const target = this.requireTarget('waitForElement');
+        this._actionPayload = { type: 'action', key: 'waitForElement', target: getRawTarget(target), args: [timeoutMs] };
         this._action = async () => {
             const el = await resolveElement(target);
             await el.waitForDisplayed({ timeout: timeoutMs });
         };
         return this;
     }
-    should(a, b, ...rest) {
-        const isFirstArgMatcher = typeof a === "string" &&
-            (a.includes(".") ||
-                a.includes("exist") ||
-                a.includes("visible") ||
-                a.includes("enabled") ||
-                a.includes("disabled") ||
-                a.includes("selected") ||
-                a.includes("checked"));
-        if (b !== undefined && !isFirstArgMatcher) {
-            // Form: should(target, matcher, ...args)
-            this._assertions.push({
-                target: a,
-                matcher: b,
-                args: rest,
-            });
-        }
-        else {
-            // Form: should(matcher, ...args) -> on current target
-            this._assertions.push({
-                target: this._target,
-                matcher: a,
-                args: b !== undefined ? [b, ...rest] : rest,
-            });
-        }
+    /**
+     * Performs a right-click (context menu) interaction on the target element.
+     */
+    rightClick() {
+        const target = this.requireTarget('rightClick');
+        this._actionPayload = { type: 'action', key: 'rightClick', target: getRawTarget(target), args: [] };
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.click({ button: 'right' });
+        };
+        return this;
+    }
+    /**
+     * Drags the target element and drops it onto the specified destination element.
+     */
+    dragDrop(destination) {
+        const target = this.requireTarget('dragDrop');
+        this._actionPayload = {
+            type: 'action',
+            key: 'dragDrop',
+            target: getRawTarget(target),
+            args: [getRawTarget(destination)],
+        };
+        this._action = async () => {
+            const sourceEl = await resolveElement(target);
+            const destEl = await resolveElement(destination);
+            await sourceEl.dragAndDrop(destEl);
+        };
         return this;
     }
+    /**
+     * Scrolls the target element into view.
+     */
+    scrollIntoView() {
+        const target = this.requireTarget('scrollIntoView');
+        this._actionPayload = { type: 'action', key: 'scrollIntoView', target: getRawTarget(target), args: [] };
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.scrollIntoView();
+        };
+        return this;
+    }
+    _pushAssertion(matcher, args = []) {
+        this._assertions.push({
+            target: this._target,
+            matcher,
+            args,
+        });
+        return this;
+    }
+    // --- Fluent Assertion Matchers ---
+    /**
+     * Asserts that the target element is displayed and visible to the user.
+     */
+    shouldBeVisible() {
+        return this._pushAssertion('be.visible');
+    }
+    /**
+     * Asserts that the target element is not displayed or hidden from view.
+     */
+    shouldNotBeVisible() {
+        return this._pushAssertion('not.be.visible');
+    }
+    /**
+     * Asserts that the target element exists in the DOM.
+     */
+    shouldExist() {
+        return this._pushAssertion('exist');
+    }
+    /**
+     * Asserts that the target element does not exist in the DOM.
+     */
+    shouldNotExist() {
+        return this._pushAssertion('not.exist');
+    }
+    /**
+     * Asserts that the target element is clickable.
+     */
+    shouldBeClickable() {
+        return this._pushAssertion('be.clickable');
+    }
+    /**
+     * Asserts that the target element is not clickable.
+     */
+    shouldNotBeClickable() {
+        return this._pushAssertion('not.be.clickable');
+    }
+    /**
+     * Asserts that the target element is enabled (not disabled).
+     */
+    shouldBeEnabled() {
+        return this._pushAssertion('be.enabled');
+    }
+    /**
+     * Asserts that the target element is disabled.
+     */
+    shouldBeDisabled() {
+        return this._pushAssertion('be.disabled');
+    }
+    /**
+     * Asserts that the target checkbox or radio element is checked.
+     */
+    shouldBeChecked() {
+        return this._pushAssertion('be.checked');
+    }
+    /**
+     * Asserts that the target checkbox or radio element is not checked.
+     */
+    shouldNotBeChecked() {
+        return this._pushAssertion('not.be.checked');
+    }
+    /**
+     * Asserts that the target element currently has focus.
+     */
+    shouldBeFocused() {
+        return this._pushAssertion('be.focused');
+    }
+    /**
+     * Asserts that the target element does not have focus.
+     */
+    shouldNotBeFocused() {
+        return this._pushAssertion('not.be.focused');
+    }
+    /**
+     * Asserts that the target element has exact inner text matching the expected value.
+     */
+    shouldHaveText(expected) {
+        return this._pushAssertion('have.text', [expected]);
+    }
+    /**
+     * Asserts that the target element does not have inner text matching the expected value.
+     */
+    shouldNotHaveText(expected) {
+        return this._pushAssertion('not.have.text', [expected]);
+    }
+    /**
+     * Asserts that the target element's text contains the given substring.
+     */
+    shouldContainText(substring) {
+        return this._pushAssertion('contain.text', [substring]);
+    }
+    /**
+     * Asserts that the target element's text does not contain the given substring.
+     */
+    shouldNotContainText(substring) {
+        return this._pushAssertion('not.contain.text', [substring]);
+    }
+    /**
+     * Asserts that the target input element has the exact expected value.
+     */
+    shouldHaveValue(value) {
+        return this._pushAssertion('have.value', [value]);
+    }
+    /**
+     * Asserts that the target input element does not have the expected value.
+     */
+    shouldNotHaveValue(value) {
+        return this._pushAssertion('not.have.value', [value]);
+    }
+    /**
+     * Asserts that the target input element's value contains the given substring.
+     */
+    shouldContainValue(substring) {
+        return this._pushAssertion('contain.value', [substring]);
+    }
+    /**
+     * Asserts that the target input element's value does not contain the given substring.
+     */
+    shouldNotContainValue(substring) {
+        return this._pushAssertion('not.contain.value', [substring]);
+    }
+    /**
+     * Asserts that the target element has the specified HTML attribute and optional value.
+     */
+    shouldHaveAttribute(name, value) {
+        return value !== undefined
+            ? this._pushAssertion('have.attr', [name, value])
+            : this._pushAssertion('have.attr', [name]);
+    }
+    /**
+     * Asserts that the target element does not have the specified HTML attribute.
+     */
+    shouldNotHaveAttribute(name) {
+        return this._pushAssertion('not.have.attr', [name]);
+    }
+    /**
+     * Asserts that the target element has the specified CSS class.
+     */
+    shouldHaveClass(className) {
+        return this._pushAssertion('have.class', [className]);
+    }
+    /**
+     * Asserts that the target element does not have the specified CSS class.
+     */
+    shouldNotHaveClass(className) {
+        return this._pushAssertion('not.have.class', [className]);
+    }
+    /**
+     * Asserts that the target element has the specified computed CSS property value.
+     */
+    shouldHaveCss(property, value) {
+        return this._pushAssertion('have.css', [property, value]);
+    }
+    /**
+     * Asserts that the target element does not have the specified computed CSS property value.
+     */
+    shouldNotHaveCss(property, value) {
+        return this._pushAssertion('not.have.css', [property, value]);
+    }
     // --- Execution when awaited ---
     /**
      * Standard Promise `then` implementation.
@@ -215,10 +417,26 @@ export class SingleElementRunner {
     async then(onfulfilled, onrejected) {
         try {
             if (this._action) {
-                await this._action();
+                const payload = this._actionPayload || {
+                    type: 'action',
+                    key: 'action',
+                    target: getRawTarget(this._target),
+                    args: [],
+                };
+                await trackCommand('action', payload, async () => {
+                    await this._action();
+                });
             }
             for (const assert of this._assertions) {
-                await executeSingleMatcher(assert.target, assert.matcher, assert.args);
+                const payload = {
+                    type: 'assertion',
+                    key: assert.matcher,
+                    target: getRawTarget(assert.target),
+                    args: assert.args,
+                };
+                await trackCommand('assertion', payload, async () => {
+                    await executeSingleMatcher(assert.target, assert.matcher, assert.args);
+                });
             }
             const res = (onfulfilled ? await onfulfilled() : undefined);
             return res;

package/dist/spectra.d.ts

@@ -1,6 +1,7 @@
-import { ClickOptions, ElementTarget, KeyOption, LongPressOptions, ScrollOptions, SwipeOptions, TypeOptions } from "./types.js";
-import { SingleElementRunner } from "./runner/single.js";
-import { MultiElementRunner } from "./runner/collection.js";
+import { BrowserReceiverAssertions, ClickOptions, ElementTarget, KeyOption, LongPressOptions, ScrollOptions, SwipeOptions, TypeOptions } from './types.js';
+import { SingleElementRunner } from './runner/single.js';
+import { MultiElementRunner } from './runner/collection.js';
+import { MockHandle, InterceptRule } from './intercept/index.js';
 /**
  * Main TestSpectra cross-platform automation and assertion orchestrator.
  *
@@ -14,7 +15,7 @@ import { MultiElementRunner } from "./runner/collection.js";
  * await Spectra.get("#username").type("admin");
  *
  * // Collection assertion
- * await Spectra.getAll(".item").should("have.length", 5);
+ * await Spectra.getAll(".item").shouldHaveLength(5);
  *
  * // Mobile touch swipe
  * await Spectra.swipe({ direction: "left", distance: 350 });
@@ -28,7 +29,7 @@ export declare class SpectraStatic {
      * @example
      * ```ts
      * await Spectra.get("#login-btn").click();
-     * await Spectra.get(LoginPage.submitButton).should("be.visible");
+     * await Spectra.get(LoginPage.submitButton).shouldBeVisible();
      * ```
      * @returns `SingleElementRunner` for chaining actions and assertions.
      */
@@ -39,7 +40,7 @@ export declare class SpectraStatic {
      * @param selector - Selector string matching multiple elements.
      * @example
      * ```ts
-     * await Spectra.getAll(".product-card").should("have.length.greaterThan", 0);
+     * await Spectra.getAll(".product-card").shouldHaveLengthGreaterThan(0);
      * await Spectra.getAll("li.tab").first().click();
      * ```
      * @returns `MultiElementRunner` for collection assertions and indexing.
@@ -85,7 +86,7 @@ export declare class SpectraStatic {
      * await Spectra.click(LoginPage.loginBtn);
      * ```
      */
-    click(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    click(target: ElementTarget, _textOrOptions?: string | ClickOptions): SingleElementRunner;
     /**
      * Performs a double-click on the specified element.
      *
@@ -96,7 +97,7 @@ export declare class SpectraStatic {
      * await Spectra.doubleClick(".grid-row");
      * ```
      */
-    doubleClick(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    doubleClick(target: ElementTarget, _textOrOptions?: string | ClickOptions): SingleElementRunner;
     /**
      * Performs a long-press touch or hold gesture on the specified element.
      *
@@ -217,6 +218,29 @@ export declare class SpectraStatic {
      * ```
      */
     waitForElement(target: ElementTarget, timeoutMs?: number): SingleElementRunner;
+    /**
+     * Intercepts HTTP/HTTPS network traffic matching the given URL rule.
+     *
+     * @param rule - URL pattern string or InterceptRule configuration.
+     * @example
+     * ```ts
+     * const mock = await Spectra.intercept({
+     *   url: "/api/v1/users",
+     *   method: "GET",
+     *   response: { status: 200, body: [{ id: 1, name: "Admin" }] }
+     * });
+     * ```
+     * @returns `MockHandle` for sequential queue responses, abort, and assertions.
+     */
+    intercept(rule: InterceptRule | string): Promise<MockHandle>;
+    /**
+     * Clears all active mock rules and resets the mock registry for worker isolation.
+     */
+    clearMocks(): void;
+    /**
+     * Browser-level assertions and utilities (cookies, localStorage, url, title).
+     */
+    get browser(): BrowserReceiverAssertions;
 }
 /**
  * Global singleton instance of `SpectraStatic`.