@testspectra/cli 1.0.4 → 1.0.6

package/src/step/matchers.ts

@@ -0,0 +1,131 @@
+import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from "./types.js";
+
+/**
+ * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
+ * to an actionable WebdriverIO.Element.
+ */
+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.
+ */
+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 "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 $$.
+ */
+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/step/proto.ts

@@ -0,0 +1,163 @@
+import { ElementTarget } from "./types.js";
+import { resolveElement } from "./matchers.js";
+
+declare global {
+  namespace WebdriverIO {
+    interface Element {
+      shouldBeVisible(): Promise<Element>;
+      shouldNotBeVisible(): Promise<Element>;
+      shouldExist(): Promise<Element>;
+      shouldNotExist(): Promise<Element>;
+      shouldBeEnabled(): Promise<Element>;
+      shouldBeDisabled(): Promise<Element>;
+      shouldBeSelected(): Promise<Element>;
+      shouldBeChecked(): Promise<Element>;
+      shouldHaveValue(expectedValue: string): Promise<Element>;
+      shouldContainValue(expectedValue: string): Promise<Element>;
+      shouldHaveText(expectedText: string): Promise<Element>;
+      shouldContainText(expectedText: string): Promise<Element>;
+      shouldHaveClass(className: string): Promise<Element>;
+      shouldHaveAttribute(attributeName: string, expectedValue?: string): Promise<Element>;
+    }
+
+    interface Browser {
+      shouldHaveUrl(expectedUrl: string): Promise<void>;
+      shouldContainUrl(expectedUrl: string): Promise<void>;
+      shouldHaveTitle(expectedTitle: string): Promise<void>;
+      shouldContainTitle(expectedTitle: string): Promise<void>;
+    }
+  }
+
+  interface Promise<T> {
+    shouldBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldNotBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldNotExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeEnabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeDisabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeSelected(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldBeChecked(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+    shouldHaveValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
+    shouldContainValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
+    shouldHaveText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
+    shouldContainText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
+    shouldHaveClass(this: Promise<WebdriverIO.Element>, className: string): Promise<WebdriverIO.Element>;
+    shouldHaveAttribute(this: Promise<WebdriverIO.Element>, attributeName: string, expectedValue?: string): Promise<WebdriverIO.Element>;
+  }
+}
+
+/**
+ * Install direct callable assertion methods onto WebdriverIO browser/element and Promise prototypes.
+ */
+export function installPrototypes() {
+  const elementCommands: Record<string, Function> = {
+    async shouldBeVisible(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeDisplayed();
+      return el;
+    },
+    async shouldNotBeVisible(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).not.toBeDisplayed();
+      return el;
+    },
+    async shouldExist(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toExist();
+      return el;
+    },
+    async shouldNotExist(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).not.toExist();
+      return el;
+    },
+    async shouldBeEnabled(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeEnabled();
+      return el;
+    },
+    async shouldBeDisabled(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeDisabled();
+      return el;
+    },
+    async shouldBeSelected(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeSelected();
+      return el;
+    },
+    async shouldBeChecked(this: any) {
+      const el = await resolveElement(this);
+      await expect(el).toBeSelected();
+      return el;
+    },
+    async shouldHaveValue(this: any, val: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveValue(val);
+      return el;
+    },
+    async shouldContainValue(this: any, val: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveValue(expect.stringContaining(val));
+      return el;
+    },
+    async shouldHaveText(this: any, text: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveText(text);
+      return el;
+    },
+    async shouldContainText(this: any, text: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveText(expect.stringContaining(text));
+      return el;
+    },
+    async shouldHaveClass(this: any, cls: string) {
+      const el = await resolveElement(this);
+      await expect(el).toHaveElementClass(cls);
+      return el;
+    },
+    async shouldHaveAttribute(this: any, name: string, val?: string) {
+      const el = await resolveElement(this);
+      if (val !== undefined) {
+        await expect(el).toHaveAttribute(name, val);
+      } else {
+        await expect(el).toHaveAttribute(name);
+      }
+      return el;
+    },
+  };
+
+  const browserCommands: Record<string, Function> = {
+    async shouldHaveUrl(url: string) {
+      await expect(browser).toHaveUrl(url);
+    },
+    async shouldContainUrl(url: string) {
+      await expect(browser).toHaveUrl(expect.stringContaining(url));
+    },
+    async shouldHaveTitle(title: string) {
+      await expect(browser).toHaveTitle(title);
+    },
+    async shouldContainTitle(title: string) {
+      await expect(browser).toHaveTitle(expect.stringContaining(title));
+    },
+  };
+
+  if (typeof browser !== "undefined" && (browser as any).addCommand) {
+    for (const [name, fn] of Object.entries(elementCommands)) {
+      (browser as any).addCommand(name, fn, true);
+    }
+    for (const [name, fn] of Object.entries(browserCommands)) {
+      (browser as any).addCommand(name, fn, false);
+    }
+  }
+
+  // Attach to Promise.prototype for ChainablePromiseElement unwrapping
+  for (const [name, fn] of Object.entries(elementCommands)) {
+    if (typeof (Promise.prototype as any)[name] !== "function") {
+      (Promise.prototype as any)[name] = async function (this: Promise<any>, ...args: any[]) {
+        const el = await this;
+        return await fn.call(el, ...args);
+      };
+    }
+  }
+}

