@testspectra/matchers 1.0.69 → 1.1.0

package/dist/runner/collection.js

@@ -1,23 +1,25 @@
-import { executeMultiMatcher } from "../matchers.js";
-import { SingleElementRunner } from "./single.js";
+import { executeMultiMatcher } from '../matchers.js';
+import { trackCommand } from '../reporter.js';
+import { SingleElementRunner } from './single.js';
 /**
  * Fluent assertion, filtering, and iteration runner for multi-element collections.
  *
- * Implements `PromiseLike<void>`, allowing assertions across matching elements,
+ * Implements `PromiseLike<void>` and `CollectionReceiverAssertions<MultiElementRunner>`,
+ * allowing assertions across matching elements,
  * array index access (`.eq()`, `.first()`, `.last()`), and sequential iteration (`.each()`).
  *
  * @example
  * ```ts
  * // Assert collection size
- * await Spectra.getAll(".cart-item").should("have.length", 3);
+ * await Spectra.getAll(".cart-item").shouldHaveLength(3);
  *
  * // Target specific element from collection
  * await Spectra.getAll(".todo-item").first().click();
- * await Spectra.getAll(".todo-item").eq(2).should("have.text", "Buy Milk");
+ * await Spectra.getAll(".todo-item").eq(2).shouldHaveText("Buy Milk");
  *
  * // Iteration
  * await Spectra.getAll(".nav-link").each(async (link, i) => {
- *   await link.should("be.visible");
+ *   await link.shouldBeVisible();
  * });
  * ```
  */
