@testspectra/matchers 1.0.69 → 1.1.0

package/tsconfig.json

@@ -9,9 +9,9 @@
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "types": ["node", "@wdio/globals/types", "@wdio/mocha-framework"],
+    "types": ["node"],
     "forceConsistentCasingInFileNames": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "src/**/__tests__/**"]
 }

package/src/matchers.ts

@@ -1,146 +0,0 @@
-import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from "./types.js";
-
-/**
- * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
- * to an actionable WebdriverIO.Element.
- *
- * @param target - Selector string or element instance.
- * @returns Resolved WebdriverIO.Element instance.
- */
-export async function resolveElement(target: ElementTarget): Promise<WebdriverIO.Element> {
-  if (typeof target === "string") {
-    const el = await $(target);
-    return el as unknown as WebdriverIO.Element;
-  }
-  const el = await (target as any);
-  return el as unknown as WebdriverIO.Element;
-}
-
-/**
- * Executes a single element matcher against the WebdriverIO browser / element context.
- *
- * @param target - Optional element target (not required for browser-level assertions).
- * @param matcher - Single element matcher string.
- * @param args - Arguments passed to the matcher.
- */
-export async function executeSingleMatcher(
-  target: ElementTarget | undefined,
-  matcher: SingleElementMatcher,
-  args: any[]
-): Promise<void> {
-  const isBrowserLevel =
-    matcher === "have.url" ||
-    matcher === "contain.url" ||
-    matcher === "have.title" ||
-    matcher === "contain.title";
-
-  if (isBrowserLevel) {
-    const expected = args[0];
-    switch (matcher) {
-      case "have.url":
-        await expect(browser).toHaveUrl(expected);
-        break;
-      case "contain.url":
-        await expect(browser).toHaveUrl(expect.stringContaining(expected));
-        break;
-      case "have.title":
-        await expect(browser).toHaveTitle(expected);
-        break;
-      case "contain.title":
-        await expect(browser).toHaveTitle(expect.stringContaining(expected));
-        break;
-    }
-    return;
-  }
-
-  if (!target) {
-    throw new Error(`Assertion matcher '${matcher}' requires an element target.`);
-  }
-
-  const el = await resolveElement(target);
-
-  switch (matcher) {
-    case "be.visible":
-      await expect(el).toBeDisplayed();
-      break;
-    case "not.be.visible":
-      await expect(el).not.toBeDisplayed();
-      break;
-    case "exist":
-      await expect(el).toExist();
-      break;
-    case "not.exist":
-      await expect(el).not.toExist();
-      break;
-    case "be.enabled":
-      await expect(el).toBeEnabled();
-      break;
-    case "be.disabled":
-      await expect(el).toBeDisabled();
-      break;
-    case "be.checked":
-    case "be.selected":
-      await expect(el).toBeSelected();
-      break;
-    case "not.be.checked":
-    case "not.be.selected":
-      await expect(el).not.toBeSelected();
-      break;
-    case "have.value":
-      await expect(el).toHaveValue(args[0]);
-      break;
-    case "contain.value":
-      await expect(el).toHaveValue(expect.stringContaining(args[0]));
-      break;
-    case "have.text":
-      await expect(el).toHaveText(args[0]);
-      break;
-    case "contain.text":
-      await expect(el).toHaveText(expect.stringContaining(args[0]));
-      break;
-    case "have.class":
-      await expect(el).toHaveElementClass(args[0]);
-      break;
-    case "have.attr":
-      if (args.length >= 2) {
-        await expect(el).toHaveAttribute(args[0], args[1]);
-      } else {
-        await expect(el).toHaveAttribute(args[0]);
-      }
-      break;
-    default:
-      throw new Error(`Unsupported matcher: ${matcher}`);
-  }
-}
-
-/**
- * Executes a multi-element collection matcher against WebdriverIO $$.
- *
- * @param selector - CSS/XPath selector for the collection.
- * @param matcher - Multi-element matcher string.
- * @param args - Expected values or count limits.
- */
-export async function executeMultiMatcher(
-  selector: string,
-  matcher: MultiElementMatcher,
-  args: any[]
-): Promise<void> {
-  const elements = await $$(selector);
-
-  switch (matcher) {
-    case "have.length":
-      await expect(elements).toBeElementsArrayOfSize(args[0]);
-      break;
-    case "have.length.greaterThan":
-      await expect(elements).toBeElementsArrayOfSize({ gte: args[0] + 1 });
-      break;
-    case "be.empty":
-      await expect(elements).toBeElementsArrayOfSize(0);
-      break;
-    case "exist":
-      await expect(elements).toBeElementsArrayOfSize({ gte: 1 });
-      break;
-    default:
-      throw new Error(`Unsupported multi-element matcher: ${matcher}`);
-  }
-}

package/src/runner/collection.ts