package/src/step/runner/collection.ts

@@ -0,0 +1,73 @@
+import { MultiElementMatcher } from "../types.js";
+import { executeMultiMatcher } from "../matchers.js";
+import { SingleElementRunner } from "./single.js";
+
+type CollectionAssertion = {
+  matcher: MultiElementMatcher;
+  args: any[];
+};
+
+export class MultiElementRunner implements PromiseLike<void> {
+  private _selector: string;
+  private _assertions: CollectionAssertion[] = [];
+
+  constructor(selector: string) {
+    this._selector = selector;
+  }
+
+  // --- Collection Assertions ---
+
+  should(matcher: MultiElementMatcher, ...args: any[]): this {
+    this._assertions.push({ matcher, args });
+    return this;
+  }
+
+  // --- Item Navigation ---
+
+  eq(index: number): SingleElementRunner {
+    const indexedSelector = `(${this._selector})[${index + 1}]`;
+    return new SingleElementRunner(indexedSelector);
+  }
+
+  first(): SingleElementRunner {
+    return this.eq(0);
+  }
+
+  last(): SingleElementRunner {
+    const indexedSelector = `(${this._selector})[last()]`;
+    return new SingleElementRunner(indexedSelector);
+  }
+
+  // --- Iteration Callback ---
+
+  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 ---
+
+  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/step/runner/single.ts

@@ -0,0 +1,166 @@
+import { SingleElementMatcher, ElementTarget } from "../types.js";
+import { executeSingleMatcher, resolveElement } from "../matchers.js";
+
+type AssertionItem = {
+  target?: ElementTarget;
+  matcher: SingleElementMatcher;
+  args: any[];
+};
+
+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 ---
+
+  click(): this {
+    const target = this.requireTarget("click");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.click();
+    };
+    return this;
+  }
+
+  doubleClick(): this {
+    const target = this.requireTarget("doubleClick");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.doubleClick();
+    };
+    return this;
+  }
+
+  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;
+  }
+
+  type(value: string, options?: { clearFirst?: boolean }): 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;
+  }
+
+  clear(): this {
+    const target = this.requireTarget("clear");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.clearValue();
+    };
+    return this;
+  }
+
+  select(value: string): this {
+    const target = this.requireTarget("select");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.selectByVisibleText(value);
+    };
+    return this;
+  }
+
+  hover(): this {
+    const target = this.requireTarget("hover");
+    this._action = async () => {
+      const el = await resolveElement(target);
+      await el.moveTo();
+    };
+    return this;
+  }
+
+  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 ---
+
+  should(matcher: SingleElementMatcher, ...args: any[]): this;
+  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 ---
+
+  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;
+    }
+  }
+
+  private requireTarget(actionName: string): ElementTarget {
+    if (!this._target) {
+      throw new Error(`Cannot execute '${actionName}' without specifying an element target.`);
+    }
+    return this._target;
+  }
+}