@specific.dev/spectest 0.131.21 → 0.132.2

package/src/harness/reach.test.ts

@@ -1,5 +1,6 @@
+import { evaluateChangePolicy } from "../change-rules.js";
 import { describe, expect, test } from "bun:test";
-import { compactReach, compileDockerignore, isExcluded, projectReach, reachContains, renderReadsLcov, sourceOf } from "./reach.js";
+import { compactReach, environmentReachSource, compileDockerignore, isExcluded, projectReach, reachContains, renderReadsLcov, sourceOf } from "./reach.js";
 
 describe("dockerignore semantics", () => {
   const ex = (text: string, rel: string) => isExcluded(compileDockerignore(text), rel);
@@ -87,7 +88,7 @@ describe("reach rules", () => {
     { service: "db", volumeSources: ["data", "/var/run/docker.sock"] },
   ];
   const reach = projectReach(files, sources);
-  const rules = { version: 1 as const, sources, prefixes: compactReach(files, reach) };
+  const rules = { version: 2 as const, sources, prefixes: compactReach(files, reach) };
 
   test("compactReach folds a wholly reached directory into one prefix and keeps the odd file", () => {
     // packages/api holds README.md, which the ignore drops, so the
@@ -125,7 +126,7 @@ describe("reach rules", () => {
     expect(sourceOf([sources[1]!], "var/run/docker.sock")).toBeUndefined();
     // The Dockerfile named by path, and the one at the context root.
     expect(sourceOf(sources, "packages/api/Dockerfile")?.service).toBe("api");
-    expect(reachContains({ version: 1, sources: [{ context: "packages/x", ignore: "**" }], prefixes: [] }, "packages/x/Dockerfile")).toBe(true);
+    expect(reachContains({ version: 2, 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", () => {
@@ -134,14 +135,47 @@ describe("reach rules", () => {
       "lambda/add/index.js",
       "supabase/config.toml",
     ]);
-    const rules = { version: 1 as const, sources: srcs, prefixes: [] };
+    const rules = { version: 2 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("repository-root inputs and volumes reach existing and newly added files", () => {
+    for (const field of ["inputs", "volumeSources"] as const) {
+      for (const root of [".", "./"]) {
+        const source = { service: "root-consumer", [field]: [root] };
+        expect(projectReach(files, [source])).toEqual([...files].sort());
+        const rules = { version: 2 as const, sources: [source], prefixes: [] };
+        for (const path of ["new.ts", "new/directory/source.ts"]) {
+          expect(reachContains(rules, path)).toBe(true);
+          expect(sourceOf([source], path)?.service).toBe("root-consumer");
+        }
+      }
+      const absolute = { [field]: ["/", "/var/run/docker.sock"] };
+      expect(projectReach(files, [absolute])).toEqual([]);
+      expect(sourceOf([absolute], "var/run/docker.sock")).toBeUndefined();
+      expect(reachContains({ version: 2, sources: [absolute], prefixes: [] }, "new.ts")).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);
+    expect(reachContains({ version: 2, sources: [], prefixes: ["."] }, "anything/at/all")).toBe(true);
+    expect(reachContains({ version: 2, sources: [], prefixes: [] }, "anything/at/all")).toBe(false);
   });
 });
+
+
+test("environment policy owns Spectest Markdown outside narrow container contexts", () => {
+  const environment = environmentReachSource("__environment__");
+  const sources = [environment, {service:"app",context:"src"}];
+  const rules = {version:2 as const,sources,prefixes:[]};
+  for (const file of ["spectest/README.md", "spectest/tests/notes.md"]) {
+    expect(reachContains(rules,file)).toBe(true);
+    expect(sourceOf(sources,file)?.service).toBe("__environment__");
+    expect(evaluateChangePolicy(environment.changePolicy!,file)).toBe("ignore");
+  }
+  expect(evaluateChangePolicy(environment.changePolicy!,"spectest/index.ts")).toBe("full");
+  expect(evaluateChangePolicy(environment.changePolicy!,"spectest/tests/helper.ts")).toBe("coverage");
+  expect(reachContains(rules,"unrelated/file.ts")).toBe(false);
+});

package/src/harness/reach.ts

@@ -1,3 +1,5 @@
+import { resolveChangePolicy } from "../change-rules.js";
+
 // What a change to a project file can reach — the pure part.
 //
 // A project file affects a test only through one of three doors: it is in
@@ -114,6 +116,8 @@ export function isExcluded(patterns: Pattern[], rel: string): boolean {
 export interface ReachSource {
   /** The service the source belongs to (for the shadow page's verdicts). */
   service?: string;
+  /** Frozen source-change policy, including adapter defaults and service overrides. */
+  changePolicy?: import("../change-rules.js").ChangePolicy;
   /** Build context directory, project-relative (`.` for the root); absent
    *  for a registry image. */
   context?: string;
@@ -138,6 +142,12 @@ function normRel(p: string): string {
   return s === "." ? "" : s;
 }
 
+/** Environment/test sources remain owned even when every container has a narrow
+ * build context. Their common policy ignores nearby documentation. */
+export function environmentReachSource(service: string): ReachSource {
+  return {service,inputs:["spectest"],changePolicy:resolveChangePolicy({})};
+}
+
 /**
  * The project's reach: every project file (`files`, project-relative)
  * some service's build context includes or some volume mounts, plus the
@@ -165,7 +175,7 @@ export function projectReach(files: readonly string[], sources: readonly ReachSo
       if (v.startsWith("/")) continue;
       const src = normRel(v);
       for (const f of files) {
-        if (f === src || f.startsWith(`${src}/`)) out.add(f);
+        if (src === "" || f === src || f.startsWith(`${src}/`)) out.add(f);
       }
     }
   }
@@ -174,7 +184,7 @@ export function projectReach(files: readonly string[], sources: readonly ReachSo
 
 /** The `reach.json` report. Mirrors `reach::ReachRules` on the server. */
 export interface ReachRules {
-  version: 1;
+  version: 2;
   /** Every service's contribution, as rules. */
   sources: ReachSource[];
   /** The current file reach, compacted: `dir/` for a directory every
@@ -259,7 +269,7 @@ export function sourceOf(sources: readonly ReachSource[], path: string): ReachSo
     for (const v of [...(s.volumeSources ?? []), ...(s.inputs ?? [])]) {
       if (v.startsWith("/")) continue;
       const src = normRel(v);
-      if (p === src || p.startsWith(`${src}/`)) return s;
+      if (src === "" || p === src || p.startsWith(`${src}/`)) return s;
     }
   }
   return undefined;

package/src/harness/shadow-builder.test.ts

@@ -30,3 +30,11 @@ test("ordinary SDK execution never needs remote builder configuration", async ()
     else process.env.SPECTEST_SHADOW_BUILD = previous;
   }
 });
+
+// Switching formats must be an explicit controller-selected shadow artifact.
+test("Nydus export requires the explicit shadow format and rejects unknown modes", () => {
+  const nydus = validateShadowBuilder({ ...config, imageFormat: "nydus-v6" });
+  expect(shadowOutput(shadowImage(nydus, "api"), nydus)).toContain("compression=nydus,force-compression=true");
+  expect(() => validateShadowBuilder({ ...config, imageFormat: "unknown" })).toThrow();
+  expect(shadowOutput(shadowImage(config, "api"), config)).toContain("compression=zstd");
+});

package/src/harness/shadow-builder.ts

@@ -7,12 +7,14 @@ export interface ShadowBuilder {
   builder: string;
   registry: string;
   experiment: string;
+  imageFormat?: "nydus-v6";
 }
 export function validateShadowBuilder(value: unknown): ShadowBuilder {
   const c = value as ShadowBuilder;
   if (!c || c.version !== 1 || !/^shadow-[a-z0-9-]+$/.test(c.builder)
     || !/^[a-z0-9.-]+(?::[0-9]+)?$/.test(c.registry)
-    || !/^[a-z0-9-]{1,80}$/.test(c.experiment)) throw new Error("invalid shadow builder configuration");
+    || !/^[a-z0-9-]{1,80}$/.test(c.experiment)
+    || (c.imageFormat !== undefined && c.imageFormat !== "nydus-v6")) throw new Error("invalid shadow builder configuration");
   return c;
 }
 export async function shadowBuilder(): Promise<ShadowBuilder | undefined> {
@@ -26,7 +28,10 @@ export function shadowImage(c: ShadowBuilder, service: string): string {
 }
 // Convert inherited gzip layers too; the persistent builder caches the conversion.
 // Level 1 favors export latency over a small additional size reduction.
-export function shadowOutput(reference: string): string {
+export function shadowOutput(reference: string, config?: ShadowBuilder): string {
+  if (config?.imageFormat === "nydus-v6") {
+    return `type=image,name=${reference},push=true,oci-mediatypes=true,compression=nydus,force-compression=true`;
+  }
   return `type=image,name=${reference},push=true,oci-mediatypes=true,compression=zstd,compression-level=1,force-compression=true`;
 }
 export function imageDigest(metadata: unknown): string {

package/src/index.ts

@@ -176,6 +176,8 @@ export {
   type ServiceCoverage,
 } from "./coverage.js";
 import { applyCoverageAdapters, coverageAdapters, validateCoverage, type ServiceCoverage } from "./coverage.js";
+export { type ChangeRule, type ChangeAction, COMMON_CHANGE_RULES } from "./change-rules.js";
+import type { ChangeRule } from "./change-rules.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 export { ca } from "./environment-ca.js";
 
@@ -365,6 +367,9 @@ export interface ServiceConfig {
    * `spectest docs /services/coverage`.
    */
   coverage?: ServiceCoverage;
+  /** Ordered source-change overrides, independent of coverage collection.
+   * Last matching rule wins. false disables inherited defaults. */
+  changeRules?: readonly ChangeRule[] | false;
   /**
    * Files seeded into the container's filesystem **before it starts**.
    * Each entry's `content` is written to a VM-host staging path and
@@ -1138,6 +1143,9 @@ function expandServiceGroups(input: InputServicesMap): ServicesMap {
       // Rewrite relative dependsOn to final keys; a spread keeps function
       // fields (helpers/setup) and the enumerable-symbol ingress decls.
       const final: ServiceConfig = { ...svc, ...(part === entry.primary ? primaryOverrides : {}) };
+      // A group-level selection override applies to every generated owner.
+      if (primaryOverrides.changeRules !== undefined) final.changeRules = primaryOverrides.changeRules === false
+        ? false : [...(svc.changeRules || []), ...primaryOverrides.changeRules];
       // Component-owned nested containers keep their collection when callers
       // add ordinary service coverage (for example browser coverage on k3s).
       const collectors = coverageAdapters(svc.coverage).filter(adapter => adapter.collect);
@@ -1321,6 +1329,9 @@ export function normalizeServiceImage(image: ServiceImage): NormalizedServiceIma
 
 /** @internal Serializes build-only work with the owning component. */
 export interface ComponentImageBuild {
+  /** Coverage and selection policy of the built application image. */
+  coverage?: ServiceCoverage;
+  changeRules?: readonly ChangeRule[] | false;
   reference: string;
   image: BuildImage;
 }

package/src/microphone-fixture.test.ts

@@ -49,44 +49,93 @@ test("missing and invalid audio fail before Chromium launches", async () => {
   await expect(prepareMicrophoneFixture({ path: "" })).rejects.toThrow("microphone.path");
 });
 
-async function capture(browser: MobileBackend): Promise<void> {
-  await browser.silentRead(page => page.evaluate(async () => {
+async function capture(browser: MobileBackend, sampleRate?: number): Promise<void> {
+  const actualRate = await browser.silentRead(page => page.evaluate(async sampleRate => {
     const stream = await navigator.mediaDevices.getUserMedia({ audio: {
       echoCancellation: false, noiseSuppression: false, autoGainControl: false,
     } });
-    const context = new AudioContext();
+    // Analyse native microphone samples without depending on the host's audio
+    // output daemon. A stalled speaker sink can report a running context while
+    // its clock barely advances; no sound needs to be played by this test.
+    const context = new AudioContext({ sampleRate, sinkId: { type: "none" } } as AudioContextOptions);
+    const sink = (context as AudioContext & { sinkId: string | { type: string } }).sinkId;
+    if (typeof sink !== "object" || sink.type !== "none") throw new Error("native silent audio sink unavailable");
     const analyser = context.createAnalyser();
     analyser.fftSize = 4096;
+    analyser.smoothingTimeConstant = 0;
     context.createMediaStreamSource(stream).connect(analyser);
     await context.resume();
     (globalThis as any).__mic = { stream, context, analyser };
-  }));
+    return context.sampleRate;
+  }, sampleRate));
+  if (sampleRate !== undefined) expect(actualRate).toBe(sampleRate);
 }
 
-async function peak(browser: MobileBackend): Promise<number> {
+async function peak(browser: MobileBackend): Promise<{ frequency: number; binWidth: number }> {
   return browser.silentRead(page => page.evaluate(async () => {
     const { context, analyser } = (globalThis as any).__mic;
     const bins = new Float32Array(analyser.frequencyBinCount);
+    const windowSeconds = analyser.fftSize / context.sampleRate;
+    let audibleAt: number | undefined;
+    let sampledAt = -Infinity;
+    let previousBin = -1;
+    let stableWindows = 0;
     for (let i = 0; i < 100; i++) {
       analyser.getFloatFrequencyData(bins);
       const max = Math.max(...bins);
-      if (max > -40) return bins.indexOf(max) * context.sampleRate / analyser.fftSize;
+      if (max > -40) {
+        audibleAt ??= context.currentTime;
+        // The first audible FFT still contains startup silence and can put
+        // even a pure tone in the adjacent bin, especially at 44.1 kHz. Fill
+        // the complete window, then measure three independent stable windows.
+        // This condition does not know the expected tone: a stable wrong
+        // fixture still returns its actual frequency and fails the assertion.
+        if (context.currentTime - audibleAt >= windowSeconds &&
+            context.currentTime - sampledAt >= windowSeconds) {
+          sampledAt = context.currentTime;
+          const bin = bins.indexOf(max);
+          stableWindows = bin === previousBin ? stableWindows + 1 : 1;
+          previousBin = bin;
+          if (stableWindows === 3) {
+            const binWidth = context.sampleRate / analyser.fftSize;
+            return { frequency: bin * binWidth, binWidth };
+          }
+        }
+      } else {
+        audibleAt = undefined;
+        stableWindows = 0;
+      }
       await new Promise(resolve => setTimeout(resolve, 20));
     }
-    throw new Error("microphone produced no audible fixture");
+    throw new Error(`microphone produced no stable audible fixture: ${JSON.stringify({
+      state: context.state, time: context.currentTime, rate: context.sampleRate, max: Math.max(...bins),
+      previousBin, stableWindows,
+      tracks: (globalThis as any).__mic.stream.getTracks().map((t: MediaStreamTrack) => ({
+        state: t.readyState, muted: t.muted, enabled: t.enabled, settings: t.getSettings(),
+      })),
+    })}`);
   }));
 }
 
-describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("native Chromium microphone", () => {
+async function expectFrequency(browser: MobileBackend, frequency: number): Promise<void> {
+  const actual = await peak(browser);
+  // FFT peaks are quantized to the native context's bins. At 48 kHz, the
+  // nearest 4096-point bin to 440 Hz is 445.3125 Hz; a fixed 5 Hz tolerance
+  // incorrectly rejects that valid signal. Half a bin preserves the actual
+  // measurement resolution and easily distinguishes the two fixture tones.
+  expect(Math.abs(actual.frequency - frequency)).toBeLessThanOrEqual(actual.binWidth / 2);
+}
+
+describe.skipIf(!Bun.which("chromium") && !Bun.which("chromium-browser") && !Bun.which("google-chrome") && !Bun.which("chrome"))("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));
 
-  test("captures the fixture through native tracks and MediaRecorder", async () => {
+  test.each([44100, 48000])("captures the fixture at %i Hz through native tracks and MediaRecorder", async sampleRate => {
     const browser = await openMobileBackend({ url: server.url.href, microphone: { path: join(dir, "440%name.wav"), loop: true } });
     try {
-      await capture(browser);
-      expect(await peak(browser)).toBeCloseTo(440, -1);
+      await capture(browser, sampleRate);
+      await expectFrequency(browser, 440);
       const result = await browser.silentRead(page => page.evaluate(async () => {
         const { stream } = (globalThis as any).__mic;
         const recorder = new MediaRecorder(stream);
@@ -112,12 +161,12 @@ describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-head
     const b = await acquirePersistentBrowser("audio-b", { url: server.url.href, microphone: { path: join(dir, "880.wav"), loop: true } });
     try {
       await Promise.all([capture(a.browser), capture(b.browser)]);
-      expect(await peak(a.browser)).toBeCloseTo(440, -1);
-      expect(await peak(b.browser)).toBeCloseTo(880, -1);
+      await expectFrequency(a.browser, 440);
+      await expectFrequency(b.browser, 880);
       await a.detach();
       const attached = await acquirePersistentBrowser("audio-a");
       expect(attached.attached).toBe(true);
-      expect(await peak(attached.browser)).toBeCloseTo(440, -1);
+      await expectFrequency(attached.browser, 440);
       await attached.detach();
     } finally { await Promise.all([a.browser.close(), b.browser.close()]); }
   }, 20000);
@@ -126,7 +175,7 @@ describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-head
     const browser = await openMobileBackend({ url: server.url.href, microphone: { path: join(dir, "440%name.wav") } });
     try {
       await capture(browser);
-      expect(await peak(browser)).toBeCloseTo(440, -1);
+      await expectFrequency(browser, 440);
       const result = await browser.silentRead(page => page.evaluate(async () => {
         const { stream, analyser } = (globalThis as any).__mic;
         const samples = new Float32Array(analyser.fftSize);
@@ -140,4 +189,46 @@ describe.skipIf(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-head
       expect(result).toBe("live");
     } finally { await browser.close(); }
   }, 20000);
+
+  test.each(["browser", "mobile"] as const)("%s sessions capture native fixture audio and camera frames by default", async frame => {
+    const browser = await openMobileBackend({
+      frame, url: server.url.href,
+      microphone: { path: join(dir, "440%name.wav"), loop: true },
+    });
+    try {
+      await capture(browser);
+      await expectFrequency(browser, 440);
+      const image = await browser.silentRead(page => page.evaluate(async () => {
+        const stream = await navigator.mediaDevices.getUserMedia({ video: true });
+        const video = document.createElement("video");
+        video.muted = true;
+        video.srcObject = stream;
+        document.body.append(video);
+        let deadline: ReturnType<typeof setTimeout> | undefined;
+        try {
+          await video.play();
+          await Promise.race([
+            new Promise<void>(resolve => video.requestVideoFrameCallback(() => resolve())),
+            new Promise<never>((_, reject) => { deadline = setTimeout(() => reject(new Error("native camera delivered no video frame")), 3000); }),
+          ]);
+          const canvas = document.createElement("canvas");
+          canvas.width = 64; canvas.height = 48;
+          const context = canvas.getContext("2d")!;
+          context.drawImage(video, 0, 0, canvas.width, canvas.height);
+          const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data;
+          const colors = new Set<string>();
+          for (let i = 0; i < pixels.length; i += 4) colors.add(`${pixels[i]},${pixels[i + 1]},${pixels[i + 2]}`);
+          return { width: video.videoWidth, height: video.videoHeight, colors: colors.size, state: stream.getVideoTracks()[0]!.readyState };
+        } finally {
+          clearTimeout(deadline);
+          stream.getTracks().forEach(track => track.stop());
+          video.remove();
+        }
+      }));
+      expect(image.width).toBeGreaterThan(0);
+      expect(image.height).toBeGreaterThan(0);
+      expect(image.colors).toBeGreaterThan(4);
+      expect(image.state).toBe("live");
+    } finally { await browser.close(); }
+  }, 20000);
 });

package/src/playwright-assertions.test.ts

@@ -6,9 +6,9 @@ import { attachBrowserProbe, desktopStrategy, getLocatorProbe, makeLocator, type
 import { assertURL } from "./playwright-assertions.js";
 import { recordBrowser, startRecording, stopRecording } from "./recorder.js";
 
-// Opt in after `bunx playwright install chromium --only-shell`, or run
+// Opt in after `bunx playwright install chromium`, or run
 // automatically when a system/cached full Chromium is available.
-const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? undefined;
+const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome") ?? undefined;
 const available = !!process.env.SPECTEST_TEST_BROWSER_ASSERTIONS || !!executablePath || existsSync(chromium.executablePath());
 
 describe.skipIf(!available)("Spectest assertions backed by real Playwright/Chromium", () => {
@@ -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(!Bun.which("chromium-headless-shell") && !Bun.which("chrome-headless-shell"))("browser backend preserves assertion provenance and failure page capture", async () => {
+test.skipIf(!(Bun.which("chromium") ?? Bun.which("chromium-browser") ?? Bun.which("google-chrome") ?? Bun.which("chrome")))("browser backend preserves assertion provenance and failure page capture", async () => {
   const { openBrowser } = await import("./browser.js");
   const replaySteps: unknown[] = [];
   const view = await openBrowser({

package/src/recorder.ts

@@ -453,7 +453,7 @@ export interface EnvEvent extends BaseEvent {
 // method name verbatim. Both renderers (control-plane web + CLI) treat it as
 // an opaque string with a generic `{action} <target>` fallback, so new method
 // names need no Rust change. Representative values: "goto", "goBack",
-// "goForward", "reload", "evaluate", "waitForFunction",
+// "goForward", "reload", "evaluate", "readClipboard", "waitForFunction",
 // "click", "dblclick", "tap", "fill", "clear", "press", "type", "scroll",
 // "check", "hover", "textContent", "inputValue", "count", "screenshot".
 export type BrowserAction = string;