@mochi.js/core 0.3.0 → 0.6.0

package/src/__tests__/proc-linux-server.test.ts

@@ -0,0 +1,243 @@
+/**
+ * Unit tests for the Linux-server environment auto-detection that drives
+ * `LaunchOptions.headlessMode` defaulting (task 0258).
+ *
+ * Two layers under test:
+ *
+ *   1. {@link detectLinuxServerEnv} — the pure classifier. Stub
+ *      `(platform, env, uid, container probes)` and assert the
+ *      `LinuxServerEnv` summary it returns.
+ *   2. {@link resolveHeadlessMode} — the resolution table that maps
+ *      `(LaunchOptions, LinuxServerEnv)` → `"new" | "legacy" | "off"`. Order
+ *      of precedence is load-bearing for the docs we ship; tests pin it.
+ *
+ * We DO NOT spawn Chromium here — the goal is to lock the decisions against
+ * regressions without taking the cost of a real launch. The flag-emit
+ * behaviour for the resolved mode is covered separately in
+ * `proc.test.ts` ("appends --headless=new when headless is true" et al.).
+ *
+ * @see packages/core/src/linux-server.ts
+ * @see packages/core/src/launch.ts (resolveHeadlessMode)
+ * @see tasks/0258 (Linux server env auto-detection)
+ */
+
+import { describe, expect, it } from "bun:test";
+import { resolveHeadlessMode } from "../launch";
+import { detectLinuxServerEnv, type LinuxServerProbes } from "../linux-server";
+import { buildChromiumArgs, type SpawnConfig } from "../proc";
+
+const FAKE_BINARY = "/usr/bin/chromium-stub";
+const FAKE_UDD = "/tmp/mochi-test-udd";
+
+function probes(overrides: Partial<LinuxServerProbes> = {}): LinuxServerProbes {
+  return {
+    platform: "linux",
+    display: undefined,
+    waylandDisplay: undefined,
+    uid: 1000,
+    hasDockerEnvFile: false,
+    cgroup: undefined,
+    ...overrides,
+  };
+}
+
+describe("detectLinuxServerEnv — server-no-display classifier (task 0258)", () => {
+  it("flags Linux + no DISPLAY + no WAYLAND_DISPLAY as serverNoDisplay=true", () => {
+    const env = detectLinuxServerEnv(probes());
+    expect(env.serverNoDisplay).toBe(true);
+  });
+
+  it("clears serverNoDisplay when DISPLAY is set (X11 dev workstation)", () => {
+    const env = detectLinuxServerEnv(probes({ display: ":0" }));
+    expect(env.serverNoDisplay).toBe(false);
+  });
+
+  it("clears serverNoDisplay when WAYLAND_DISPLAY is set (Wayland session)", () => {
+    const env = detectLinuxServerEnv(probes({ waylandDisplay: "wayland-0" }));
+    expect(env.serverNoDisplay).toBe(false);
+  });
+
+  it("treats empty-string DISPLAY as 'no display' (matches Chromium)", () => {
+    // An empty DISPLAY value means no usable X server; Chromium itself rejects
+    // the connection. Mirror that — an empty string must not gate us out of
+    // headless defaulting.
+    const env = detectLinuxServerEnv(probes({ display: "" }));
+    expect(env.serverNoDisplay).toBe(true);
+  });
+
+  it("never flags serverNoDisplay on darwin / win32 (rule is Linux-only)", () => {
+    expect(detectLinuxServerEnv(probes({ platform: "darwin" })).serverNoDisplay).toBe(false);
+    expect(detectLinuxServerEnv(probes({ platform: "win32" })).serverNoDisplay).toBe(false);
+  });
+
+  it("flags root=true when uid === 0 on Linux (orthogonal axis)", () => {
+    const env = detectLinuxServerEnv(probes({ uid: 0 }));
+    expect(env.root).toBe(true);
+    expect(env.serverNoDisplay).toBe(true);
+  });
+
+  it("clears root when uid !== 0", () => {
+    expect(detectLinuxServerEnv(probes({ uid: 1000 })).root).toBe(false);
+    expect(detectLinuxServerEnv(probes({ uid: undefined })).root).toBe(false);
+  });
+
+  it("never flags root on non-Linux (uid 0 on macOS root shell is not the same axis)", () => {
+    // The auto-`--no-sandbox` fallback in proc.ts is Linux-specific; the
+    // classifier mirrors that.
+    expect(detectLinuxServerEnv(probes({ platform: "darwin", uid: 0 })).root).toBe(false);
+  });
+
+  it("flags container=true when /.dockerenv is present", () => {
+    const env = detectLinuxServerEnv(probes({ hasDockerEnvFile: true }));
+    expect(env.container).toBe(true);
+  });
+
+  it("flags container=true when /proc/1/cgroup mentions docker", () => {
+    const env = detectLinuxServerEnv(
+      probes({ cgroup: "12:devices:/docker/abc123\n11:freezer:/docker/abc123\n" }),
+    );
+    expect(env.container).toBe(true);
+  });
+
+  it("flags container=true when cgroup mentions containerd", () => {
+    const env = detectLinuxServerEnv(probes({ cgroup: "0::/system.slice/containerd.service\n" }));
+    expect(env.container).toBe(true);
+  });
+
+  it("flags container=true when cgroup mentions kubepods (Kubernetes)", () => {
+    const env = detectLinuxServerEnv(
+      probes({ cgroup: "0::/kubepods.slice/kubepods-pod123.slice/\n" }),
+    );
+    expect(env.container).toBe(true);
+  });
+
+  it("clears container when neither indicator hits", () => {
+    expect(
+      detectLinuxServerEnv(probes({ cgroup: "0::/user.slice/user-1000.slice\n" })).container,
+    ).toBe(false);
+    expect(detectLinuxServerEnv(probes()).container).toBe(false);
+  });
+
+  it("rationale string surfaces every probed axis for debug logging", () => {
+    const env = detectLinuxServerEnv(
+      probes({ display: ":0", uid: 0, hasDockerEnvFile: true, waylandDisplay: undefined }),
+    );
+    expect(env.rationale).toContain("platform=linux");
+    expect(env.rationale).toContain("display=:0");
+    expect(env.rationale).toContain("uid=0");
+    expect(env.rationale).toContain("container=true");
+    expect(env.rationale).toContain("serverNoDisplay=false");
+  });
+});
+
+describe("resolveHeadlessMode — precedence table (task 0258)", () => {
+  const SERVER_ENV = detectLinuxServerEnv(probes());
+  const DEV_ENV = detectLinuxServerEnv(probes({ display: ":0" }));
+
+  it("explicit headlessMode='new' wins on a dev workstation", () => {
+    expect(resolveHeadlessMode({ headlessMode: "new" }, DEV_ENV)).toBe("new");
+  });
+
+  it("explicit headlessMode='legacy' wins on a server", () => {
+    expect(resolveHeadlessMode({ headlessMode: "legacy" }, SERVER_ENV)).toBe("legacy");
+  });
+
+  it("explicit headlessMode='off' wins on a server (caller knows what they want)", () => {
+    expect(resolveHeadlessMode({ headlessMode: "off" }, SERVER_ENV)).toBe("off");
+  });
+
+  it("legacy headless: true maps to 'new' regardless of env", () => {
+    expect(resolveHeadlessMode({ headless: true }, DEV_ENV)).toBe("new");
+    expect(resolveHeadlessMode({ headless: true }, SERVER_ENV)).toBe("new");
+  });
+
+  it("legacy headless: false maps to 'off' regardless of env", () => {
+    // Even on a server, an explicit `headless: false` must be honored —
+    // we are not in the business of ignoring user input. The user will
+    // crash, but they asked for it.
+    expect(resolveHeadlessMode({ headless: false }, SERVER_ENV)).toBe("off");
+    expect(resolveHeadlessMode({ headless: false }, DEV_ENV)).toBe("off");
+  });
+
+  it("env default: server-no-display → 'new' (the task 0258 fix)", () => {
+    expect(resolveHeadlessMode({}, SERVER_ENV)).toBe("new");
+  });
+
+  it("env default: dev workstation with DISPLAY → 'off' (run headful)", () => {
+    expect(resolveHeadlessMode({}, DEV_ENV)).toBe("off");
+  });
+
+  it("env default: macOS / Windows → 'off' (no Linux-only fallback)", () => {
+    const macEnv = detectLinuxServerEnv(probes({ platform: "darwin" }));
+    const winEnv = detectLinuxServerEnv(probes({ platform: "win32" }));
+    expect(resolveHeadlessMode({}, macEnv)).toBe("off");
+    expect(resolveHeadlessMode({}, winEnv)).toBe("off");
+  });
+
+  it("headlessMode supersedes a contradicting legacy headless flag", () => {
+    expect(resolveHeadlessMode({ headlessMode: "off", headless: true }, SERVER_ENV)).toBe("off");
+    expect(resolveHeadlessMode({ headlessMode: "new", headless: false }, DEV_ENV)).toBe("new");
+  });
+
+  it("server + root still resolves to 'new' (orthogonal axes — task 0258 §detection)", () => {
+    // The root/no-sandbox auto-flag is owned by proc.ts, not the headless
+    // resolver. This test pins that resolveHeadlessMode does NOT bake root
+    // into its decision — the user could be running the new-headless flow
+    // as root inside a container without that influencing the mode.
+    const rootServer = detectLinuxServerEnv(probes({ uid: 0 }));
+    expect(resolveHeadlessMode({}, rootServer)).toBe("new");
+  });
+
+  it("container + DISPLAY (rare but valid) → 'off' (developer in a devcontainer)", () => {
+    const devcontainer = detectLinuxServerEnv(
+      probes({ display: ":0", hasDockerEnvFile: true, cgroup: "0::/docker/abc\n" }),
+    );
+    expect(devcontainer.container).toBe(true);
+    expect(devcontainer.serverNoDisplay).toBe(false);
+    expect(resolveHeadlessMode({}, devcontainer)).toBe("off");
+  });
+});
+
+describe("buildChromiumArgs — headlessMode dispatch (task 0258)", () => {
+  function baseCfg(overrides: Partial<SpawnConfig> = {}): SpawnConfig {
+    return { binary: FAKE_BINARY, headless: false, ...overrides };
+  }
+
+  it("headlessMode='new' emits --headless=new", () => {
+    const args = buildChromiumArgs(baseCfg({ headlessMode: "new" }), FAKE_UDD, undefined);
+    expect(args).toContain("--headless=new");
+    expect(args).not.toContain("--headless");
+  });
+
+  it("headlessMode='legacy' emits bare --headless", () => {
+    const args = buildChromiumArgs(baseCfg({ headlessMode: "legacy" }), FAKE_UDD, undefined);
+    expect(args).toContain("--headless");
+    expect(args).not.toContain("--headless=new");
+  });
+
+  it("headlessMode='off' emits no headless flag at all", () => {
+    const args = buildChromiumArgs(baseCfg({ headlessMode: "off" }), FAKE_UDD, undefined);
+    expect(args.some((a) => a === "--headless" || a.startsWith("--headless="))).toBe(false);
+  });
+
+  it("headlessMode='new' supersedes headless: false", () => {
+    // The launcher resolves the mode; by the time we reach buildChromiumArgs,
+    // the resolved mode is canonical.
+    const args = buildChromiumArgs(
+      baseCfg({ headless: false, headlessMode: "new" }),
+      FAKE_UDD,
+      undefined,
+    );
+    expect(args).toContain("--headless=new");
+  });
+
+  it("legacy: headless: true with no headlessMode falls back to --headless=new", () => {
+    const args = buildChromiumArgs(baseCfg({ headless: true }), FAKE_UDD, undefined);
+    expect(args).toContain("--headless=new");
+  });
+
+  it("legacy: headless: false with no headlessMode emits no headless flag", () => {
+    const args = buildChromiumArgs(baseCfg({ headless: false }), FAKE_UDD, undefined);
+    expect(args.some((a) => a === "--headless" || a.startsWith("--headless="))).toBe(false);
+  });
+});

