@testspectra/matchers 1.0.70 → 1.1.0

package/dist/spectra.js

@@ -1,6 +1,8 @@
-import { SingleElementRunner } from "./runner/single.js";
-import { MultiElementRunner } from "./runner/collection.js";
-import { resolveElement } from "./matchers.js";
+import { SingleElementRunner } from './runner/single.js';
+import { MultiElementRunner } from './runner/collection.js';
+import { executeBrowserAssertion, resolveElement } from './matchers.js';
+import { CdpHandler, MockRegistry } from './intercept/index.js';
+import { trackCommand } from './reporter.js';
 /**
  * Main TestSpectra cross-platform automation and assertion orchestrator.
  *
@@ -14,7 +16,7 @@ import { resolveElement } from "./matchers.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 +30,7 @@ export 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.
      */
@@ -41,7 +43,7 @@ export 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.
@@ -63,7 +65,7 @@ export class SpectraStatic {
     navigate(url) {
         return new SingleElementRunner(undefined, async () => {
             await browser.url(url);
-        });
+        }, { type: 'action', key: 'navigate', target: undefined, args: [url] });
     }
     /**
      * Navigates back one step in the browser / app history.
@@ -76,7 +78,7 @@ export class SpectraStatic {
     back() {
         return new SingleElementRunner(undefined, async () => {
             await browser.back();
-        });
+        }, { type: 'action', key: 'back', target: undefined, args: [] });
     }
     /**
      * Refreshes the current browser page.
@@ -89,7 +91,7 @@ export class SpectraStatic {
     refresh() {
         return new SingleElementRunner(undefined, async () => {
             await browser.refresh();
-        });
+        }, { type: 'action', key: 'refresh', target: undefined, args: [] });
     }
     // --- Direct Interaction Actions ---
     /**
@@ -103,11 +105,11 @@ export class SpectraStatic {
      * await Spectra.click(LoginPage.loginBtn);
      * ```
      */
-    click(target, textOrOptions) {
+    click(target, _textOrOptions) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.click();
-        });
+        }, { type: 'action', key: 'click', target: target, args: [] });
     }
     /**
      * Performs a double-click on the specified element.
@@ -119,11 +121,11 @@ export class SpectraStatic {
      * await Spectra.doubleClick(".grid-row");
      * ```
      */
