@specific.dev/spectest 0.87.0 → 0.88.0

package/src/daemon.ts

@@ -67,8 +67,9 @@ import {
   type CoverageInventoryContext,
 } from "./coverage.js";
 import { serviceForHost as hostToService } from "./harness/browser-coverage.js";
-import { acquirePersistentBrowser, mobileKey } from "./browser.js";
+import { acquirePersistentBrowser, acquirePersistentDesktop, mobileKey } from "./browser.js";
 import { isMobileApp, openPersistentMobile } from "./mobile.js";
+import { isDesktopApp, type Desktop, type DesktopApp, type DesktopOptions, type DesktopChrome } from "./desktop.js";
 // Pure ingress hostname matching, ported out of this file (see
 // harness/hostmatch.ts). Keeping ONE implementation is the point: the
 // exact-then-longest-suffix rule and the one-label certificate rule are
@@ -4255,7 +4256,8 @@ async function computeProjectReachInner(all: NamedService[]): Promise<ReachRules
   for (const svc of all) {
     const src: ReachSource = {
       service: svc.name,
-      volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source ? [v.source] : [])),
+      volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source && !v.reachExempt ? [v.source] : [])),
+      ...(svc.inputs && svc.inputs.length > 0 ? { inputs: [...svc.inputs] } : {}),
     };
     if (svc.image.type === "dockerfile") {
       try {
@@ -4352,10 +4354,11 @@ interface BrowserSessionRecord {
   openedAtMs: number;
   closedAtMs?: number;
   initialUrl?: string;
-  /** Replay frame: `"browser"` (desktop window, default) or `"mobile"`
-   * (phone bezel). Drives the dashboard's chrome; the rrweb events are
+  /** Replay frame: `"browser"` (default), `"mobile"` (phone bezel), or
+   * `"desktop"` (native app window). Drives the dashboard's chrome; the rrweb events are
    * identical either way. */
-  frame?: "browser" | "mobile";
+  frame?: "browser" | "mobile" | "desktop";
+  desktopChrome?: DesktopChrome;
   /** Safe-area insets that were CDP-emulated during capture (mobile
    * sessions on a Chromium that supports the override). The dashboard
    * substitutes these for `env(safe-area-inset-*)` in the replayed CSS —
@@ -4463,7 +4466,7 @@ function browserArgs(
 function newBrowserSession(
   testStart: number,
   idScope: string,
-  frame: "browser" | "mobile" = "browser",
+  frame: "browser" | "mobile" | "desktop" = "browser",
   artifacts?: ReturnType<typeof newArtifactCollector>,
   name = "",
 ): {
@@ -4486,6 +4489,7 @@ function newBrowserSession(
     record,
     recorder: {
       sessionId: record.sessionId,
+      frame,
       ...(name ? { sessionName: name } : {}),
       recordStep(step) {
         if (closed) return;
@@ -4507,6 +4511,37 @@ function newBrowserSession(
   };
 }
 
+/** Same desktop recording path for test runs and interactive evals. */
+function desktopOpener(
+  start: number,
+  scope: string,
+  sessions: Array<ReturnType<typeof newBrowserSession>>,
+  detaches: Array<() => Promise<void>>,
+  artifacts?: ReturnType<typeof newArtifactCollector>,
+) {
+  const memo = new Map<string, Desktop>();
+  return async (app: DesktopApp, options: DesktopOptions = {}): Promise<Desktop> => {
+    if (!isDesktopApp(app)) throw new Error("ctx.desktop(app): pass ctx.svc.app from an electron() service");
+    const window = options.window ?? 0;
+    const key = JSON.stringify([app.endpoint, window]);
+    const existing = memo.get(key);
+    if (existing) return existing;
+    const session = newBrowserSession(start, scope, "desktop", artifacts, window === 0 ? app.name : `${app.name} · window ${window + 1}`);
+    const { browser, detach, desktopChrome } = await acquirePersistentDesktop(app.endpoint, window, session.recorder);
+    session.record.desktopChrome = desktopChrome;
+    session.record.initialUrl = browser.url();
+    sessions.push(session);
+    detaches.push(async () => { await detach(); session.markClosed(); });
+    const close = browser.close.bind(browser);
+    browser.close = async () => {
+      await close();
+      if (memo.get(key) === browser) memo.delete(key);
+    };
+    memo.set(key, browser);
+    return browser;
+  };
+}
+
 /** Per-Terminal asciicast session shipped to the control plane. */
 interface TerminalSessionRecord {
   sessionId: string;
@@ -5599,6 +5634,7 @@ async function runOne(testCase: TestCase<unknown>): Promise<RunResult> {
     openTerminal: recordedOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    desktop: desktopOpener(start, testCase.id, sessions, browserDetaches),
     mcp: openMcp,
     testName: testCase.name,
     parent,
@@ -6154,6 +6190,7 @@ async function evalCode(
     openTerminal: evalOpenTerminal,
     browser: trackedOpenBrowser,
     mobile: trackedOpenMobile,
+    desktop: desktopOpener(start, "eval", sessions, browserDetaches, artifactCollector),
     mcp: openMcp,
     testName: "eval",
     parent: undefined,

package/src/desktop-recorder.test.ts

@@ -0,0 +1,55 @@
+import { expect, test } from 'bun:test';
+import { runInNewContext } from 'node:vm';
+import { DESKTOP_INPUT_SYNC_SCRIPT } from './desktop-recorder.js';
+
+function recorder(type = 'textarea', blocked = false) {
+  const element = { type, value: 'draft', checked: false, hasAttribute: (_name: string) => false, closest: () => blocked ? {} : null };
+  const window: any = { __spectestRec: { mirror: { getId: () => 7 } }, __spectestRrwebEvents: [] };
+  runInNewContext(DESKTOP_INPUT_SYNC_SCRIPT, { window, document: { querySelectorAll: () => [element] } });
+  return { element, window, events: window.__spectestRrwebEvents as any[] };
+}
+
+test('late attachment captures a controlled input clearing without a DOM input event', () => {
+  const { element, window, events } = recorder();
+  expect(events).toHaveLength(0);
+  element.value = '';
+  window.__spectestSyncInputs(123);
+  expect(JSON.parse(JSON.stringify(events))).toEqual([
+    { type: 3, data: { source: 5, id: 7, text: '', isChecked: false }, timestamp: 123 },
+  ]);
+  window.__spectestSyncInputs(124);
+  expect(events).toHaveLength(1);
+});
+
+test('rrweb input events need no duplicate correction; a snapshot does not hide later changes', () => {
+  const { element, window, events } = recorder();
+  element.value = 'typed';
+  events.push({ type: 3, data: { source: 5, id: 7, text: 'typed', isChecked: false } });
+  window.__spectestSyncInputs();
+  expect(events).toHaveLength(1);
+  events.length = 0;
+  events.push({ type: 2, data: {} });
+  element.value = '';
+  window.__spectestSyncInputs();
+  expect(events).toHaveLength(2);
+  expect(events[1].data.text).toBe('');
+});
+
+test('correction respects password masking, blocked controls and file inputs', () => {
+  const password = recorder('password');
+  password.element.value = 'secret-value';
+  password.window.__spectestSyncInputs();
+  expect(password.events[0].data.text).toBe('************');
+  expect(JSON.stringify(password.events)).not.toContain('secret-value');
+  const revealed = recorder('text');
+  revealed.element.hasAttribute = name => name === 'data-rr-is-password';
+  revealed.element.value = 'revealed-secret';
+  revealed.window.__spectestSyncInputs();
+  expect(revealed.events[0].data.text).toBe('***************');
+  expect(JSON.stringify(revealed.events)).not.toContain('revealed-secret');
+  for (const fixture of [recorder('textarea', true), recorder('file')]) {
+    fixture.element.value = 'private';
+    fixture.window.__spectestSyncInputs();
+    expect(fixture.events).toHaveLength(0);
+  }
+});

package/src/desktop-recorder.ts

@@ -0,0 +1,30 @@
+// A late recorder cannot interpose on setters React cached during mounting.
+// Reconcile controls at action boundaries, without changing the app's DOM or
+// descriptors. Normal rrweb Input events win; synthesize only missing changes.
+export const DESKTOP_INPUT_SYNC_SCRIPT = String.raw`(() => {
+  if (window.__spectestSyncInputs) return;
+  const known = new WeakMap();
+  window.__spectestSyncInputs = (timestamp = Date.now()) => {
+    const rec = window.__spectestRec;
+    const events = window.__spectestRrwebEvents;
+    if (!rec?.mirror || !events) return;
+    const inputs = new Map();
+    for (const event of events) {
+      if (event.type === 3 && event.data?.source === 5) inputs.set(event.data.id, event.data);
+    }
+    for (const element of document.querySelectorAll('input, textarea, select')) {
+      const type = element.hasAttribute('data-rr-is-password') ? 'password' : element.type?.toLowerCase();
+      if (type === 'file' || element.closest('.rr-block, .rr-ignore')) continue;
+      const id = rec.mirror.getId(element);
+      if (!(id > 0)) continue;
+      const text = type === 'password' ? '*'.repeat(element.value.length) : element.value;
+      const isChecked = (type === 'checkbox' || type === 'radio') ? element.checked : false;
+      const current = { text, isChecked };
+      const previous = inputs.get(id) ?? known.get(element);
+      known.set(element, current);
+      if (!previous || (previous.text === text && previous.isChecked === isChecked)) continue;
+      events.push({ type: 3, data: { source: 5, id, text, isChecked }, timestamp });
+    }
+  };
+  window.__spectestSyncInputs();
+})();`;

package/src/desktop.ts

@@ -0,0 +1,43 @@
+import type { Browser } from "./browser.js";
+
+export const DESKTOP_APP: unique symbol = Symbol.for("spectest.desktopApp");
+
+/** An Electron service handle produced by electron(). */
+export interface DesktopApp {
+  readonly [DESKTOP_APP]: true;
+  readonly endpoint: string;
+  readonly name: string;
+}
+
+/** Real renderer window: user input, locators, assertions, and replay capture.
+ * close() closes this window only. Native OS dialogs are outside DOM replay. */
+export interface Desktop extends Browser {}
+
+/** Observed window configuration at the start of a replay session. */
+export interface DesktopChrome {
+  titleBarStyle: string;
+  frame: boolean;
+  trafficLightPosition: { x: number; y: number } | null;
+  titleBarOverlay: boolean | { height?: number; color?: string; symbolColor?: string };
+  roundedCorners: boolean;
+  buttonVisibility: boolean | null;
+  titlebarArea?: { x: number; y: number; width: number; height: number };
+}
+
+export interface DesktopOptions {
+  /** Zero-based window creation order. Defaults to the first window.
+   * Open additional windows using the app UI before selecting them.
+   * A closed window keeps its index; other windows never change identity. */
+  window?: number;
+}
+
+export function desktopApp(endpoint: string, name: string): DesktopApp {
+  return { [DESKTOP_APP]: true, endpoint, name };
+}
+
+export function isDesktopApp(value: unknown): value is DesktopApp {
+  return typeof value === "object" && value !== null &&
+    (value as DesktopApp)[DESKTOP_APP] === true &&
+    typeof (value as DesktopApp).endpoint === "string" &&
+    typeof (value as DesktopApp).name === "string";
+}

package/src/harness/reach.test.ts

@@ -128,6 +128,18 @@ describe("reach rules", () => {
     expect(reachContains({ version: 1, sources: [{ context: "packages/x", ignore: "**" }], prefixes: [] }, "packages/x/Dockerfile")).toBe(true);
   });
 
+  test("a service's declared inputs count: a lambda's source directory, a config file", () => {
+    const srcs = [{ service: "aws", inputs: ["lambda/add", "supabase/config.toml"] }];
+    expect(projectReach(["lambda/add/index.js", "lambda/other/index.js", "supabase/config.toml", "supabase/config.toml.bak"], srcs)).toEqual([
+      "lambda/add/index.js",
+      "supabase/config.toml",
+    ]);
+    const rules = { version: 1 as const, sources: srcs, prefixes: [] };
+    expect(reachContains(rules, "lambda/add/new.js")).toBe(true);
+    expect(sourceOf(srcs, "lambda/add/new.js")?.service).toBe("aws");
+    expect(reachContains(rules, "lambda/other/index.js")).toBe(false);
+  });
+
   test("the whole project as one prefix", () => {
     expect(reachContains({ version: 1, sources: [], prefixes: ["."] }, "anything/at/all")).toBe(true);
     expect(reachContains({ version: 1, sources: [], prefixes: [] }, "anything/at/all")).toBe(false);

package/src/harness/reach.ts

@@ -125,6 +125,10 @@ export interface ReachSource {
   /** Volume sources, project-relative; an absolute source is not a
    *  project path and is skipped. */
   volumeSources?: string[];
+  /** The service's declared `inputs`: project files or directories it
+   *  consumes some other way (packaged at setup, read at load). A
+   *  directory covers its subtree. */
+  inputs?: string[];
 }
 
 function normRel(p: string): string {
@@ -157,7 +161,7 @@ export function projectReach(files: readonly string[], sources: readonly ReachSo
       const rel = normRel(e);
       if (rel) out.add(rel);
     }
-    for (const v of s.volumeSources ?? []) {
+    for (const v of [...(s.volumeSources ?? []), ...(s.inputs ?? [])]) {
       if (v.startsWith("/")) continue;
       const src = normRel(v);
       for (const f of files) {
@@ -252,7 +256,7 @@ export function sourceOf(sources: readonly ReachSource[], path: string): ReachSo
       }
     }
     for (const e of s.extraFiles ?? []) if (normRel(e) === p) return s;
-    for (const v of s.volumeSources ?? []) {
+    for (const v of [...(s.volumeSources ?? []), ...(s.inputs ?? [])]) {
       if (v.startsWith("/")) continue;
       const src = normRel(v);
       if (p === src || p.startsWith(`${src}/`)) return s;

package/src/index.ts

@@ -141,6 +141,8 @@ import { describeUrlPattern, matchesUrl } from "./url-match.js";
 // `expo()` component.
 export type { Mobile, MobileApp } from "./mobile.js";
 import type { Mobile, MobileApp } from "./mobile.js";
+export type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
+import type { Desktop, DesktopApp, DesktopOptions } from "./desktop.js";
 
 export type { Terminal, TerminalOpts, TerminalResult } from "./terminal.js";
 
@@ -308,6 +310,13 @@ export interface ServiceConfig {
   tls?: readonly ServiceTls[];
   /** Bind-mounted volumes for state that survives snapshot/fork. */
   volumes?: readonly VolumeMount[];
+  /**
+   * @internal Spectest's own components only: project files or
+   * directories the service consumes outside its build context and
+   * volumes (a lambda's `source`, Supabase's folder). Project-relative; a
+   * directory covers its subtree. The reach counts them.
+   */
+  inputs?: readonly string[];
   /**
    * Opt this service in to **code coverage collection** (experimental).
    *
@@ -1320,6 +1329,13 @@ export interface VolumeMount {
    * so unlike a volume directory it is never created or wiped by spectest.
    */
   source?: string;
+  /**
+   * @internal Spectest's own components only. The mount does not count
+   * for the project's reach: what the service can load from it is stated
+   * some other way (a narrowed build context, `inputs`). Never set this
+   * for a mount the service reads freely.
+   */
+  reachExempt?: boolean;
   /** Container path. */
   target: string;
   readOnly?: boolean;
@@ -1553,6 +1569,13 @@ function validateEnvironmentConfig<S extends ServicesMap>(
       }
     }
     validateCoverage(name, svc.coverage);
+    for (const input of svc.inputs ?? []) {
+      if (typeof input !== "string" || input.trim() === "" || input.startsWith("/") || input.split("/").includes("..")) {
+        throw new Error(
+          `service "${name}" has an invalid \`inputs\` entry ${JSON.stringify(input)} — a project-relative file or directory path`,
+        );
+      }
+    }
     for (const raw of svc.hostnames ?? []) {
       const h = raw.toLowerCase();
       if (!HOSTNAME_RE.test(hostPatternBody(h))) {
@@ -1928,6 +1951,16 @@ export interface TestContext<
    * like named desktop browsers.
    */
   mobile(app: MobileApp, name?: string): Promise<Mobile>;
+  /** Drive a real Electron renderer window through locators and user input.
+   * Acquires the app started by electron(); keeps its live state across forks.
+   * Each test gets a self-contained graphical replay. Selecting another window
+   * does not create a new app or isolate its storage from sibling windows.
+   *
+   * const app = await ctx.desktop(ctx.svc.app);
+   * await app.getByRole("textbox", { name: "New note" }).fill("Hello");
+   * await app.getByRole("button", { name: "Add note" }).click();
+   */
+  desktop(app: DesktopApp, options?: DesktopOptions): Promise<Desktop>;
   /** The test's display name. */
   readonly testName: string;
   /**

package/src/inputs.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { defineEnvironment } from "./index.js";
+
+const image = { type: "registry" as const, reference: "busybox" };
+
+describe("service inputs", () => {
+  test("project-relative files and directories are accepted and kept on the config", () => {
+    const env = defineEnvironment({
+      name: "t",
+      services: { app: { image, inputs: ["lambda/add", "supabase/config.toml"] } },
+    });
+    expect(env.config.services.app!.inputs).toEqual(["lambda/add", "supabase/config.toml"]);
+  });
+
+  test("an absolute path, an empty entry and a parent reference are refused", () => {
+    for (const bad of ["/etc/passwd", "", "../outside"]) {
+      expect(() => defineEnvironment({ name: "t", services: { app: { image, inputs: [bad] } } })).toThrow(/invalid `inputs` entry/);
+    }
+  });
+});

package/src/recorder.ts

@@ -520,6 +520,8 @@ export interface BrowserEvent extends BaseEvent {
    * bundle to look the session up in.
    */
   sessionName?: string;
+  /** Presentation kind; Electron and mobile share the browser event transport. */
+  frame?: "browser" | "mobile" | "desktop";
   /**
    * Wall-clock `Date.now()` captured at the moment this op *finished*.
    * Lives in the same time base as rrweb's `event.timestamp` fields,