@testspectra/matchers 1.0.69 → 1.1.0

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "@testspectra/matchers",
-  "version": "1.0.69",
-  "description": "Cross-platform action commands and direct callable assertion matchers for TestSpectra",
+  "version": "1.1.0",
+  "description": "Canonical TypeScript contracts and ambient type definitions for TestSpectra",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc -w",
-    "prepublishOnly": "npm run build"
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
-    "@wdio/globals": "^9.2.8",
-    "@wdio/mocha-framework": "^9.2.8",
-    "webdriverio": "^9.2.8",
-    "typescript": "^5.4.5"
+    "typescript": "^5.6.3"
   },
   "type": "module",
-  "license": "MIT"
-}
+  "license": "SEE LICENSE IN LICENSE.md",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -2,27 +2,8 @@
  * @packageDocumentation
  * # @testspectra/matchers
  *
- * Cross-platform action commands, fluent runners, and callable assertion matchers for TestSpectra.
- *
- * ## Features:
- * - **`Spectra`**: Unified automation API (`Spectra.get()`, `Spectra.getAll()`, `Spectra.click()`, `Spectra.type()`, etc.)
- * - **`SingleElementRunner`**: Fluent interaction & assertion runner for single element targets
- * - **`MultiElementRunner`**: Fluent assertion & traversal runner for multi-element collections
- * - **Callable Matchers**: Ambient prototypes for WebdriverIO Element & Browser (`.shouldBeVisible()`, `.shouldHaveText()`, etc.)
- *
- * @example
- * ```ts
- * import { Spectra } from "@testspectra/matchers";
- *
- * await Spectra.get("#login-btn").click().should("not.be.visible");
- * await Spectra.getAll(".list-item").should("have.length.greaterThan", 0);
- * ```
+ * Canonical TypeScript contracts, action/assertion types, and ambient type definitions for TestSpectra.
  */
 
-export * from "./types.js";
-export * from "./matchers.js";
-export * from "./runner/single.js";
-export * from "./runner/collection.js";
-export * from "./spectra.js";
-export * from "./proto.js";
-
+export * from './types.js';
+export * from './proto.js';

package/src/proto.ts