-    doubleClick(target, textOrOptions) {
+    doubleClick(target, _textOrOptions) {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.doubleClick();
-        });
+        }, { type: 'action', key: 'doubleClick', target: target, args: [] });
     }
     /**
      * Performs a long-press touch or hold gesture on the specified element.
@@ -137,19 +139,16 @@ export class SpectraStatic {
      * ```
      */
     longPress(target, options) {
-        const duration = typeof options === "number" ? options : options?.duration || 1000;
+        const duration = typeof options === 'number' ? options : options?.duration || 1000;
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
-            if (typeof el.touchAction === "function") {
-                await el.touchAction([
-                    { action: "longPress", ms: duration },
-                    { action: "release" },
-                ]);
+            if (typeof el.touchAction === 'function') {
+                await el.touchAction([{ action: 'longPress', ms: duration }, { action: 'release' }]);
             }
             else {
                 await el.click();
             }
-        });
+        }, { type: 'action', key: 'longPress', target: target, args: [duration] });
     }
     /**
      * Types text into the specified element.
@@ -170,7 +169,7 @@ export class SpectraStatic {
                 await el.clearValue();
             }
             await el.setValue(value);
-        });
+        }, { type: 'action', key: 'type', target: target, args: [value] });
     }
     /**
      * Clears the input content from the specified element.
@@ -185,7 +184,7 @@ export class SpectraStatic {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.clearValue();
-        });
+        }, { type: 'action', key: 'clear', target: target, args: [] });
     }
     /**
      * Selects an option from a `<select>` dropdown by its visible text.
@@ -201,7 +200,7 @@ export class SpectraStatic {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.selectByVisibleText(value);
-        });
+        }, { type: 'action', key: 'select', target: target, args: [value] });
     }
     /**
      * Hovers the mouse pointer over the specified element.
@@ -216,7 +215,7 @@ export class SpectraStatic {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.moveTo();
-        });
+        }, { type: 'action', key: 'hover', target: target, args: [] });
     }
     /**
      * Simulates pressing a specific keyboard key.
@@ -231,7 +230,7 @@ export class SpectraStatic {
     pressKey(key) {
         return new SingleElementRunner(undefined, async () => {
             await browser.keys(key);
-        });
+        }, { type: 'action', key: 'pressKey', target: undefined, args: [key] });
     }
     /**
      * Drags a source element and drops it onto a destination target.
@@ -248,7 +247,7 @@ export class SpectraStatic {
             const source = await resolveElement(sourceTarget);
             const target = await resolveElement(destTarget);
             await source.dragAndDrop(target);
-        });
+        }, { type: 'action', key: 'dragDrop', target: sourceTarget, args: [destTarget] });
     }
     // --- Gesture Actions ---
     /**
@@ -271,12 +270,17 @@ export class SpectraStatic {
                 await browser.execute((direction, pixels) => {
                     const delta = pixels || 500;
                     window.scrollBy({
-                        top: direction === "up" ? -delta : direction === "down" ? delta : 0,
-                        left: direction === "left" ? -delta : direction === "right" ? delta : 0,
-                        behavior: "smooth",
+                        top: direction === 'up' ? -delta : direction === 'down' ? delta : 0,
+                        left: direction === 'left' ? -delta : direction === 'right' ? delta : 0,
+                        behavior: 'smooth',
                     });
-                }, options?.direction || "down", options?.pixels || 500);
+                }, options?.direction || 'down', options?.pixels || 500);
             }
+        }, {
+            type: 'action',
+            key: 'scroll',
+            target: options?.selector,
+            args: [options?.direction || 'down', options?.pixels || 500],
         });
     }
     /**
@@ -290,23 +294,26 @@ export class SpectraStatic {
      */
     swipe(options) {
         return new SingleElementRunner(options.selector, async () => {
-            if (typeof browser.touchAction === "function") {
+            if (typeof browser.touchAction === 'function') {
                 const distance = options.distance || 300;
                 await browser.touchAction([
-                    { action: "press", x: 200, y: 500 },
+                    { action: 'press', x: 200, y: 500 },
                     {
-                        action: "moveTo",
-                        x: options.direction === "right" ? 200 + distance : options.direction === "left" ? 200 - distance : 200,
-                        y: options.direction === "down" ? 500 + distance : options.direction === "up" ? 500 - distance : 500,
+                        action: 'moveTo',
+                        x: options.direction === 'right' ? 200 + distance : options.direction === 'left' ? 200 - distance : 200,
+                        y: options.direction === 'down' ? 500 + distance : options.direction === 'up' ? 500 - distance : 500,
                     },
-                    { action: "release" },
+                    { action: 'release' },
                 ]);
             }
             else {
                 // Fallback to web scroll
-                await this.scroll({ direction: options.direction, pixels: options.distance });
+                await this.scroll({
+                    direction: options.direction,
+                    pixels: options.distance,
+                });
             }
-        });
+        }, { type: 'action', key: 'swipe', target: options.selector, args: [options.direction, options.distance || 300] });
     }
     // --- Timing Actions ---
     /**
@@ -321,7 +328,7 @@ export class SpectraStatic {
     wait(durationMs) {
         return new SingleElementRunner(undefined, async () => {
             await browser.pause(durationMs);
-        });
+        }, { type: 'action', key: 'wait', target: undefined, args: [durationMs] });
     }
     /**
      * Waits until the specified element is displayed on the screen.
@@ -337,7 +344,117 @@ export class SpectraStatic {
         return new SingleElementRunner(target, async () => {
             const el = await resolveElement(target);
             await el.waitForDisplayed({ timeout: timeoutMs });
-        });
+        }, { type: 'action', key: 'waitForElement', target: target, args: [] });
+    }
+    // --- Network Interception & Mocking Actions ---
+    /**
+     * 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.
+     */
+    async intercept(rule) {
+        const normalizedRule = typeof rule === 'string' ? { url: rule } : rule;
+        return CdpHandler.registerRule(normalizedRule);
+    }
+    /**
+     * Clears all active mock rules and resets the mock registry for worker isolation.
+     */
+    clearMocks() {
+        MockRegistry.getInstance().clear();
+    }
+    /**
+     * Browser-level assertions and utilities (cookies, localStorage, url, title).
+     */
+    get browser() {
+        return {
+            shouldHaveUrl: async (expectedUrl) => {
+                const payload = {
+                    type: 'assertion',
+                    key: 'shouldHaveUrl',
+                    args: [expectedUrl],
+                };
+                await trackCommand('browser', payload, async () => {
+                    await executeBrowserAssertion('shouldHaveUrl', [expectedUrl]);
+                });
+            },
+            shouldContainUrl: async (expectedSubstr) => {
+                const payload = {
+                    type: 'assertion',
+                    key: 'shouldContainUrl',
+                    args: [expectedSubstr],
+                };
+                await trackCommand('browser', payload, async () => {
+                    await executeBrowserAssertion('shouldContainUrl', [expectedSubstr]);
+                });
+            },
+            shouldHaveTitle: async (expectedTitle) => {
+                const payload = {
+                    type: 'assertion',
+                    key: 'shouldHaveTitle',
+                    args: [expectedTitle],
+                };
+                await trackCommand('browser', payload, async () => {
+                    await executeBrowserAssertion('shouldHaveTitle', [expectedTitle]);
+                });
+            },
+            shouldContainTitle: async (expectedSubstr) => {
+                const payload = {
+                    type: 'assertion',
+                    key: 'shouldContainTitle',
+                    args: [expectedSubstr],
+                };
+                await trackCommand('browser', payload, async () => {
+                    await executeBrowserAssertion('shouldContainTitle', [expectedSubstr]);
+                });
+            },
+            shouldBePageLoaded: async () => {
+                const payload = {
+                    type: 'assertion',
+                    key: 'shouldBePageLoaded',
+                    args: [],
+                };
+                await trackCommand('browser', payload, async () => {
+                    await executeBrowserAssertion('shouldBePageLoaded');
+                });
+            },
+            shouldHaveNoConsoleErrors: async () => {
+                const payload = {
+                    type: 'assertion',
+                    key: 'shouldHaveNoConsoleErrors',
+                    args: [],
+                };
+                await trackCommand('browser', payload, async () => {
+                    await executeBrowserAssertion('shouldHaveNoConsoleErrors');
+                });
+            },
+            clearCookies: async () => {
+                const payload = { type: 'action', key: 'clearCookies', args: [] };
+                await trackCommand('browser', payload, async () => {
+                    const b = typeof browser !== 'undefined' ? browser : globalThis.browser;
+                    if (b && typeof b.deleteAllCookies === 'function') {
+                        await b.deleteAllCookies();
+                    }
+                });
+            },
+            clearLocalStorage: async () => {
+                const payload = { type: 'action', key: 'clearLocalStorage', args: [] };
+                await trackCommand('browser', payload, async () => {
+                    const b = typeof browser !== 'undefined' ? browser : globalThis.browser;
+                    if (b && typeof b.execute === 'function') {
+                        await b.execute(() => localStorage.clear());
+                    }
+                });
+            },
+        };
     }
 }
 /**