@testspectra/matchers 1.0.70 → 1.1.0-rc.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,13 +115,22 @@ 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) {
-                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;
     }
@@ -120,10 +144,14 @@ 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();
+            if (typeof el.clearValue === 'function')
+                await el.clearValue();
+            else if (typeof el.clear === 'function')
+                await el.clear();
         };
         return this;
     }
@@ -138,27 +166,35 @@ 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);
+            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.
      */
     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();
+            if (typeof el.moveTo === 'function')
+                await el.moveTo();
+            else if (typeof el.hover === 'function')
+                await el.hover();
         };
         return this;
     }
@@ -173,40 +209,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 +434,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/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}"`;
+    }
+}