@testspectra/matchers 1.0.70 → 1.1.0-rc.0

package/package.json

@@ -1,21 +1,26 @@
 {
   "name": "@testspectra/matchers",
-  "version": "1.0.70",
-  "description": "Cross-platform action commands and direct callable assertion matchers for TestSpectra",
+  "version": "1.1.0-rc.0",
+  "description": "Canonical TypeScript contracts and ambient type definitions for TestSpectra",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "watch": "tsc -w",
+    "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "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"
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
   },
   "type": "module",
-  "license": "MIT"
+  "license": "SEE LICENSE IN LICENSE.md"
 }

package/src/contract.ts

@@ -0,0 +1,182 @@
+/**
+ * @packageDocumentation
+ * # PlatformDriverBridge Contract
+ *
+ * The unified abstract driver contract consumed by `@testspectra/matchers` element proxies,
+ * fluent matchers, and the `Spectra` automation object. Every platform-specific driver
+ * (`WebCdpDriverBridge`, `AndroidTcpDriverBridge`) implements this interface so that the
+ * DSL layer contains zero platform branching.
+ */
+
+import type {
+  CDPNetworkEntry,
+  MockInterceptHandle,
+  MockRule,
+  ScrollOptions,
+  SpectraBrowserBridge,
+  SwipeOptions,
+} from './types.js';
+
+/**
+ * Runtime configuration injected by the Rust orchestrator via `globalThis.__TESTSPECTRA_CONFIG__`.
+ */
+export interface RuntimeWorkerConfig {
+  workerId?: number;
+  rootDir: string;
+  testFilePath?: string;
+  testFiles?: Array<{ id: string; title: string; filePath: string; suite: string }>;
+  activePlatform: string;
+  configuredBaseUrl: string;
+  cdpWsUrl: string;
+  driverServerUrl: string;
+  manifest?: Record<string, any>;
+  /** Target app package (Android). Paired with androidSerial/adbPath for on-demand adb actions. */
+  appPackage?: string;
+  /** Target adb device serial for this worker (Android only). */
+  androidSerial?: string;
+  /** Resolved `adb` binary path (Android only), paired with androidSerial above. */
+  adbPath?: string;
+  /** Host port this worker's own MobileMockProxyServer should listen on (Android only) — derived
+   * per-device the same way androidSerial/the driver-server port already are, so each device in
+   * a multi-device run gets its own proxy instead of every worker racing for one shared port. */
+  mockProxyPort?: number;
+  implicitWaitMs?: number;
+  timeoutMs?: number;
+  stepDelayMs?: number;
+}
+
+/**
+ * Cross-cutting shared runtime state injected into the assembled worker script.
+ *
+ * The worker runtime is emitted as a single self-contained TypeScript module (concatenated
+ * by the Rust orchestrator). This object is created once in the harness prelude and mutated
+ * in place (`activeDriver` is bound after the platform bridge is instantiated), so fragments
+ * access it lazily at call-time through `globalThis.__TS_RUNTIME__`.
+ */
+export interface RuntimeContext {
+  config: RuntimeWorkerConfig;
+  activeDriver: PlatformDriverBridge | null;
+  mobileMockRules: MockRule[];
+  lastFocusedSelector: string | null;
+  currentTargetItem?: any;
+
+  emitEvent(tag: string, payload: string): void;
+  trackStep<T>(
+    category: 'action' | 'assertion' | 'browser',
+    payloadObj: Record<string, any>,
+    fn: () => Promise<T>,
+  ): Promise<T>;
+  pollCondition(fn: () => Promise<boolean> | boolean, timeoutMs?: number, intervalMs?: number): Promise<boolean>;
+  getImplicitWaitMs(): number;
+  getAssertionTimeoutMs(): number;
+  matchesUrlPattern(pattern: string, url: string): boolean;
+  createMockHandle(rule: MockRule): MockInterceptHandle;
+  parseMockRule(patternOrOptions?: any, maybeMethodOrHandler?: any, maybeFixture?: any, maybeOptions?: any): MockRule;
+
+  // Opt-in duration logging (see core/orchestrator/src/worker/prelude.ts). Present at runtime only
+  // when TESTSPECTRA_DURATION_LOG is set; the wrappers are pass-through no-ops otherwise.
+  recordDuration?: (label: string, category: string, durationMs: number, extra?: Record<string, unknown>) => void;
+  withDuration?: <T>(
+    label: string,
+    category: string,
+    fn: () => Promise<T>,
+    extra?: Record<string, unknown>,
+  ) => Promise<T>;
+  durationLogPath?: string | null;
+
+  // Matchers runtime factories — registered onto the context by the `tools/matchers` fragments
+  // at load time, then consumed by sibling fragments (concatenated single-scope assembly).
+  createElementActions?: (selector: string, index: number | null) => Record<string, any>;
+  createElementState?: (selector: string, index: number | null) => Record<string, any>;
+  createElementAssertions?: (selector: string, index: number | null, state: Record<string, any>) => Record<string, any>;
+  createElementProxy?: (selector: string, index?: number | null) => any;
+  createCollectionProxy?: (selector: string) => any;
+  resolveTargetProxy?: (target: any) => any;
+  buildSpectra?: () => any;
+
+  // Platform driver classes — registered by the driver bridge fragments at load time.
+  cdpBridgeClass?: any;
+  androidBridgeClass?: any;
+  mobileMockProxyClass?: any;
+  mobileMockProxy?: any;
+
+  // BDD harness lifecycle hooks & entrypoints — `bdd_runner.ts` owns the hook slots and
+  // `runSuite`; `auto_import.ts` owns `bootstrapEnvironment`. Routed through this shared context
+  // (rather than plain module-scoped bindings) because the harness fragments are concatenated
+  // into one script by the Rust orchestrator but remain separate ES modules for unit testing.
+  beforeHook?: (() => Promise<void> | void) | null;
+  afterHook?: (() => Promise<void> | void) | null;
+  beforeEachHook?: (() => Promise<void> | void) | null;
+  afterEachHook?: (() => Promise<void> | void) | null;
+  bootstrapEnvironment?: () => Promise<void>;
+  runSuite?: () => Promise<void>;
+}
+
+/**
+ * The unified platform driver contract. It extends the browser surface documented in
+ * `SpectraBrowserBridge` (navigation, script execution, network interception, browser-level
+ * assertions) with the element interaction and state-inspection methods needed by the DSL,
+ * so the `tools/matchers` layer never branches on `activePlatform`.
+ */
+export interface PlatformDriverBridge extends SpectraBrowserBridge {
+  /** Establishes connection to the underlying runtime endpoint (WebSocket / TCP Socket). */
+  connect(): Promise<void>;
+
+  /** Cleans up open connections, servers, and listeners. */
+  close(): Promise<void>;
+
+  /** Navigates to target URL (Web) or Activity / Deep Link (Android). */
+  navigate(targetUrl: string): Promise<void>;
+
+  // --- Element Actions ---
+  click(selector: string, index?: number | null): Promise<void>;
+  doubleClick(selector: string, index?: number | null): Promise<void>;
+  rightClick(selector: string, index?: number | null): Promise<void>;
+  setValue(selector: string, value: unknown, index?: number | null): Promise<void>;
+  clearValue(selector: string, index?: number | null): Promise<void>;
+  select(selector: string, option: string, index?: number | null): Promise<void>;
+  hover(selector: string, index?: number | null): Promise<void>;
+  focus(selector: string, index?: number | null): Promise<void>;
+  dragDrop(sourceSelector: string, targetSelector: string, sourceIndex?: number | null): Promise<void>;
+  longPress(selector: string, duration: number, index?: number | null): Promise<void>;
+  scrollIntoView(selector: string, index?: number | null): Promise<void>;
+
+  // --- Element State Inspection ---
+  getText(selector: string, index?: number | null): Promise<string>;
+  getValue(selector: string, index?: number | null): Promise<string>;
+  isDisplayed(selector: string, index?: number | null): Promise<boolean>;
+  isExisting(selector: string, index?: number | null): Promise<boolean>;
+  isEnabled(selector: string, index?: number | null): Promise<boolean>;
+  isSelected(selector: string, index?: number | null): Promise<boolean>;
+  isFocused(selector: string, index?: number | null): Promise<boolean>;
+  isClickable(selector: string, index?: number | null): Promise<boolean>;
+  hasClass(selector: string, className: string, index?: number | null): Promise<boolean>;
+  getAttribute(selector: string, name: string, index?: number | null): Promise<string | null>;
+  getCSSProperty(selector: string, name: string, index?: number | null): Promise<{ value: string }>;
+  count(selector: string): Promise<number>;
+
+  // --- Gestures & Keys ---
+  pressKey(key: string | number): Promise<void>;
+  scroll(options?: ScrollOptions): Promise<void>;
+  swipe(options: SwipeOptions): Promise<void>;
+
+  /**
+   * Grants an Android runtime permission on demand (e.g. right after confirming an in-app
+   * rationale dialog), via `adb shell pm grant` on the host. No-op on platforms without an
+   * OS-level runtime permission model (e.g. web).
+   */
+  grantPermission(name: string): Promise<void>;
+
+  /** Clears all active network interception rules. */
+  clearMocks(): void;
+
+  // --- State accessed by the harness & tests ---
+  mockRules: MockRule[];
+  consoleErrors: string[];
+  recordedNetwork: CDPNetworkEntry[];
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __TS_RUNTIME__: RuntimeContext;
+}

package/src/index.ts

@@ -2,27 +2,9 @@
  * @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 './contract.js';
+export * from './proto.js';