@specific.dev/spectest 0.103.0 → 0.104.0

package/dist/browser.d.ts

@@ -22,6 +22,13 @@ export interface BrowserOptions {
     frame?: "browser" | "mobile";
     /** Initial URL to navigate to before the constructor returns. */
     url?: string;
+    /** IANA timezone, e.g. "Europe/Stockholm". Defaults to the host timezone.
+     * Set on first creation; inherited sessions keep their original timezone. */
+    timezone?: string;
+    /** Locale, e.g. "sv-SE", for navigator.language, Accept-Language and
+     * date/number formatting. Omit to use the browser's default locale.
+     * Set on first creation; inherited sessions keep their original locale. */
+    locale?: string;
     /** Feed a WAV fixture through Chromium's native microphone capture.
      * Set on the session's first creation; inherited sessions keep their source.
      * Fixture sessions use a dedicated Chromium process for audio isolation. */
@@ -296,7 +303,7 @@ export interface SafeAreaInsets {
  * Pre-open `n` views into the pool (called by the daemon at the end of
  * /bootstrap, before the warm-template snapshot is captured). Only
  * default-viewport views are pooled — `openBrowser` with a custom
- * width/height bypasses the pool.
+ * width/height, timezone, locale or microphone bypasses the pool.
  */
 export declare function prewarmViewPool(n?: number): Promise<void>;
 /**

package/dist/browser.js

@@ -160,20 +160,24 @@ function deviceContextOptions(d) {
 }
 /** Create the context one view lives in — device emulation when the view is
  *  phone-emulated, a plain viewport otherwise. */
-async function newViewContext(width, height, device, microphone) {
-    const fixture = microphone === undefined ? undefined : await prepareMicrophoneFixture(microphone);
+async function newViewContext(width, height, device, opts = {}) {
+    const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
     let browser;
     try {
         browser = fixture ? await chromium.launch({
             executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
         }) : await ensurePlaywrightBrowser();
-        const context = await browser.newContext(device
-            ? deviceContextOptions(device)
-            : {
-                viewport: { width, height },
-                // Reduced-motion for replay fidelity — see deviceContextOptions.
-                reducedMotion: "reduce",
-            });
+        const context = await browser.newContext({
+            ...(device
+                ? deviceContextOptions(device)
+                : {
+                    viewport: { width, height },
+                    // Reduced-motion for replay fidelity — see deviceContextOptions.
+                    reducedMotion: "reduce",
+                }),
+            timezoneId: opts.timezone,
+            locale: opts.locale,
+        });
         context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
         context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
         if (fixture) {
@@ -879,7 +883,7 @@ async function createView(width, height) {
  * Pre-open `n` views into the pool (called by the daemon at the end of
  * /bootstrap, before the warm-template snapshot is captured). Only
  * default-viewport views are pooled — `openBrowser` with a custom
- * width/height bypasses the pool.
+ * width/height, timezone, locale or microphone bypasses the pool.
  */
 export async function prewarmViewPool(n = 1) {
     for (let i = 0; i < n; i++) {
@@ -910,10 +914,11 @@ export async function openMobileBackend(opts = {}) {
     const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
     const wantW = device ? device.viewport.width : opts.width ?? 1280;
     const wantH = device ? device.viewport.height : opts.height ?? 720;
-    // Mobile views are never pooled — the pool holds only default-desktop
-    // views (in the shared desktop context), and a mobile view needs its own
-    // emulated context anyway.
-    const pooled = !device && opts.microphone === undefined && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    // The pool holds only default-desktop contexts. Context creation options
+    // such as timezone and locale require a fresh context.
+    const pooled = !device && opts.microphone === undefined && opts.timezone === undefined &&
+        opts.locale === undefined && wantW === 1280 && wantH === 720
+        ? VIEW_POOL.pop() : undefined;
     let holder;
     if (pooled) {
         holder = {
@@ -930,7 +935,7 @@ export async function openMobileBackend(opts = {}) {
         };
     }
     else {
-        holder = await newHolder(wantW, wantH, device, opts.microphone);
+        holder = await newHolder(wantW, wantH, device, opts);
     }
     const { backend } = buildBackend(holder, opts.recorder ?? null, {
         persistent: false,
@@ -992,8 +997,8 @@ function checkSessionCap(kind, live, name) {
         `Each named session is a live browser captured in every snapshot from here on — name them for the ` +
         `roles under test (e.g. "buyer"/"seller") rather than per row of data, or close() the ones you're done with.`);
 }
-async function newHolder(width, height, device, microphone) {
-    const context = await newViewContext(width, height, device, microphone);
+async function newHolder(width, height, device, opts = {}) {
+    const context = await newViewContext(width, height, device, opts);
     let spawned;
     try {
         spawned = await spawnPage(context);
@@ -1073,7 +1078,7 @@ export async function acquirePersistentBrowser(name = "", opts = {}) {
     }
     else {
         checkSessionCap("browser", SHARED_BROWSERS.size, name);
-        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device, opts.microphone);
+        holder = await newHolder(device ? device.viewport.width : opts.width ?? 1280, device ? device.viewport.height : opts.height ?? 720, device, opts);
         SHARED_BROWSERS.set(name, holder);
     }
     const view = holder;

package/package.json

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

package/src/browser-timezone.test.ts

@@ -0,0 +1,105 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { readRaw } from "./inspect.js";
+import {
+  acquirePersistentBrowser,
+  openBrowser,
+  prewarmViewPool,
+  type Browser,
+} from "./browser.js";
+
+interface Settings {
+  timezone: string;
+  locale: string;
+  language: string;
+  acceptLanguage: string;
+  winterOffset: number;
+  summerOffset: number;
+  number: string;
+}
+
+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", () => {
+  let server: ReturnType<typeof Bun.serve>;
+  beforeAll(() => {
+    server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: request => new Response(`<script>
+        window.settings = {
+          timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+          locale: Intl.DateTimeFormat().resolvedOptions().locale,
+          language: navigator.language,
+          acceptLanguage: ${JSON.stringify(request.headers.get("accept-language"))},
+          winterOffset: new Date("2026-01-15T12:00:00Z").getTimezoneOffset(),
+          summerOffset: new Date("2026-07-15T12:00:00Z").getTimezoneOffset(),
+          number: new Intl.NumberFormat().format(1234.5),
+        };
+      </script>`, { headers: { "content-type": "text/html" } }),
+    });
+  });
+  afterAll(() => server.stop(true));
+
+  test("applies both options before initial navigation and retains them after reload", async () => {
+    const browser = await openBrowser({ timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      const initial = await settings(browser);
+      expect(initial).toMatchObject({
+        timezone: "Europe/Stockholm", locale: "sv-SE", language: "sv-SE",
+        winterOffset: -60, summerOffset: -120, number: "1\u00a0234,5",
+      });
+      expect(initial.acceptLanguage.split(",")[0]).toBe("sv-SE");
+      await browser.reload();
+      expect(await settings(browser)).toEqual(initial);
+    } finally { await browser.close(); }
+  }, 20000);
+
+  test.each([
+    { timezone: "Europe/Stockholm" },
+    { locale: "sv-SE" },
+  ])("bypasses the default view pool for %j without changing defaults", async options => {
+    const baseline = await openBrowser({ url: server.url.href });
+    let defaults: Settings;
+    try { defaults = await settings(baseline); } finally { await baseline.close(); }
+    await prewarmViewPool();
+    const browser = await openBrowser({ ...options, url: server.url.href });
+    try {
+      const actual = await settings(browser);
+      expect(actual.timezone).toBe(options.timezone ?? defaults.timezone);
+      expect(actual.language).toBe(options.locale ?? defaults.language);
+    } finally { await browser.close(); }
+    const pooled = await openBrowser({ url: server.url.href });
+    try { expect(await settings(pooled)).toEqual(defaults); } finally { await pooled.close(); }
+  }, 20000);
+
+  test("named sessions are isolated and reattachment keeps first-call settings", async () => {
+    const a = await acquirePersistentBrowser("regional-a", { timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      const b = await acquirePersistentBrowser("regional-b", { timezone: "America/New_York", locale: "en-US", url: server.url.href });
+      try {
+        expect(await settings(b.browser)).toMatchObject({ timezone: "America/New_York", language: "en-US", winterOffset: 300, summerOffset: 240 });
+        const original = await settings(a.browser);
+        expect(original).toMatchObject({ timezone: "Europe/Stockholm", language: "sv-SE" });
+        await a.detach();
+        const attached = await acquirePersistentBrowser("regional-a", { timezone: "UTC", locale: "en-US" });
+        expect(attached.attached).toBe(true);
+        await attached.browser.reload();
+        expect(await settings(attached.browser)).toEqual(original);
+        await attached.detach();
+      } finally { await b.browser.close(); }
+    } finally { await a.browser.close(); }
+  }, 20000);
+
+  test("mobile framing retains regional settings", async () => {
+    const browser = await openBrowser({ frame: "mobile", timezone: "Europe/Stockholm", locale: "sv-SE", url: server.url.href });
+    try {
+      expect(await settings(browser)).toMatchObject({ timezone: "Europe/Stockholm", language: "sv-SE", winterOffset: -60 });
+    } finally { await browser.close(); }
+  }, 20000);
+
+  test("rejects an invalid timezone", async () => {
+    await expect(openBrowser({ timezone: "Invalid/Timezone" })).rejects.toThrow(/timezone/i);
+  }, 20000);
+});

package/src/browser.ts

@@ -93,6 +93,13 @@ export interface BrowserOptions {
   frame?: "browser" | "mobile";
   /** Initial URL to navigate to before the constructor returns. */
   url?: string;
+  /** IANA timezone, e.g. "Europe/Stockholm". Defaults to the host timezone.
+   * Set on first creation; inherited sessions keep their original timezone. */
+  timezone?: string;
+  /** Locale, e.g. "sv-SE", for navigator.language, Accept-Language and
+   * date/number formatting. Omit to use the browser's default locale.
+   * Set on first creation; inherited sessions keep their original locale. */
+  locale?: string;
   /** Feed a WAV fixture through Chromium's native microphone capture.
    * Set on the session's first creation; inherited sessions keep their source.
    * Fixture sessions use a dedicated Chromium process for audio isolation. */
@@ -510,23 +517,25 @@ async function newViewContext(
   width: number,
   height: number,
   device: DevicePreset | null,
-  microphone?: MicrophoneFixture,
+  opts: Pick<BrowserOptions, "microphone" | "timezone" | "locale"> = {},
 ): Promise<BrowserContext> {
-  const fixture = microphone === undefined ? undefined : await prepareMicrophoneFixture(microphone);
+  const fixture = opts.microphone === undefined ? undefined : await prepareMicrophoneFixture(opts.microphone);
   let browser: PlaywrightBrowser | undefined;
   try {
     browser = fixture ? await chromium.launch({
       executablePath: chromiumPath(), headless: true, args: [...CHROME_ARGV, fixture.arg],
     }) : await ensurePlaywrightBrowser();
-    const context = await browser.newContext(
-      device
+    const context = await browser.newContext({
+      ...(device
         ? deviceContextOptions(device)
         : {
             viewport: { width, height },
             // Reduced-motion for replay fidelity — see deviceContextOptions.
             reducedMotion: "reduce",
-          },
-    );
+          }),
+      timezoneId: opts.timezone,
+      locale: opts.locale,
+    });
     context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
     context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
     if (fixture) {
@@ -1310,7 +1319,7 @@ async function createView(width: number, height: number): Promise<PooledView> {
  * Pre-open `n` views into the pool (called by the daemon at the end of
  * /bootstrap, before the warm-template snapshot is captured). Only
  * default-viewport views are pooled — `openBrowser` with a custom
- * width/height bypasses the pool.
+ * width/height, timezone, locale or microphone bypasses the pool.
  */
 export async function prewarmViewPool(n = 1): Promise<void> {
   for (let i = 0; i < n; i++) {
@@ -1345,11 +1354,12 @@ export async function openMobileBackend(
   const device = opts.frame === "mobile" ? LATEST_IPHONE : null;
   const wantW = device ? device.viewport.width : opts.width ?? 1280;
   const wantH = device ? device.viewport.height : opts.height ?? 720;
-  // Mobile views are never pooled — the pool holds only default-desktop
-  // views (in the shared desktop context), and a mobile view needs its own
-  // emulated context anyway.
+  // The pool holds only default-desktop contexts. Context creation options
+  // such as timezone and locale require a fresh context.
   const pooled =
-    !device && opts.microphone === undefined && wantW === 1280 && wantH === 720 ? VIEW_POOL.pop() : undefined;
+    !device && opts.microphone === undefined && opts.timezone === undefined &&
+    opts.locale === undefined && wantW === 1280 && wantH === 720
+      ? VIEW_POOL.pop() : undefined;
   let holder: ViewHolder;
   if (pooled) {
     holder = {
@@ -1365,7 +1375,7 @@ export async function openMobileBackend(
       initScripts: [],
     };
   } else {
-    holder = await newHolder(wantW, wantH, device, opts.microphone);
+    holder = await newHolder(wantW, wantH, device, opts);
   }
 
   const { backend } = buildBackend(holder, opts.recorder ?? null, {
@@ -1437,9 +1447,9 @@ async function newHolder(
   width: number,
   height: number,
   device: DevicePreset | null,
-  microphone?: MicrophoneFixture,
+  opts: Pick<BrowserOptions, "microphone" | "timezone" | "locale"> = {},
 ): Promise<ViewHolder> {
-  const context = await newViewContext(width, height, device, microphone);
+  const context = await newViewContext(width, height, device, opts);
   let spawned: SpawnedPage;
   try { spawned = await spawnPage(context); } catch (err) {
     await closeViewContext(context);
@@ -1539,7 +1549,7 @@ export async function acquirePersistentBrowser(
       device ? device.viewport.width : opts.width ?? 1280,
       device ? device.viewport.height : opts.height ?? 720,
       device,
-      opts.microphone,
+      opts,
     );
     SHARED_BROWSERS.set(name, holder);
   }