@@ -1,153 +0,0 @@
-import { MultiElementMatcher } from "../types.js";
-import { executeMultiMatcher } from "../matchers.js";
-import { SingleElementRunner } from "./single.js";
-
-/**
- * Representation of a queued assertion against an element collection.
- */
-type CollectionAssertion = {
-  matcher: MultiElementMatcher;
-  args: any[];
-};
-
-/**
- * Fluent assertion, filtering, and iteration runner for multi-element collections.
- *
- * Implements `PromiseLike<void>`, 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);
- *
- * // Target specific element from collection
- * await Spectra.getAll(".todo-item").first().click();
- * await Spectra.getAll(".todo-item").eq(2).should("have.text", "Buy Milk");
- *
- * // Iteration
- * await Spectra.getAll(".nav-link").each(async (link, i) => {
- *   await link.should("be.visible");
- * });
- * ```
- */
-export class MultiElementRunner implements PromiseLike<void> {
-  private _selector: string;
-  private _assertions: CollectionAssertion[] = [];
-
-  constructor(selector: string) {
-    this._selector = selector;
-  }
-
-  // --- 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.
-   */
-  should(matcher: MultiElementMatcher, ...args: any[]): this {
-    this._assertions.push({ matcher, args });
-    return this;
-  }
-
-  // --- Item Navigation ---
-
-  /**
-   * Returns a `SingleElementRunner` targeting the element at the specified 0-based index.
-   *
-   * @param index - 0-based index of the element within the matched collection.
-   * @example
-   * ```ts
-   * await Spectra.getAll("li.menu-item").eq(1).click();
-   * ```
-   * @returns `SingleElementRunner` for the indexed element.
-   */
-  eq(index: number): SingleElementRunner {
-    const indexedSelector = `(${this._selector})[${index + 1}]`;
-    return new SingleElementRunner(indexedSelector);
-  }
-
-  /**
-   * Returns a `SingleElementRunner` targeting the first element in the collection (`index = 0`).
-   *
-   * @example
-   * ```ts
-   * await Spectra.getAll(".result-item").first().click();
-   * ```
-   * @returns `SingleElementRunner` for the first element.
-   */
-  first(): SingleElementRunner {
-    return this.eq(0);
-  }
-
-  /**
-   * Returns a `SingleElementRunner` targeting the last element in the collection.
-   *
-   * @example
-   * ```ts
-   * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
-   * ```
-   * @returns `SingleElementRunner` for the last element.
-   */
-  last(): SingleElementRunner {
-    const indexedSelector = `(${this._selector})[last()]`;
-    return new SingleElementRunner(indexedSelector);
-  }
-
-  // --- Iteration Callback ---
-
-  /**
-   * Iterates asynchronously through every matched element in the collection sequentially.
-   *
-   * @param callback - Async function called for each element with `(runner, index)`.
-   * @example
-   * ```ts
-   * await Spectra.getAll(".checkbox").each(async (item, index) => {
-   *   await item.should("be.visible");
-   * });
-   * ```
-   */
-  async each(
-    callback: (el: SingleElementRunner, index: number) => Promise<void>
-  ): Promise<void> {
-    const elements = await $$(this._selector);
-    const count = await (elements as any).length;
-    for (let i = 0; i < count; i++) {
-      const runner = this.eq(i);
-      await callback(runner, i);
-    }
-  }
-
-  // --- Execution when awaited ---
-
-  /**
-   * Standard Promise `then` implementation.
-   * Executes all queued collection assertions sequentially when awaited.
-   */
-  async then<TResult1 = void, TResult2 = never>(
-    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
-    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
-  ): Promise<TResult1 | TResult2> {
-    try {
-      for (const assert of this._assertions) {
-        await executeMultiMatcher(this._selector, assert.matcher, assert.args);
-      }
-      const res = (onfulfilled ? await onfulfilled() : undefined) as TResult1;
-      return res;
-    } catch (err) {
-      if (onrejected) {
-        return onrejected(err);
-      }
-      throw err;
-    }
-  }
-}
-

package/src/runner/single.ts