@@ -1,438 +1,27 @@
-import { ElementTarget } from "./types.js";
-import { resolveElement } from "./matchers.js";
+import type { SpectraBrowserBridge, SpectraStatic } from './types.js';
 
 declare global {
-  namespace WebdriverIO {
-    interface Element {
-      /**
-       * Asserts that the element is displayed on the screen and visible to the user.
-       *
-       * @example
-       * ```ts
-       * await LoginPage.submitButton.shouldBeVisible();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldBeVisible(): Promise<Element>;
-
-      /**
-       * Asserts that the element is NOT displayed or is hidden from view.
-       *
-       * @example
-       * ```ts
-       * await LoginPage.errorMessage.shouldNotBeVisible();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldNotBeVisible(): Promise<Element>;
-
-      /**
-       * Asserts that the element exists in the DOM/UI hierarchy.
-       *
-       * @example
-       * ```ts
-       * await LoginPage.rememberMeCheckbox.shouldExist();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldExist(): Promise<Element>;
-
-      /**
-       * Asserts that the element does NOT exist in the DOM/UI hierarchy.
-       *
-       * @example
-       * ```ts
-       * await LoginPage.loadingSpinner.shouldNotExist();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldNotExist(): Promise<Element>;
-
-      /**
-       * Asserts that the element is enabled for interaction.
-       *
-       * @example
-       * ```ts
-       * await LoginPage.loginButton.shouldBeEnabled();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldBeEnabled(): Promise<Element>;
-
-      /**
-       * Asserts that the element is disabled (cannot be interacted with).
-       *
-       * @example
-       * ```ts
-       * await LoginPage.disabledSubmit.shouldBeDisabled();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldBeDisabled(): Promise<Element>;
-
-      /**
-       * Asserts that the form element (radio button, checkbox, option) is selected.
-       *
-       * @example
-       * ```ts
-       * await SettingsPage.darkModeRadio.shouldBeSelected();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldBeSelected(): Promise<Element>;
-
-      /**
-       * Asserts that the checkbox or radio element is checked.
-       *
-       * @example
-       * ```ts
-       * await SettingsPage.termsCheckbox.shouldBeChecked();
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldBeChecked(): Promise<Element>;
-
-      /**
-       * Asserts that the input element has the exact given value.
-       *
-       * @param expectedValue - The exact expected value.
-       * @example
-       * ```ts
-       * await LoginPage.usernameInput.shouldHaveValue("admin@test.com");
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldHaveValue(expectedValue: string): Promise<Element>;
-
-      /**
-       * Asserts that the input element's value contains the given substring.
-       *
-       * @param expectedValue - Substring expected to be present in the value.
-       * @example
-       * ```ts
-       * await LoginPage.tokenInput.shouldContainValue("JWT_");
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldContainValue(expectedValue: string): Promise<Element>;
-
-      /**
-       * Asserts that the element's text content matches the exact expected text.
-       *
-       * @param expectedText - The exact expected text content.
-       * @example
-       * ```ts
-       * await LoginPage.headerTitle.shouldHaveText("Welcome to TestSpectra");
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldHaveText(expectedText: string): Promise<Element>;
-
-      /**
-       * Asserts that the element's text content contains the expected substring.
-       *
-       * @param expectedText - Substring expected to be within the element text.
-       * @example
-       * ```ts
-       * await LoginPage.welcomeBanner.shouldContainText("Welcome");
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldContainText(expectedText: string): Promise<Element>;
-
-      /**
-       * Asserts that the element has the specified CSS class.
-       *
-       * @param className - Expected CSS class name.
-       * @example
-       * ```ts
-       * await NavigationBar.homeTab.shouldHaveClass("is-active");
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldHaveClass(className: string): Promise<Element>;
-
-      /**
-       * Asserts that the element has the specified attribute, optionally checking its exact value.
-       *
-       * @param attributeName - Name of the attribute (e.g. `aria-label`, `disabled`, `href`).
-       * @param expectedValue - Optional expected value of the attribute.
-       * @example
-       * ```ts
-       * await NavigationBar.logoLink.shouldHaveAttribute("href", "/dashboard");
-       * await NavigationBar.cartButton.shouldHaveAttribute("aria-expanded");
-       * ```
-       * @returns The element instance for chaining.
-       */
-      shouldHaveAttribute(attributeName: string, expectedValue?: string): Promise<Element>;
-    }
-
-    /**
-     * Optional settings for HTTP network interception responses.
-     */
-    export interface InterceptFixtureOptions {
-      /** HTTP status code to return in the mocked response (default: 200) */
-      statusCode?: number;
-      /** Custom HTTP response headers */
-      headers?: Record<string, string>;
-    }
-
-    /**
-     * Structured mock payload object with optional status code and headers.
-     */
-    export interface InterceptFixtureObject<TData = unknown> {
-      /** HTTP status code */
-      statusCode?: number;
-      /** Response body payload */
-      body: TData;
-      /** Custom HTTP response headers */
-      headers?: Record<string, string>;
-    }
-
-    /**
-     * Input payload for API mocking: JSON object, string, or structured fixture object.
-     */
-    export type InterceptInput<TData = unknown> =
-      | InterceptFixtureObject<TData>
-      | TData
-      | string;
+  /**
+   * The global TestSpectra static automation and assertion instance.
+   */
+  var Spectra: SpectraStatic;
+
+  /**
+   * The global TestSpectra browser bridge instance.
+   */
+  var browser: SpectraBrowserBridge;
+
+  /**
+   * Global fixture store injected by TestSpectra runner.
+   */
+  var Fixture: Record<string, any>;
+
+  /**
+   * Global step library injected by TestSpectra runner.
+   */
+  var Step: Record<string, any>;
 
-    interface Mock {
-      /**
-       * Dynamically set or change the fixture response for this mock instance.
-       * Supports fixture file paths, structured `{ statusCode, body, headers }` objects, or raw data.
-       *
-       * @param fixture - Data payload or Fixture reference.
-       * @param options - Optional status code and header overrides.
-       * @example
-       * ```ts
-       * const mock = await browser.intercept("/api/user", "GET");
-       * await mock.respondWith({ name: "Admin", role: "superadmin" });
-       * ```
-       */
-      respondWith<TData = unknown>(
-        fixture: InterceptInput<TData>,
-        options?: InterceptFixtureOptions
-      ): Promise<void>;
-    }
-
-    interface Browser {
-      /**
-       * Intercepts and mocks network API requests matching the specified endpoint.
-       * Supports automatic base URL resolution and TestSpectra JSON Fixtures.
-       *
-       * @param path - URL path or route to intercept (e.g. `"/api/users"` or `"https://api.example.com/v1/*"`).
-       * @param method - HTTP request method (`"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, `"PATCH"`).
-       * @param fixture - Optional initial response payload or Fixture object.
-       * @param options - Optional status code and header configuration.
-       * @example
-       * ```ts
-       * // Intercept with JSON Fixture
-       * await browser.intercept("/api/status", "GET", Fixture.userData);
-       *
-       * // Intercept with custom payload & status code
-       * await browser.intercept("/api/auth/login", "POST", { token: "xyz" }, { statusCode: 200 });
-       * ```
-       * @returns `Mock` instance allowing dynamic response modification.
-       */
-      intercept<TData = unknown>(
-        path: string,
-        method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH",
-        fixture?: InterceptInput<TData>,
-        options?: InterceptFixtureOptions
-      ): Promise<Mock>;
-
-      /**
-       * Asserts that the current browser page URL exactly matches the expected URL.
-       *
-       * @param expectedUrl - The exact URL expected.
-       * @example
-       * ```ts
-       * await browser.shouldHaveUrl("https://app.example.com/dashboard");
-       * ```
-       */
-      shouldHaveUrl(expectedUrl: string): Promise<void>;
-
-      /**
-       * Asserts that the current browser page URL contains the given substring.
-       *
-       * @param expectedUrl - Substring expected in the current URL.
-       * @example
-       * ```ts
-       * await browser.shouldContainUrl("/dashboard");
-       * ```
-       */
-      shouldContainUrl(expectedUrl: string): Promise<void>;
-
-      /**
-       * Asserts that the current browser page title matches the expected title.
-       *
-       * @param expectedTitle - The exact title expected.
-       * @example
-       * ```ts
-       * await browser.shouldHaveTitle("Dashboard - TestSpectra");
-       * ```
-       */
-      shouldHaveTitle(expectedTitle: string): Promise<void>;
-
-      /**
-       * Asserts that the current browser page title contains the expected substring.
-       *
-       * @param expectedTitle - Substring expected in the title.
-       * @example
-       * ```ts
-       * await browser.shouldContainTitle("Dashboard");
-       * ```
-       */
-      shouldContainTitle(expectedTitle: string): Promise<void>;
-    }
-  }
-
-  interface Promise<T> {
-    /** Asserts that the element promise resolves to a visible element. */
-    shouldBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to a hidden/non-visible element. */
-    shouldNotBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an existing element in the DOM. */
-    shouldExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an element that does not exist in the DOM. */
-    shouldNotExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an enabled element. */
-    shouldBeEnabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to a disabled element. */
-    shouldBeDisabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to a selected element. */
-    shouldBeSelected(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to a checked checkbox or radio. */
-    shouldBeChecked(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an element with the exact value. */
-    shouldHaveValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an element whose value contains the substring. */
-    shouldContainValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an element with the exact text content. */
-    shouldHaveText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an element whose text contains the substring. */
-    shouldContainText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an element having the CSS class. */
-    shouldHaveClass(this: Promise<WebdriverIO.Element>, className: string): Promise<WebdriverIO.Element>;
-    /** Asserts that the element promise resolves to an element having the attribute. */
-    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);
-      };
-    }
+  namespace WebdriverIO {
+    interface Browser extends SpectraBrowserBridge {}
   }
 }