@specific.dev/spectest 0.131.18 → 0.131.19

package/dist/browser.js

@@ -1,5 +1,5 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
-// driving the guest's system Chromium (pipe transport — `chromium.launch`
+// driving the guest's Headless Shell (pipe transport — `chromium.launch`
 // with an explicit `executablePath`). Electron attaches to the app-owned
 // Chromium over CDP instead; its client also lives inside the VM. The wrapper
 // keeps the public surface stable (we swapped from Bun.WebView to Playwright without
@@ -109,7 +109,7 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // ────────────────────────────────────────────────────────────────────────
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
-// Default sessions share one Chromium per daemon, launched lazily and kept
+// Browser and mobile sessions share one Headless Shell per daemon, launched lazily and kept
 // for the daemon's lifetime. Fixture sessions own a process because the audio
 // source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
@@ -126,17 +126,18 @@ const VIEW_CLEANUPS = new WeakMap();
 // (mirroring the old one-Chrome-profile model), which left `close()` closing
 // the page only — cookies survived and the next session was still
 // authenticated.
-function chromiumPath() {
-    return (Bun.which("chromium") ??
-        Bun.which("chromium-browser") ??
-        Bun.which("google-chrome") ??
-        "/usr/bin/chromium");
+function browserExecutable() {
+    const executable = Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell");
+    if (!executable) {
+        throw new Error("Chromium Headless Shell is required by this SDK but is missing from the runtime image. Rebuild the environment with a current Spectest golden image; for local development, install chromium-headless-shell on PATH.");
+    }
+    return executable;
 }
 async function ensurePlaywrightBrowser() {
     if (PW_BROWSER?.isConnected())
         return PW_BROWSER;
     PW_BROWSER = await chromium.launch({
-        executablePath: chromiumPath(),
+        executablePath: browserExecutable(),
         headless: true,
         args: CHROME_ARGV,
     });
@@ -167,7 +168,7 @@ async function newViewContext(width, height, device, opts = {}) {
     let browser;
     try {
         browser = fixture ? await chromium.launch({
-            executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
+            executablePath: browserExecutable(), headless: true, args: [...CHROME_ARGV, fixture.arg],
         }) : await ensurePlaywrightBrowser();
         const context = await browser.newContext({
             ...(device

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.131.18",
+  "version": "0.131.19",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser-executable.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("SDK refuses a Chromium-only runtime instead of silently falling back", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "spectest-no-shell-"));
+  try {
+    await writeFile(join(dir, "chromium"), "#!/bin/sh\necho UNEXPECTED_CHROMIUM_LAUNCH >&2\nexit 1\n", { mode: 0o755 });
+    const browserModule = new URL("./browser.ts", import.meta.url).href;
+    const child = Bun.spawn([process.execPath, "-e", `
+      import { openBrowser } from ${JSON.stringify(browserModule)};
+      try { await openBrowser(); process.exit(2); }
+      catch (error) { console.error(error.message); process.exit(1); }
+    `], { env: { ...process.env, PATH: dir }, stdout: "pipe", stderr: "pipe" });
+    const stderr = await new Response(child.stderr).text();
+    expect(await child.exited).toBe(1);
+    expect(stderr).toContain("Headless Shell is required");
+    expect(stderr).not.toContain("UNEXPECTED_CHROMIUM_LAUNCH");
+  } finally { await rm(dir, { recursive: true, force: true }); }
+});

package/src/browser-finalization.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
 import { acquirePersistentBrowser } from "./browser.js";
 import { finalizeBrowserRecordings } from "./harness/deadline.js";
 
-const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"));
+const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
 
 test.skipIf(!available)("stuck replay drains are bounded warnings and late replies cannot change the recording or clear a later buffer", async () => {
   const chunks: unknown[] = [];

package/src/browser-navigation.test.ts

@@ -2,7 +2,7 @@ import { expect, test } from "bun:test";
 import { openBrowser } from "./browser.js";
 import { startRecording, stopRecording } from "./recorder.js";
 
-const available = !!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"));
+const available = !!(Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"));
 
 test.skipIf(!available)("public navigation options control goto/reload and remain visible in recordings", async () => {
   // The document commits immediately but load waits for an image. This

package/src/browser-screenshot.test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "bun:test";
+import { openBrowser, type BrowserSessionRecorder } from "./browser.js";
+import { readRaw } from "./inspect.js";
+
+const available =
+  Bun.which("chromium-headless-shell") ??
+  Bun.which("chrome-headless-shell");
+for (const frame of ["browser", "mobile"] as const) {
+  test.skipIf(!available)(
+    `${frame} public screenshot exports full PNG pixels after DOM changes`,
+    async () => {
+      const artifacts: Parameters<
+        NonNullable<BrowserSessionRecorder["registerArtifact"]>
+      >[0][] = [];
+      const browser = await openBrowser({
+        frame,
+        recorder: {
+          sessionId: `screenshot-${frame}`,
+          recordStep() {},
+          registerArtifact: (artifact) => artifacts.push(artifact),
+        },
+      });
+      const width = frame === "mobile" ? 393 : 1280;
+      const height = frame === "mobile" ? 852 : 720;
+      const dpr = frame === "mobile" ? 3 : 1;
+      try {
+        await browser.goto(
+          `data:text/html,${encodeURIComponent('<meta name="viewport" content="width=device-width,initial-scale=1"><style>body{margin:0;background:rgb(255,0,0)}</style>')}`,
+        );
+        for (const color of ["rgb(255,0,0)", "rgb(0,255,0)"]) {
+          await browser.evaluate(
+            "change background",
+            `document.body.style.background = ${JSON.stringify(color)}`,
+          );
+          const id = await browser.screenshot();
+          const artifact = artifacts.at(-1)!;
+          expect(artifact.id).toBe(id);
+          expect(artifact.contentType).toBe("image/png");
+          const png = Buffer.from(artifact.bytesBase64, "base64");
+          expect(artifact.sizeBytes).toBe(png.length);
+          expect([png.readUInt32BE(16), png.readUInt32BE(20)]).toEqual([
+            width * dpr,
+            height * dpr,
+          ]);
+          const pixel = readRaw(
+            await browser.evaluate(
+              "read captured bottom-right pixel",
+              `(async function () {
+          const img = new Image(); img.src = 'data:image/png;base64,${artifact.bytesBase64}'; await img.decode();
+          const canvas = document.createElement('canvas'); canvas.width=img.width; canvas.height=img.height;
+          const ctx=canvas.getContext('2d');ctx.drawImage(img,0,0);
+          return [...ctx.getImageData(img.width-10,img.height-10,1,1).data];
+        })()`,
+            ),
+          );
+          expect(pixel).toEqual(
+            color.includes("255,0,0") ? [255, 0, 0, 255] : [0, 255, 0, 255],
+          );
+        }
+      } finally {
+        await browser.close();
+      }
+    },
+    20000,
+  );
+}

package/src/browser-surface.test.ts

@@ -2,10 +2,13 @@ import { expect, test } from "bun:test";
 import { chromium } from "playwright-core";
 import { awaitBrowserSurface, captureBrowserScreenshot, reduceBrowserSurfaces } from "./browser-surface.js";
 
-const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? undefined;
-for (const mobile of [false, true]) {
-  test.skipIf(!executablePath)(`reduced surface preserves ${mobile ? "mobile" : "desktop"} behavior and screenshot pixels`, async () => {
-    const browser = await chromium.launch({ executablePath, headless: true, args: ["--no-sandbox"] });
+const engines = {
+  chromium: Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome"),
+  shell: Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell"),
+};
+for (const [engine, executablePath] of Object.entries(engines)) for (const mobile of [false, true]) {
+  test.skipIf(!executablePath)(`${engine}: reduced surface preserves ${mobile ? "mobile" : "desktop"} behavior and screenshot pixels`, async () => {
+    const browser = await chromium.launch({ executablePath: executablePath!, headless: true, args: ["--no-sandbox"] });
     const width = mobile ? 393 : 1280, height = mobile ? 852 : 720, dpr = mobile ? 3 : 1;
     try {
       const context = await browser.newContext({ viewport: { width, height }, isMobile: mobile, hasTouch: mobile, deviceScaleFactor: dpr });

package/src/browser-timezone.test.ts

@@ -21,7 +21,7 @@ async function settings(browser: Browser): Promise<Settings> {
   return readRaw(await browser.evaluate<Settings>("read initial regional settings", "window.settings")) as unknown as Settings;
 }
 
-describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("browser timezone and locale", () => {
+describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("browser timezone and locale", () => {
   let server: ReturnType<typeof Bun.serve>;
   beforeAll(() => {
     server = Bun.serve({

package/src/browser.ts

@@ -1,5 +1,5 @@
 // Headless browser handle for tests. Thin wrapper around playwright-core
-// driving the guest's system Chromium (pipe transport — `chromium.launch`
+// driving the guest's Headless Shell (pipe transport — `chromium.launch`
 // with an explicit `executablePath`). Electron attaches to the app-owned
 // Chromium over CDP instead; its client also lives inside the VM. The wrapper
 // keeps the public surface stable (we swapped from Bun.WebView to Playwright without
@@ -463,7 +463,7 @@ const NAVIGATION_TIMEOUT_MS = 30_000;
 // Shared Chromium (playwright-core)
 // ────────────────────────────────────────────────────────────────────────
 
-// Default sessions share one Chromium per daemon, launched lazily and kept
+// Browser and mobile sessions share one Headless Shell per daemon, launched lazily and kept
 // for the daemon's lifetime. Fixture sessions own a process because the audio
 // source is a process-wide flag. Both ride snapshots: the process, playwright's
 // pipe connection to it, and every open page freeze into the VM snapshot
@@ -481,19 +481,18 @@ const VIEW_CLEANUPS = new WeakMap<BrowserContext, () => Promise<void>>();
 // the page only — cookies survived and the next session was still
 // authenticated.
 
-function chromiumPath(): string {
-  return (
-    Bun.which("chromium") ??
-    Bun.which("chromium-browser") ??
-    Bun.which("google-chrome") ??
-    "/usr/bin/chromium"
-  );
+function browserExecutable(): string {
+  const executable = Bun.which("chromium-headless-shell") ?? Bun.which("chrome-headless-shell");
+  if (!executable) {
+    throw new Error("Chromium Headless Shell is required by this SDK but is missing from the runtime image. Rebuild the environment with a current Spectest golden image; for local development, install chromium-headless-shell on PATH.");
+  }
+  return executable;
 }
 
 async function ensurePlaywrightBrowser(): Promise<PlaywrightBrowser> {
   if (PW_BROWSER?.isConnected()) return PW_BROWSER;
   PW_BROWSER = await chromium.launch({
-    executablePath: chromiumPath(),
+    executablePath: browserExecutable(),
     headless: true,
     args: CHROME_ARGV,
   });
@@ -531,7 +530,7 @@ async function newViewContext(
   let browser: PlaywrightBrowser | undefined;
   try {
     browser = fixture ? await chromium.launch({
-      executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
+      executablePath: browserExecutable(), headless: true, args: [...CHROME_ARGV, fixture.arg],
     }) : await ensurePlaywrightBrowser();
     const context = await browser.newContext({
       ...(device

package/src/microphone-fixture.test.ts

@@ -77,7 +77,7 @@ async function peak(browser: MobileBackend): Promise<number> {
   }));
 }
 
-describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome"))("native Chromium microphone", () => {
+describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("native Chromium microphone", () => {
   let server: ReturnType<typeof Bun.serve>;
   beforeAll(() => { server = Bun.serve({ port: 0, hostname: "127.0.0.1", fetch: () => new Response("<html>microphone</html>", { headers: { "content-type": "text/html" } }) }); });
   afterAll(() => server.stop(true));

package/src/playwright-assertions.test.ts

@@ -200,7 +200,7 @@ describe.skipIf(!available)("Spectest assertions backed by real Playwright/Chrom
 
 // Exercise the production session branding/recording as well as the real
 // native engine above. browser.ts intentionally uses system Chromium.
-test.skipIf(!executablePath)("browser backend preserves assertion provenance and failure page capture", async () => {
+test.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("browser backend preserves assertion provenance and failure page capture", async () => {
   const { openBrowser } = await import("./browser.js");
   const replaySteps: unknown[] = [];
   const view = await openBrowser({