package/src/__tests__/proxy-auth.test.ts

@@ -5,7 +5,8 @@
  * with-auth/no-auth × edge cases (missing port, IPv6 host, percent-encoded
  * creds, empty password).
  *
- * `installProxyAuth`: drives a fake CDP router. Verifies:
+ * `installProxyAuth`: drives a fake CDP router via the shared
+ * `tests/helpers/cdp-fixture.ts` helper. Verifies:
  *   - `Fetch.enable` is sent with `handleAuthRequests: true, patterns: [{ urlPattern: "*" }]`.
  *   - `Fetch.authRequired` events trigger `Fetch.continueWithAuth` carrying
  *     the configured creds.
@@ -16,8 +17,8 @@
  */
 
 import { describe, expect, it } from "bun:test";
+import { type FakePipe, makeFakePipe } from "../../../../tests/helpers/cdp-fixture";
 import { MessageRouter } from "../cdp/router";
-import type { PipeReader, PipeWriter } from "../cdp/transport";
 import { installProxyAuth, parseProxyUrl } from "../proxy-auth";
 
 describe("parseProxyUrl", () => {
@@ -131,69 +132,35 @@ describe("parseProxyUrl", () => {
 
 interface FakeRouter {
   router: MessageRouter;
-  written: { method: string; params?: unknown }[];
+  pipe: FakePipe;
   pushEvent(method: string, params: unknown): void;
 }
 
 function makeRouter(): FakeRouter {
-  const written: { method: string; params?: unknown }[] = [];
-  let pumpController: ReadableStreamDefaultController<Uint8Array> | null = null;
-  const stream = new ReadableStream<Uint8Array>({
-    start(c) {
-      pumpController = c;
-    },
-  });
-  const reader: PipeReader = {
-    getReader: () => stream.getReader(),
-  };
-  const writer: PipeWriter = {
-    write: (chunk: Uint8Array) => {
-      const last = chunk[chunk.length - 1] === 0 ? chunk.length - 1 : chunk.length;
-      const json = new TextDecoder().decode(chunk.subarray(0, last));
-      try {
-        const obj = JSON.parse(json) as { id?: number; method: string; params?: unknown };
-        written.push({ method: obj.method, params: obj.params });
-        // Auto-resolve the request immediately so the await in
-        // `installProxyAuth` doesn't hang.
-        if (typeof obj.id === "number") {
-          const reply = JSON.stringify({ id: obj.id, result: {} });
-          const enc = new TextEncoder().encode(reply);
-          const out = new Uint8Array(enc.length + 1);
-          out.set(enc, 0);
-          out[enc.length] = 0;
-          pumpController?.enqueue(out);
-        }
-      } catch {
-        // ignore
-      }
-      return chunk.byteLength;
-    },
-    flush: () => undefined,
-    end: () => undefined,
-  };
-  const router = new MessageRouter(reader, writer);
+  // Default responders auto-answer Fetch.enable / Fetch.disable / etc with
+  // `{}` — that's everything `installProxyAuth` waits on.
+  const pipe = makeFakePipe();
+  const router = new MessageRouter(pipe.reader, pipe.writer);
   router.start();
-  const enc = new TextEncoder();
   return {
     router,
-    written,
+    pipe,
     pushEvent(method: string, params: unknown): void {
-      const bytes = enc.encode(JSON.stringify({ method, params }));
-      const out = new Uint8Array(bytes.length + 1);
-      out.set(bytes, 0);
-      out[bytes.length] = 0;
-      pumpController?.enqueue(out);
+      pipe.inject({ method, params });
     },
   };
 }
 
 describe("installProxyAuth", () => {
-  it("sends Fetch.enable with handleAuthRequests:true and empty patterns", async () => {
+  it("sends Fetch.enable with handleAuthRequests:true and Document-first patterns (task 0266)", async () => {
     const f = makeRouter();
     const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
-    const enable = f.written.find((c) => c.method === "Fetch.enable");
+    const enable = f.pipe.written.find((c) => c.parsed.method === "Fetch.enable");
     expect(enable).toBeDefined();
-    expect(enable?.params).toEqual({ handleAuthRequests: true, patterns: [{ urlPattern: "*" }] });
+    expect(enable?.parsed.params).toEqual({
+      handleAuthRequests: true,
+      patterns: [{ urlPattern: "*", resourceType: "Document" }, { urlPattern: "*" }],
+    });
     await handle.dispose();
     await f.router.close();
   });
@@ -204,9 +171,9 @@ describe("installProxyAuth", () => {
     f.pushEvent("Fetch.authRequired", { requestId: "req-42", authChallenge: { source: "Proxy" } });
     // Allow microtasks + the writer push to flush.
     await new Promise((r) => setTimeout(r, 10));
-    const reply = f.written.find((c) => c.method === "Fetch.continueWithAuth");
+    const reply = f.pipe.written.find((c) => c.parsed.method === "Fetch.continueWithAuth");
     expect(reply).toBeDefined();
-    expect(reply?.params).toEqual({
+    expect(reply?.parsed.params).toEqual({
       requestId: "req-42",
       authChallengeResponse: {
         response: "ProvideCredentials",
@@ -223,9 +190,9 @@ describe("installProxyAuth", () => {
     const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
     f.pushEvent("Fetch.requestPaused", { requestId: "rp-1" });
     await new Promise((r) => setTimeout(r, 10));
-    const reply = f.written.find((c) => c.method === "Fetch.continueRequest");
+    const reply = f.pipe.written.find((c) => c.parsed.method === "Fetch.continueRequest");
     expect(reply).toBeDefined();
-    expect(reply?.params).toEqual({ requestId: "rp-1" });
+    expect(reply?.parsed.params).toEqual({ requestId: "rp-1" });
     await handle.dispose();
     await f.router.close();
   });
@@ -235,7 +202,7 @@ describe("installProxyAuth", () => {
     const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
     await handle.dispose();
     await handle.dispose();
-    const disables = f.written.filter((c) => c.method === "Fetch.disable");
+    const disables = f.pipe.written.filter((c) => c.parsed.method === "Fetch.disable");
     expect(disables.length).toBe(1);
     await f.router.close();
   });
@@ -246,7 +213,7 @@ describe("installProxyAuth", () => {
     await handle.dispose();
     f.pushEvent("Fetch.authRequired", { requestId: "late" });
     await new Promise((r) => setTimeout(r, 10));
-    const replies = f.written.filter((c) => c.method === "Fetch.continueWithAuth");
+    const replies = f.pipe.written.filter((c) => c.parsed.method === "Fetch.continueWithAuth");
     expect(replies.length).toBe(0);
     await f.router.close();
   });

package/src/__tests__/screenshot.e2e.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Live conformance test for `Page.screenshot` (task 0265).
+ *
+ * Gated by `MOCHI_E2E=1` so the default `bun test` run stays fast and offline.
+ * Spawns a real Chromium-for-Testing instance, navigates to a tiny data URL,
+ * captures the viewport as PNG, and asserts the bytes start with the PNG
+ * magic signature.
+ *
+ * Budget: < 10 seconds.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { mochi } from "../index";
+
+const E2E_ENABLED = process.env.MOCHI_E2E === "1";
+const TEST_TIMEOUT_MS = 10_000;
+
+const describeOrSkip = E2E_ENABLED ? describe : describe.skip;
+
+describeOrSkip("@mochi.js/core Page.screenshot E2E (MOCHI_E2E=1)", () => {
+  it(
+    "captures a PNG screenshot — Uint8Array starts with PNG magic bytes",
+    async () => {
+      const session = await mochi.launch({
+        profile: "test",
+        seed: "screenshot-e2e",
+        headless: true,
+      });
+      try {
+        const page = await session.newPage();
+        await page.goto("data:text/html,<title>shot</title><h1 style='color:red'>hello</h1>");
+        const png = await page.screenshot();
+        expect(png).toBeInstanceOf(Uint8Array);
+        // PNG signature: 89 50 4E 47 0D 0A 1A 0A
+        expect(png[0]).toBe(0x89);
+        expect(png[1]).toBe(0x50);
+        expect(png[2]).toBe(0x4e);
+        expect(png[3]).toBe(0x47);
+        expect(png[4]).toBe(0x0d);
+        expect(png[5]).toBe(0x0a);
+        expect(png[6]).toBe(0x1a);
+        expect(png[7]).toBe(0x0a);
+        // Sanity: a non-trivial image should be more than just the header.
+        expect(png.length).toBeGreaterThan(100);
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  it(
+    "captures a JPEG screenshot when format: 'jpeg'",
+    async () => {
+      const session = await mochi.launch({
+        profile: "test",
+        seed: "screenshot-e2e-jpeg",
+        headless: true,
+      });
+      try {
+        const page = await session.newPage();
+        await page.goto("data:text/html,<h1>jpeg</h1>");
+        const jpeg = await page.screenshot({ format: "jpeg", quality: 70 });
+        expect(jpeg).toBeInstanceOf(Uint8Array);
+        // JPEG SOI marker: FF D8 FF
+        expect(jpeg[0]).toBe(0xff);
+        expect(jpeg[1]).toBe(0xd8);
+        expect(jpeg[2]).toBe(0xff);
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  it(
+    "fullPage: true captures beyond the visible viewport",
+    async () => {
+      const session = await mochi.launch({
+        profile: "test",
+        seed: "screenshot-e2e-fullpage",
+        headless: true,
+      });
+      try {
+        const page = await session.newPage();
+        // A page taller than the default viewport so fullPage actually matters.
+        await page.goto(
+          "data:text/html,<style>body{margin:0}div{height:3000px;background:linear-gradient(red,blue)}</style><div></div>",
+        );
+        const viewportShot = await page.screenshot();
+        const fullShot = await page.screenshot({ fullPage: true });
+        expect(viewportShot[0]).toBe(0x89);
+        expect(fullShot[0]).toBe(0x89);
+        // Full-page bytes should be larger than viewport bytes for a 3000px page.
+        expect(fullShot.length).toBeGreaterThan(viewportShot.length);
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+
+  it(
+    "encoding: 'base64' returns a string instead of bytes",
+    async () => {
+      const session = await mochi.launch({
+        profile: "test",
+        seed: "screenshot-e2e-b64",
+        headless: true,
+      });
+      try {
+        const page = await session.newPage();
+        await page.goto("data:text/html,<h1>b64</h1>");
+        const b64 = await page.screenshot({ encoding: "base64" });
+        expect(typeof b64).toBe("string");
+        // Decoded base64 must start with the PNG magic.
+        const decoded = Buffer.from(b64, "base64");
+        expect(decoded[0]).toBe(0x89);
+        expect(decoded[1]).toBe(0x50);
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+});