@testspectra/matchers 1.1.0 → 1.1.8-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/matchers",
-  "version": "1.1.0",
+  "version": "1.1.8-rc.1",
   "description": "Canonical TypeScript contracts and ambient type definitions for TestSpectra",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,15 +11,16 @@
       "default": "./dist/index.js"
     }
   },
-  "devDependencies": {
-    "@types/node": "^20.14.0",
-    "typescript": "^5.6.3"
-  },
-  "type": "module",
-  "license": "SEE LICENSE IN LICENSE.md",
   "scripts": {
     "build": "tsc",
     "watch": "tsc -w",
-    "typecheck": "tsc --noEmit"
-  }
-}
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  },
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md"
+}

package/src/contract.ts

@@ -0,0 +1,223 @@
+/**
+ * @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,
+  ScopedSelector,
+  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;
+  /** Mirrors `spectra.config.ts`'s `executionConfig.networkMonitoringEnabled` (default: true). */
+  networkMonitoringEnabled?: boolean;
+  /** Mirrors `spectra.config.ts`'s `executionConfig.monitoredDomains`. Empty/absent = capture all. */
+  monitoredDomains?: { domain: string; enabled: boolean }[];
+  /** Mirrors `spectra.config.ts`'s `executionConfig.environmentVariables`. */
+  environmentVariables?: Record<string, string>;
+}
+
+/**
+ * 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;
+  /** Whether a captured network request/response for `url` should be recorded, per
+   * `config.networkMonitoringEnabled` / `config.monitoredDomains`. */
+  shouldRecordNetworkEntry(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 | ScopedSelector, index: number | null) => Record<string, any>;
+  createElementState?: (selector: string | ScopedSelector, index: number | null) => Record<string, any>;
+  createElementAssertions?: (
+    selector: string | ScopedSelector,
+    index: number | null,
+    state: Record<string, any>,
+  ) => Record<string, any>;
+  createElementProxy?: (selector: string | ScopedSelector, index?: number | null) => any;
+  createCollectionProxy?: (selector: string | ScopedSelector) => 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>;
+
+  /** Navigates one step backward in browser/navigation history. */
+  back(): Promise<void>;
+
+  /** Navigates one step forward in browser/navigation history. */
+  forward(): Promise<void>;
+
+  /** Reloads / refreshes the current active page. */
+  refresh(): Promise<void>;
+
+  /** Sets the browser viewport dimensions (width and height in pixels). */
+  setViewport(width: number, height: number): Promise<void>;
+
+  /** Pauses execution for the given duration in milliseconds. */
+  pause(ms: number): Promise<void>;
+
+  /** Intercepts and mocks HTTP network requests matching the specified pattern or options. */
+  intercept(
+    patternOrOptions: string | { url: string; method?: string; response?: unknown },
+    method?: string,
+    fixture?: unknown,
+    options?: { statusCode?: number; headers?: Record<string, string>; delayMs?: number },
+  ): Promise<MockInterceptHandle>;
+
+  // --- Element Actions ---
+  // `selector` accepts a `ScopedSelector` when resolved via `element.get()`/`.getAll()` chaining
+  // (see tools/matchers/src/types.ts); when it is one, its own `.index` is authoritative and the
+  // separate `index` argument below is unused. `dragDrop`'s destination stays `string`-only —
+  // scoping it is out of scope (see the plan's non-goals).
+  click(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+  doubleClick(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+  rightClick(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+  setValue(selector: string | ScopedSelector, value: unknown, index?: number | null): Promise<void>;
+  clearValue(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+  select(selector: string | ScopedSelector, option: string, index?: number | null): Promise<void>;
+  hover(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+  focus(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+  dragDrop(sourceSelector: string | ScopedSelector, targetSelector: string, sourceIndex?: number | null): Promise<void>;
+  longPress(selector: string | ScopedSelector, duration: number, index?: number | null): Promise<void>;
+  scrollIntoView(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+
+  // --- Element State Inspection ---
+  getText(selector: string | ScopedSelector, index?: number | null): Promise<string>;
+  getValue(selector: string | ScopedSelector, index?: number | null): Promise<string>;
+  isDisplayed(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+  isExisting(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+  isEnabled(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+  isSelected(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+  isFocused(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+  isClickable(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+  hasClass(selector: string | ScopedSelector, className: string, index?: number | null): Promise<boolean>;
+  getAttribute(selector: string | ScopedSelector, name: string, index?: number | null): Promise<string | null>;
+  getCSSProperty(selector: string | ScopedSelector, name: string, index?: number | null): Promise<{ value: string }>;
+  count(selector: string | ScopedSelector): 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

@@ -6,4 +6,5 @@
  */
 
 export * from './types.js';
+export * from './contract.js';
 export * from './proto.js';

package/src/proto.ts

@@ -21,6 +21,14 @@ declare global {
    */
   var Step: Record<string, any>;
 
+  /**
+   * Typed shape of `Spectra.env`. Empty by default — each `spectra.config.ts`
+   * `executionConfig.environmentVariables` key is merged in as a `readonly <KEY>: string` member
+   * by the CLI's generated `.testspectra/types/env.d.ts` (plain TypeScript interface merging, the
+   * same mechanism `@types/node` uses to let projects augment `NodeJS.ProcessEnv`).
+   */
+  interface SpectraEnv {}
+
   namespace WebdriverIO {
     interface Browser extends SpectraBrowserBridge {}
   }