@@ -27,22 +29,46 @@ export class MultiElementRunner {
     constructor(selector) {
         this._selector = selector;
     }
+    _pushAssertion(matcher, args = []) {
+        this._assertions.push({ matcher, args });
+        return this;
+    }
     // --- Collection Assertions ---
     /**
-     * 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.
+     * Asserts that the collection contains exactly `count` elements.
      */
-    should(matcher, ...args) {
-        this._assertions.push({ matcher, args });
-        return this;
+    shouldHaveLength(count) {
+        return this._pushAssertion('have.length', [count]);
+    }
+    /**
+     * Asserts that the collection does not contain `count` elements.
+     */
+    shouldNotHaveLength(count) {
+        return this._pushAssertion('not.have.length', [count]);
+    }
+    /**
+     * Asserts that the collection contains more than `min` elements.
+     */
+    shouldHaveLengthGreaterThan(min) {
+        return this._pushAssertion('have.length.greaterThan', [min]);
+    }
+    /**
+     * Asserts that the collection contains less than `max` elements.
+     */
+    shouldHaveLengthLessThan(max) {
+        return this._pushAssertion('have.length.lessThan', [max]);
+    }
+    /**
+     * Asserts that the collection is empty (contains 0 elements).
+     */
+    shouldBeEmpty() {
+        return this._pushAssertion('be.empty');
+    }
+    /**
+     * Asserts that the collection is not empty (contains at least 1 element).
+     */
+    shouldNotBeEmpty() {
+        return this._pushAssertion('not.be.empty');
     }
     // --- Item Navigation ---
     /**
@@ -56,8 +82,16 @@ export class MultiElementRunner {
      * @returns `SingleElementRunner` for the indexed element.
      */
     eq(index) {
-        const indexedSelector = `(${this._selector})[${index + 1}]`;
-        return new SingleElementRunner(indexedSelector);
+        const targetSelector = `${this._selector}[${index}]`;
+        const elPromise = (async () => {
+            if (typeof $$ !== 'undefined') {
+                const elements = await $$(this._selector);
+                return elements[index];
+            }
+            return { selector: targetSelector };
+        })();
+        elPromise.selector = targetSelector;
+        return new SingleElementRunner(elPromise);
     }
     /**
      * Returns a `SingleElementRunner` targeting the first element in the collection (`index = 0`).
@@ -76,13 +110,22 @@ 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 indexedSelector = `(${this._selector})[last()]`;
-        return new SingleElementRunner(indexedSelector);
+        const targetSelector = `${this._selector}[last()]`;
+        const elPromise = (async () => {
+            if (typeof $$ !== 'undefined') {
+                const elements = await $$(this._selector);
+                const arr = Array.isArray(elements) ? elements : await elements;
+                return arr[arr.length - 1];
+            }
+            return { selector: targetSelector };
+        })();
+        elPromise.selector = targetSelector;
+        return new SingleElementRunner(elPromise);
     }
     // --- Iteration Callback ---
     /**
@@ -92,7 +135,7 @@ export class MultiElementRunner {
      * @example
      * ```ts
      * await Spectra.getAll(".checkbox").each(async (item, index) => {
-     *   await item.should("be.visible");
+     *   await item.shouldBeVisible();
      * });
      * ```
      */
@@ -112,7 +155,16 @@ export class MultiElementRunner {
     async then(onfulfilled, onrejected) {
         try {
             for (const assert of this._assertions) {
-                await executeMultiMatcher(this._selector, assert.matcher, assert.args);
+                const payload = {
+                    type: 'assertion',
+                    key: assert.matcher,
+                    target: this._selector,
+                    args: assert.args,
+                    isCollection: true,
+                };
+                await trackCommand('assertion', payload, async () => {
+                    await executeMultiMatcher(this._selector, assert.matcher, assert.args);
+                });
             }
             const res = (onfulfilled ? await onfulfilled() : undefined);
             return res;

package/dist/runner/single.d.ts

@@ -1,29 +1,30 @@
-import { SingleElementMatcher, ElementTarget, TypeOptions } from "../types.js";
+import { ElementReceiverAssertions, ElementTarget, TypeOptions } from '../types.js';
 /**
  * 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 declare class SingleElementRunner implements PromiseLike<void> {
+export declare class SingleElementRunner implements PromiseLike<void>, ElementReceiverAssertions<SingleElementRunner> {
     private _target;
     private _action;
+    private _actionPayload;
     private _assertions;
-    constructor(target?: ElementTarget, action?: () => Promise<any>);
+    constructor(target?: ElementTarget, action?: () => Promise<any>, actionPayload?: any);
     /**
      * Clicks on the target element.
      *
@@ -110,32 +111,122 @@ export declare class SingleElementRunner implements PromiseLike<void> {
      */
     waitForElement(timeoutMs?: number): 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.
+     * Performs a right-click (context menu) interaction on the target element.
      */
-    should(matcher: SingleElementMatcher, ...args: any[]): this;
+    rightClick(): 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.
+     * Drags the target element and drops it onto the specified destination element.
+     */
+    dragDrop(destination: ElementTarget): this;
+    /**
+     * Scrolls the target element into view.
+     */
+    scrollIntoView(): this;
+    private _pushAssertion;
+    /**
+     * Asserts that the target element is displayed and visible to the user.
+     */
+    shouldBeVisible(): this;
+    /**
+     * Asserts that the target element is not displayed or hidden from view.
+     */
+    shouldNotBeVisible(): this;
+    /**
+     * Asserts that the target element exists in the DOM.
+     */
+    shouldExist(): this;
+    /**
+     * Asserts that the target element does not exist in the DOM.
+     */
+    shouldNotExist(): this;
+    /**
+     * Asserts that the target element is clickable.
+     */
+    shouldBeClickable(): this;
+    /**
+     * Asserts that the target element is not clickable.
+     */
+    shouldNotBeClickable(): this;
+    /**
+     * Asserts that the target element is enabled (not disabled).
+     */
+    shouldBeEnabled(): this;
+    /**
+     * Asserts that the target element is disabled.
+     */
+    shouldBeDisabled(): this;
+    /**
+     * Asserts that the target checkbox or radio element is checked.
+     */
+    shouldBeChecked(): this;
+    /**
+     * Asserts that the target checkbox or radio element is not checked.
+     */
+    shouldNotBeChecked(): this;
+    /**
+     * Asserts that the target element currently has focus.
+     */
+    shouldBeFocused(): this;
+    /**
+     * Asserts that the target element does not have focus.
+     */
+    shouldNotBeFocused(): this;
+    /**
+     * Asserts that the target element has exact inner text matching the expected value.
+     */
+    shouldHaveText(expected: string | RegExp): this;
+    /**
+     * Asserts that the target element does not have inner text matching the expected value.
+     */
+    shouldNotHaveText(expected: string | RegExp): this;
+    /**
+     * Asserts that the target element's text contains the given substring.
+     */
+    shouldContainText(substring: string): this;
+    /**
+     * Asserts that the target element's text does not contain the given substring.
+     */
+    shouldNotContainText(substring: string): this;
+    /**
+     * Asserts that the target input element has the exact expected value.
+     */
+    shouldHaveValue(value: string): this;
+    /**
+     * Asserts that the target input element does not have the expected value.
+     */
+    shouldNotHaveValue(value: string): this;
+    /**
+     * Asserts that the target input element's value contains the given substring.
+     */
+    shouldContainValue(substring: string): this;
+    /**
+     * Asserts that the target input element's value does not contain the given substring.
+     */
+    shouldNotContainValue(substring: string): this;
+    /**
+     * Asserts that the target element has the specified HTML attribute and optional value.
+     */
+    shouldHaveAttribute(name: string, value?: string): this;
+    /**
+     * Asserts that the target element does not have the specified HTML attribute.
+     */
+    shouldNotHaveAttribute(name: string): this;
+    /**
+     * Asserts that the target element has the specified CSS class.
+     */
+    shouldHaveClass(className: string): this;
+    /**
+     * Asserts that the target element does not have the specified CSS class.
+     */
+    shouldNotHaveClass(className: string): this;
+    /**
+     * Asserts that the target element has the specified computed CSS property value.
+     */
+    shouldHaveCss(property: string, value: string): this;
+    /**
+     * Asserts that the target element does not have the specified computed CSS property value.
      */
-    should(target: ElementTarget, matcher: SingleElementMatcher, ...args: any[]): this;
+    shouldNotHaveCss(property: string, value: string): this;
     /**
      * Standard Promise `then` implementation.
      * Executes queued action first (if any), followed sequentially by all queued assertions.