@@ -1,301 +0,0 @@
-import { SingleElementMatcher, ElementTarget, TypeOptions } from "../types.js";
-import { executeSingleMatcher, resolveElement } from "../matchers.js";
-
-/**
- * Representation of a queued assertion against an element or page.
- */
-type AssertionItem = {
-  target?: ElementTarget;
-  matcher: SingleElementMatcher;
-  args: any[];
-};
-
-/**
- * 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.
- *
- * @example
- * ```ts
- * // Direct action + chained assertion
- * await Spectra.get("#submit-btn")
- *   .click()
- *   .should("not.be.visible");
- *
- * // Query + multiple assertions
- * await Spectra.get(LoginPage.usernameInput)
- *   .should("be.visible")
- *   .should("be.enabled")
- *   .should("have.value", "admin");
- * ```
- */
-export class SingleElementRunner implements PromiseLike<void> {
-  private _target: ElementTarget | undefined;
-  private _action: (() => Promise<any>) | null = null;
-  private _assertions: AssertionItem[] = [];
-
-  constructor(target?: ElementTarget, action?: () => Promise<any>) {
-    this._target = target;
-    this._action = action || null;
-  }
-
-  // --- Chained Actions on current target ---
-
-  /**
-   * Clicks on the target element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get("#login-btn").click();
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  click(): this {
-    const target = this.requireTarget("click");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      await el.click();
-    };
-    return this;
-  }
-
-  /**
-   * Double-clicks on the target element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get(".file-row").doubleClick();
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  doubleClick(): this {
-    const target = this.requireTarget("doubleClick");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      await el.doubleClick();
-    };
-    return this;
-  }
-
-  /**
-   * Performs a long-press touch or hold gesture on the target element.
-   *
-   * @param durationMs - Duration in milliseconds to hold (default: 1000).
-   * @example
-   * ```ts
-   * await Spectra.get("#context-menu-trigger").longPress(1500);
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  longPress(durationMs = 1000): this {
-    const target = this.requireTarget("longPress");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      if (typeof (el as any).touchAction === "function") {
-        await (el as any).touchAction([
-          { action: "longPress", ms: durationMs },
-          { action: "release" },
-        ]);
-      } else {
-        await el.click();
-      }
-    };
-    return this;
-  }
-
-  /**
-   * Types string value into the target input element.
-   *
-   * @param value - Text string to type into the element.
-   * @param options - Optional typing options (e.g. `clearFirst: true`).
-   * @example
-   * ```ts
-   * await Spectra.get("#search-input").type("iPhone 15", { clearFirst: true });
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  type(value: string, options?: TypeOptions): this {
-    const target = this.requireTarget("type");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      if (options?.clearFirst) {
-        await el.clearValue();
-      }
-      await el.setValue(value);
-    };
-    return this;
-  }
-
-  /**
-   * Clears the current value of the target input element.
-   *
-   * @example
-   * ```ts
-   * await Spectra.get("#search-input").clear();
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  clear(): this {
-    const target = this.requireTarget("clear");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      await el.clearValue();
-    };
-    return this;
-  }
-
-  /**
-   * Selects an option from a `<select>` dropdown by its visible text.
-   *
-   * @param value - Visible text of the option to select.
-   * @example
-   * ```ts
-   * await Spectra.get("#country-select").select("United States");
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  select(value: string): this {
-    const target = this.requireTarget("select");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      await el.selectByVisibleText(value);
-    };
-    return this;
-  }
-
-  /**
-   * Moves the mouse cursor over the target element (hover).
-   *
-   * @example
-   * ```ts
-   * await Spectra.get("#dropdown-menu-trigger").hover();
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  hover(): this {
-    const target = this.requireTarget("hover");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      await el.moveTo();
-    };
-    return this;
-  }
-
-  /**
-   * Waits for the target element to become displayed in the DOM.
-   *
-   * @param timeoutMs - Maximum duration in milliseconds to wait (default: 10000).
-   * @example
-   * ```ts
-   * await Spectra.get("#modal-dialog").waitForElement(5000);
-   * ```
-   * @returns Current runner instance for method chaining.
-   */
-  waitForElement(timeoutMs = 10000): this {
-    const target = this.requireTarget("waitForElement");
-    this._action = async () => {
-      const el = await resolveElement(target);
-      await el.waitForDisplayed({ timeout: timeoutMs });
-    };
-    return this;
-  }
-
-  // --- Fluent Assertion Matchers ---
-
-  /**
-   * 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;
-
-  should(a: ElementTarget | SingleElementMatcher, b?: any, ...rest: any[]): this {
-    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 as ElementTarget,
-        matcher: b as SingleElementMatcher,
-        args: rest,
-      });
-    } else {
-      // Form: should(matcher, ...args) -> on current target
-      this._assertions.push({
-        target: this._target,
-        matcher: a as SingleElementMatcher,
-        args: b !== undefined ? [b, ...rest] : rest,
-      });
-    }
-    return this;
-  }
-
-  // --- Execution when awaited ---
-
-  /**
-   * Standard Promise `then` implementation.
-   * Executes queued action first (if any), followed sequentially by all queued assertions.
-   */
-  async then<TResult1 = void, TResult2 = never>(
-    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null,
-    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
-  ): Promise<TResult1 | TResult2> {
-    try {
-      if (this._action) {
-        await this._action();
-      }
-      for (const assert of this._assertions) {
-        await executeSingleMatcher(assert.target, assert.matcher, assert.args);
-      }
-      const res = (onfulfilled ? await onfulfilled() : undefined) as TResult1;
-      return res;
-    } catch (err) {
-      if (onrejected) {
-        return onrejected(err);
-      }
-      throw err;
-    }
-  }
-
-  /**
-   * Helper that throws an error if an action is called without a defined target.
-   */
-  private requireTarget(actionName: string): ElementTarget {
-    if (!this._target) {
-      throw new Error(`Cannot execute '${actionName}' without specifying an element target.`);
-    }
-    return this._target;
-  }
-}
-