@testspectra/matchers 1.1.8-rc.2 → 1.1.8-rc.4

package/dist/reporter.js

@@ -67,7 +67,19 @@ export function formatArgs(args) {
  */
 export async function trackCommand(category, commandText, fn) {
     const start = Date.now();
-    const payload = typeof commandText === 'object' ? JSON.stringify(commandText) : commandText;
+    const payloadObj = typeof commandText === 'object' ? { ...commandText } : { text: commandText };
+    if (typeof globalThis !== 'undefined') {
+        const g = globalThis;
+        const currentTest = g.__CURRENT_TEST_TITLE__ || g.__CURRENT_TEST_ID__;
+        if (currentTest && !payloadObj.test) {
+            payloadObj.test = currentTest;
+        }
+        const workerId = g.__TESTSPECTRA_WORKER_ID__;
+        if (workerId !== undefined && payloadObj.workerId === undefined) {
+            payloadObj.workerId = workerId;
+        }
+    }
+    const payload = JSON.stringify(payloadObj);
     console.log(`[TESTSPECTRA_STEP_START] ${payload}`);
     try {
         const result = await fn();

package/dist/runner/collection.d.ts

@@ -1,4 +1,4 @@
-import { CollectionReceiverAssertions, MultiElementMatcher } from '../types.js';
+import { CollectionReceiverAssertions } from '../types.js';
 import { SingleElementRunner } from './single.js';
 /**
  * Fluent assertion, filtering, and iteration runner for multi-element collections.
@@ -26,6 +26,7 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
     private _selector;
     private _assertions;
     constructor(selector: string);
+    private _pushAssertion;
     /**
      * Asserts that the collection contains exactly `count` elements.
      */
@@ -50,19 +51,6 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
      * Asserts that the collection is not empty (contains at least 1 element).
      */
     shouldNotBeEmpty(): this;
-    /**
-     * Queues an assertion matcher against the multi-element collection.
-     *
-     * @param matcher - Multi-element matcher string (e.g. `'have.length'`, `'be.empty'`).
-     * @param args - Expected values or limits for the matcher.
-     * @example
-     * ```ts
-     * await Spectra.getAll(".product-card").should("have.length.greaterThan", 0);
-     * await Spectra.getAll(".error-badge").should("be.empty");
-     * ```
-     * @returns Current collection runner instance for chaining.
-     */
-    should(matcher: MultiElementMatcher, ...args: any[]): this;
     /**
      * Returns a `SingleElementRunner` targeting the element at the specified 0-based index.
      *
@@ -89,7 +77,7 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
      *
      * @example
      * ```ts
-     * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
+     * await Spectra.getAll(".step-indicator").last().shouldHaveClass("current");
      * ```
      * @returns `SingleElementRunner` for the last element.
      */
@@ -101,7 +89,7 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
      * @example
      * ```ts
      * await Spectra.getAll(".checkbox").each(async (item, index) => {
-     *   await item.should("be.visible");
+     *   await item.shouldBeVisible();
      * });
      * ```
      */

package/dist/runner/collection.js

@@ -29,58 +29,46 @@ export class MultiElementRunner {
     constructor(selector) {
         this._selector = selector;
     }
+    _pushAssertion(matcher, args = []) {
+        this._assertions.push({ matcher, args });
+        return this;
+    }
     // --- Collection Assertions ---
     /**
      * Asserts that the collection contains exactly `count` elements.
      */
     shouldHaveLength(count) {
-        return this.should('have.length', count);
+        return this._pushAssertion('have.length', [count]);
     }
     /**
      * Asserts that the collection does not contain `count` elements.
      */
     shouldNotHaveLength(count) {
-        return this.should('not.have.length', count);
+        return this._pushAssertion('not.have.length', [count]);
     }
     /**
      * Asserts that the collection contains more than `min` elements.
      */
     shouldHaveLengthGreaterThan(min) {
-        return this.should('have.length.greaterThan', min);
+        return this._pushAssertion('have.length.greaterThan', [min]);
     }
     /**
      * Asserts that the collection contains less than `max` elements.
      */
     shouldHaveLengthLessThan(max) {
-        return this.should('have.length.lessThan', max);
+        return this._pushAssertion('have.length.lessThan', [max]);
     }
     /**
      * Asserts that the collection is empty (contains 0 elements).
      */
     shouldBeEmpty() {
-        return this.should('be.empty');
+        return this._pushAssertion('be.empty');
     }
     /**
      * Asserts that the collection is not empty (contains at least 1 element).
      */
     shouldNotBeEmpty() {
-        return this.should('not.be.empty');
-    }
-    /**
-     * Queues an assertion matcher against the multi-element collection.
-     *
-     * @param matcher - Multi-element matcher string (e.g. `'have.length'`, `'be.empty'`).
-     * @param args - Expected values or limits for the matcher.
-     * @example
-     * ```ts
-     * await Spectra.getAll(".product-card").should("have.length.greaterThan", 0);
-     * await Spectra.getAll(".error-badge").should("be.empty");
-     * ```
-     * @returns Current collection runner instance for chaining.
-     */
-    should(matcher, ...args) {
-        this._assertions.push({ matcher, args });
-        return this;
+        return this._pushAssertion('not.be.empty');
     }
     // --- Item Navigation ---
     /**
@@ -96,9 +84,22 @@ export class MultiElementRunner {
     eq(index) {
         const targetSelector = `${this._selector}[${index}]`;
         const elPromise = (async () => {
-            if (typeof $$ !== 'undefined') {
-                const elements = await $$(this._selector);
-                return elements[index];
+            const getElements = typeof $$ !== 'undefined' ? $$ : globalThis.$$;
+            if (typeof getElements === 'function') {
+                const elements = await getElements(this._selector);
+                if (typeof elements?.nth === 'function') {
+                    return elements.nth(index);
+                }
+                if (index === 0 && typeof elements?.first === 'function') {
+                    return elements.first();
+                }
+                if (elements && elements[index] !== undefined) {
+                    return elements[index];
+                }
+            }
+            const getDollar = typeof $ !== 'undefined' ? $ : globalThis.$;
+            if (typeof getDollar === 'function') {
+                return getDollar(targetSelector);
             }
             return { selector: targetSelector };
         })();
@@ -122,17 +123,30 @@ export class MultiElementRunner {
      *
      * @example
      * ```ts
-     * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
+     * await Spectra.getAll(".step-indicator").last().shouldHaveClass("current");
      * ```
      * @returns `SingleElementRunner` for the last element.
      */
     last() {
         const targetSelector = `${this._selector}[last()]`;
         const elPromise = (async () => {
-            if (typeof $$ !== 'undefined') {
-                const elements = await $$(this._selector);
+            const getElements = typeof $$ !== 'undefined' ? $$ : globalThis.$$;
+            if (typeof getElements === 'function') {
+                const elements = await getElements(this._selector);
+                if (typeof elements?.last === 'function') {
+                    return elements.last();
+                }
+                if (typeof elements?.nth === 'function') {
+                    return elements.nth(-1);
+                }
                 const arr = Array.isArray(elements) ? elements : await elements;
-                return arr[arr.length - 1];
+                if (arr && arr.length > 0) {
+                    return arr[arr.length - 1];
+                }
+            }
+            const getDollar = typeof $ !== 'undefined' ? $ : globalThis.$;
+            if (typeof getDollar === 'function') {
+                return getDollar(targetSelector);
             }
             return { selector: targetSelector };
         })();
@@ -147,7 +161,7 @@ export class MultiElementRunner {
      * @example
      * ```ts
      * await Spectra.getAll(".checkbox").each(async (item, index) => {
-     *   await item.should("be.visible");
+     *   await item.shouldBeVisible();
      * });
      * ```
      */

package/dist/runner/single.d.ts

@@ -1,4 +1,4 @@
-import { ElementReceiverAssertions, ElementTarget, SingleElementMatcher, TypeOptions } from '../types.js';
+import { ElementReceiverAssertions, ElementTarget, TypeOptions } from '../types.js';
 /**
  * Fluent interaction and assertion runner for a single element or browser context.
  *
@@ -90,11 +90,11 @@ export declare class SingleElementRunner implements PromiseLike<void>, ElementRe
      */
     select(value: string): this;
     /**
-     * Moves the mouse cursor over the target element (hover).
+     * Hovers over the target element.
      *
      * @example
      * ```ts
-     * await Spectra.get("#dropdown-menu-trigger").hover();
+     * await Spectra.get("#dropdown-trigger").hover();
      * ```
      * @returns Current runner instance for method chaining.
      */
@@ -122,6 +122,7 @@ export declare class SingleElementRunner implements PromiseLike<void>, ElementRe
      * Scrolls the target element into view.
      */
     scrollIntoView(): this;
+    private _pushAssertion;
     /**
      * Asserts that the target element is displayed and visible to the user.
      */
@@ -226,33 +227,6 @@ export declare class SingleElementRunner implements PromiseLike<void>, ElementRe
      * Asserts that the target element does not have the specified computed CSS property value.
      */
     shouldNotHaveCss(property: string, value: string): this;
-    /**
-     * Queues an assertion matcher against the current target element or page.
-     *
-     * @param matcher - Single element matcher string (e.g. `'be.visible'`, `'have.text'`).
-     * @param args - Additional parameters for the matcher (e.g. expected text or value).
-     * @example
-     * ```ts
-     * await Spectra.get("#status-badge").should("be.visible");
-     * await Spectra.get("#username").should("have.value", "alice");
-     * await Spectra.get("#banner").should("have.class", "alert-success");
-     * ```
-     * @returns Current runner instance for method chaining.
-     */
-    should(matcher: SingleElementMatcher, ...args: any[]): this;
-    /**
-     * Queues an assertion matcher targeting a specific element.
-     *
-     * @param target - Custom element target for this specific assertion.
-     * @param matcher - Single element matcher string.
-     * @param args - Additional parameters for the matcher.
-     * @example
-     * ```ts
-     * await Spectra.should(LoginPage.submitBtn, "be.enabled");
-     * ```
-     * @returns Current runner instance for method chaining.
-     */
-    should(target: ElementTarget, matcher: SingleElementMatcher, ...args: any[]): this;
     /**
      * Standard Promise `then` implementation.
      * Executes queued action first (if any), followed sequentially by all queued assertions.

package/dist/runner/single.js

@@ -120,9 +120,17 @@ export class SingleElementRunner {
         this._action = async () => {
             const el = await resolveElement(target);
             if (options?.clearFirst) {
-                await el.clearValue();
+                if (typeof el.clearValue === 'function')
+                    await el.clearValue();
+                else if (typeof el.clear === 'function')
+                    await el.clear();
             }
-            await el.setValue(value);
+            if (typeof el.setValue === 'function')
+                await el.setValue(value);
+            else if (typeof el.fill === 'function')
+                await el.fill(value);
+            else if (typeof el.type === 'function')
+                await el.type(value);
         };
         return this;
     }
@@ -140,7 +148,10 @@ export class SingleElementRunner {
         this._actionPayload = { type: 'action', key: 'clear', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
-            await el.clearValue();
+            if (typeof el.clearValue === 'function')
+                await el.clearValue();
+            else if (typeof el.clear === 'function')
+                await el.clear();
         };
         return this;
     }
@@ -159,16 +170,19 @@ export class SingleElementRunner {
         this._actionPayload = { type: 'action', key: 'selectOption', target: getRawTarget(target), args: [value] };
         this._action = async () => {
             const el = await resolveElement(target);
-            await el.selectByVisibleText(value);
+            if (typeof el.selectByVisibleText === 'function')
+                await el.selectByVisibleText(value);
+            else if (typeof el.selectOption === 'function')
+                await el.selectOption({ label: value });
         };
         return this;
     }
     /**
-     * Moves the mouse cursor over the target element (hover).
+     * Hovers over the target element.
      *
      * @example
      * ```ts
-     * await Spectra.get("#dropdown-menu-trigger").hover();
+     * await Spectra.get("#dropdown-trigger").hover();
      * ```
      * @returns Current runner instance for method chaining.
      */
@@ -177,7 +191,10 @@ export class SingleElementRunner {
         this._actionPayload = { type: 'action', key: 'hover', target: getRawTarget(target), args: [] };
         this._action = async () => {
             const el = await resolveElement(target);
-            await el.moveTo();
+            if (typeof el.moveTo === 'function')
+                await el.moveTo();
+            else if (typeof el.hover === 'function')
+                await el.hover();
         };
         return this;
     }
@@ -242,191 +259,172 @@ export class SingleElementRunner {
         };
         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.should('be.visible');
+        return this._pushAssertion('be.visible');
     }
     /**
      * Asserts that the target element is not displayed or hidden from view.
      */
     shouldNotBeVisible() {
-        return this.should('not.be.visible');
+        return this._pushAssertion('not.be.visible');
     }
     /**
      * Asserts that the target element exists in the DOM.
      */
     shouldExist() {
-        return this.should('exist');
+        return this._pushAssertion('exist');
     }
     /**
      * Asserts that the target element does not exist in the DOM.
      */
     shouldNotExist() {
-        return this.should('not.exist');
+        return this._pushAssertion('not.exist');
     }
     /**
      * Asserts that the target element is clickable.
      */
     shouldBeClickable() {
-        return this.should('be.clickable');
+        return this._pushAssertion('be.clickable');
     }
     /**
      * Asserts that the target element is not clickable.
      */
     shouldNotBeClickable() {
-        return this.should('not.be.clickable');
+        return this._pushAssertion('not.be.clickable');
     }
     /**
      * Asserts that the target element is enabled (not disabled).
      */
     shouldBeEnabled() {
-        return this.should('be.enabled');
+        return this._pushAssertion('be.enabled');
     }
     /**
      * Asserts that the target element is disabled.
      */
     shouldBeDisabled() {
-        return this.should('be.disabled');
+        return this._pushAssertion('be.disabled');
     }
     /**
      * Asserts that the target checkbox or radio element is checked.
      */
     shouldBeChecked() {
-        return this.should('be.checked');
+        return this._pushAssertion('be.checked');
     }
     /**
      * Asserts that the target checkbox or radio element is not checked.
      */
     shouldNotBeChecked() {
-        return this.should('not.be.checked');
+        return this._pushAssertion('not.be.checked');
     }
     /**
      * Asserts that the target element currently has focus.
      */
     shouldBeFocused() {
-        return this.should('be.focused');
+        return this._pushAssertion('be.focused');
     }
     /**
      * Asserts that the target element does not have focus.
      */
     shouldNotBeFocused() {
-        return this.should('not.be.focused');
+        return this._pushAssertion('not.be.focused');
     }
     /**
      * Asserts that the target element has exact inner text matching the expected value.
      */
     shouldHaveText(expected) {
-        return this.should('have.text', 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.should('not.have.text', expected);
+        return this._pushAssertion('not.have.text', [expected]);
     }
     /**
      * Asserts that the target element's text contains the given substring.
      */
     shouldContainText(substring) {
-        return this.should('contain.text', substring);
+        return this._pushAssertion('contain.text', [substring]);
     }
     /**
      * Asserts that the target element's text does not contain the given substring.
      */
     shouldNotContainText(substring) {
-        return this.should('not.contain.text', substring);
+        return this._pushAssertion('not.contain.text', [substring]);
     }
     /**
      * Asserts that the target input element has the exact expected value.
      */
     shouldHaveValue(value) {
-        return this.should('have.value', value);
+        return this._pushAssertion('have.value', [value]);
     }
     /**
      * Asserts that the target input element does not have the expected value.
      */
     shouldNotHaveValue(value) {
-        return this.should('not.have.value', value);
+        return this._pushAssertion('not.have.value', [value]);
     }
     /**
      * Asserts that the target input element's value contains the given substring.
      */
     shouldContainValue(substring) {
-        return this.should('contain.value', 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.should('not.contain.value', 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.should('have.attr', name, value) : this.should('have.attr', name);
+        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.should('not.have.attr', name);
+        return this._pushAssertion('not.have.attr', [name]);
     }
     /**
      * Asserts that the target element has the specified CSS class.
      */
     shouldHaveClass(className) {
-        return this.should('have.class', className);
+        return this._pushAssertion('have.class', [className]);
     }
     /**
      * Asserts that the target element does not have the specified CSS class.
      */
     shouldNotHaveClass(className) {
-        return this.should('not.have.class', 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.should('have.css', 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.should('not.have.css', property, value);
-    }
-    should(a, b, ...rest) {
-        const isFirstArgMatcher = typeof a === 'string' &&
-            (a.includes('.') ||
-                a.includes('exist') ||
-                a.includes('visible') ||
-                a.includes('clickable') ||
-                a.includes('focused') ||
-                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,
-            });
-        }
-        return this;
+        return this._pushAssertion('not.have.css', [property, value]);
     }
     // --- Execution when awaited ---
     /**

package/dist/spectra.d.ts

@@ -15,7 +15,7 @@ import { MockHandle, InterceptRule } from './intercept/index.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 });
@@ -29,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.
      */
@@ -40,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.

package/dist/spectra.js

@@ -16,7 +16,7 @@ import { trackCommand } from './reporter.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 });
@@ -30,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.
      */
@@ -43,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.

package/package.json

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