@testspectra/matchers 1.1.0 → 1.1.8-rc.1

package/dist/proto.d.ts

@@ -16,6 +16,14 @@ declare global {
      * Global step library injected by TestSpectra runner.
      */
     var Step: Record<string, any>;
+    /**
+     * Typed shape of `Spectra.env`. Empty by default — each `spectra.config.ts`
+     * `executionConfig.environmentVariables` key is merged in as a `readonly <KEY>: string` member
+     * by the CLI's generated `.testspectra/types/env.d.ts` (plain TypeScript interface merging, the
+     * same mechanism `@types/node` uses to let projects augment `NodeJS.ProcessEnv`).
+     */
+    interface SpectraEnv {
+    }
     namespace WebdriverIO {
         interface Browser extends SpectraBrowserBridge {
         }

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.js

@@ -84,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 };
         })();
@@ -117,10 +130,23 @@ export class MultiElementRunner {
     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 };
         })();

package/dist/runner/single.d.ts

@@ -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.
      */

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;
     }

package/dist/semantic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers - Semantic Natural Language Formatter
+ *
+ * Formats commands, actions, and assertions into clean, grammatically
+ * correct English sentences for real-time reporting.
+ */
+export declare function formatSemanticTarget(target: any, isCollection?: boolean): string;
+export declare function formatSemanticAction(action: string, target: any, args?: any[]): string;
+export declare function formatSemanticMatcher(target: any, matcher: string, args?: any[], isCollection?: boolean): string;
+export declare function formatSemanticBrowser(method: string, args?: any[]): string;

package/dist/semantic.js

@@ -0,0 +1,141 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers - Semantic Natural Language Formatter
+ *
+ * Formats commands, actions, and assertions into clean, grammatically
+ * correct English sentences for real-time reporting.
+ */
+export function formatSemanticTarget(target, isCollection = false) {
+    if (target === undefined || target === null)
+        return isCollection ? 'collection' : 'element';
+    if (typeof target === 'string') {
+        return isCollection ? `collection "${target}"` : `element "${target}"`;
+    }
+    if (typeof target === 'object') {
+        if (target.selector) {
+            return isCollection ? `collection "${target.selector}"` : `element "${target.selector}"`;
+        }
+        if (target.constructor && target.constructor.name && target.constructor.name !== 'Object') {
+            return `element "${target.constructor.name}"`;
+        }
+    }
+    return `element "${String(target)}"`;
+}
+export function formatSemanticAction(action, target, args = []) {
+    const targetStr = formatSemanticTarget(target, false);
+    const arg0 = args[0] !== undefined ? String(args[0]) : '';
+    switch (action) {
+        case 'type':
+            return `Type "${arg0}" into ${targetStr}`;
+        case 'click':
+            return `Click on ${targetStr}`;
+        case 'doubleClick':
+            return `Double-click on ${targetStr}`;
+        case 'rightClick':
+            return `Right-click on ${targetStr}`;
+        case 'check':
+            return `Check checkbox ${targetStr}`;
+        case 'uncheck':
+            return `Uncheck checkbox ${targetStr}`;
+        case 'selectOption':
+            return `Select option "${arg0}" in ${targetStr}`;
+        case 'clear':
+            return `Clear text in ${targetStr}`;
+        case 'hover':
+            return `Hover over ${targetStr}`;
+        case 'scrollIntoView':
+            return `Scroll ${targetStr} into view`;
+        case 'navigate':
+            return `Navigate to "${arg0}"`;
+        case 'wait':
+            return `Wait for ${arg0}ms`;
+        case 'pause':
+            return `Pause execution for ${arg0}ms`;
+        default:
+            return `Perform ${action} on ${targetStr}`;
+    }
+}
+export function formatSemanticMatcher(target, matcher, args = [], isCollection = false) {
+    const targetStr = formatSemanticTarget(target, isCollection);
+    const arg0 = args[0] !== undefined ? String(args[0]) : '';
+    const arg1 = args[1] !== undefined ? String(args[1]) : '';
+    switch (matcher) {
+        case 'be.visible':
+            return `Expect ${targetStr} to be visible`;
+        case 'not.be.visible':
+            return `Expect ${targetStr} not to be visible`;
+        case 'exist':
+            return `Expect ${targetStr} to exist in DOM`;
+        case 'not.exist':
+            return `Expect ${targetStr} not to exist in DOM`;
+        case 'be.enabled':
+            return `Expect ${targetStr} to be enabled`;
+        case 'be.disabled':
+            return `Expect ${targetStr} to be disabled`;
+        case 'be.checked':
+            return `Expect ${targetStr} to be checked`;
+        case 'not.be.checked':
+            return `Expect ${targetStr} not to be checked`;
+        case 'have.text':
+            return `Expect ${targetStr} to have text "${arg0}"`;
+        case 'not.have.text':
+            return `Expect ${targetStr} not to have text "${arg0}"`;
+        case 'contain.text':
+            return `Expect ${targetStr} to contain text "${arg0}"`;
+        case 'not.contain.text':
+            return `Expect ${targetStr} not to contain text "${arg0}"`;
+        case 'have.value':
+            return `Expect ${targetStr} to have value "${arg0}"`;
+        case 'not.have.value':
+            return `Expect ${targetStr} not to have value "${arg0}"`;
+        case 'contain.value':
+            return `Expect ${targetStr} to contain value "${arg0}"`;
+        case 'not.contain.value':
+            return `Expect ${targetStr} not to contain value "${arg0}"`;
+        case 'have.class':
+            return `Expect ${targetStr} to have class "${arg0}"`;
+        case 'not.have.class':
+            return `Expect ${targetStr} not to have class "${arg0}"`;
+        case 'have.attr':
+            return args.length >= 2
+                ? `Expect ${targetStr} to have attribute "${arg0}" = "${arg1}"`
+                : `Expect ${targetStr} to have attribute "${arg0}"`;
+        case 'not.have.attr':
+            return `Expect ${targetStr} not to have attribute "${arg0}"`;
+        case 'be.focused':
+            return `Expect ${targetStr} to be focused`;
+        case 'be.selected':
+            return `Expect ${targetStr} to be selected`;
+        case 'be.empty':
+            return `Expect ${targetStr} to be empty`;
+        case 'not.be.empty':
+            return `Expect ${targetStr} not to be empty`;
+        case 'have.length':
+            return `Expect ${targetStr} count to equal ${arg0}`;
+        case 'have.length.greaterThan':
+            return `Expect ${targetStr} count to be greater than ${arg0}`;
+        case 'have.length.lessThan':
+            return `Expect ${targetStr} count to be less than ${arg0}`;
+        case 'have.length.atLeast':
+            return `Expect ${targetStr} count to be at least ${arg0}`;
+        case 'have.length.atMost':
+            return `Expect ${targetStr} count to be at most ${arg0}`;
+        default:
+            return `Expect ${targetStr} to match ${matcher}`;
+    }
+}
+export function formatSemanticBrowser(method, args = []) {
+    const arg0 = args[0] !== undefined ? String(args[0]) : '';
+    switch (method) {
+        case 'shouldContainTitle':
+            return `Expect browser title to contain "${arg0}"`;
+        case 'shouldHaveTitle':
+            return `Expect browser title to be "${arg0}"`;
+        case 'shouldContainUrl':
+            return `Expect browser URL to contain "${arg0}"`;
+        case 'shouldHaveUrl':
+            return `Expect browser URL to be "${arg0}"`;
+        default:
+            return `Expect browser to ${method} "${arg0}"`;
+    }
+}