@specific.dev/spectest 0.39.0 → 0.43.0

package/dist/index.d.ts

@@ -84,7 +84,7 @@ export interface ServiceConfig {
     hostnames?: readonly string[];
     /**
      * Expose this service over HTTPS via a TLS-terminating reverse proxy
-     * hosted in the spectest-daemon. Each entry maps a fully-qualified
+     * hosted in the harness. Each entry maps a fully-qualified
      * hostname to the HTTP port the service listens on inside its
      * container; the daemon binds the hostname on `:443` (SNI-multiplexed,
      * with a leaf cert signed by the in-VM root CA) and on `:80`, and
@@ -936,20 +936,57 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
     /**
      * Open the headless browser. Backed by Chromium-over-CDP inside the VM.
      *
-     * There is ONE persistent browser per environment: every `ctx.browser()`
-     * call returns it, and it stays alive across tests — the browser is part
-     * of the state a test's snapshot captures, so a `dependsOn` child resumes
-     * the exact live page its parent left (cookies, localStorage, signed-in
-     * SPA state). Sign in once in a parent test; every descendant is already
-     * signed in. Sibling tests fork from the same parent snapshot, so they
-     * can't see each other's browsing. A test with no browser-using ancestor
-     * gets a fresh browser on first call (first call's options win).
+     * There is one persistent browser PER NAME, and `ctx.browser()` is the
+     * default (unnamed) one: every call returns it, and it stays alive across
+     * tests — the browser is part of the state a test's snapshot captures, so
+     * a `dependsOn` child resumes the exact live page its parent left
+     * (cookies, localStorage, signed-in SPA state). Sign in once in a parent
+     * test; every descendant is already signed in. Sibling tests fork from
+     * the same parent snapshot, so they can't see each other's browsing. A
+     * test with no browser-using ancestor gets a fresh browser on first call
+     * (first call's options win).
+     *
+     * For a second, independent browser — a second user — name it:
+     * `ctx.browser("alice")`. See the named overload.
      *
      * `.close()` destroys the shared instance — the next `ctx.browser()`
      * starts fresh. Don't call it for routine cleanup; recording is detached
      * automatically at test end.
      */
     browser(opts?: BrowserOptions): Promise<Browser>;
+    /**
+     * Open the persistent browser called `name`, creating it on first use.
+     * Each name is its own browser — its own cookies, localStorage and page —
+     * so naming them is how one test drives two users.
+     *
+     * **Only name a browser when the test needs two or more isolated sessions
+     * at once.** Otherwise use `ctx.browser()`: a name is a second identity,
+     * not a label, and a lone `ctx.browser("main")` buys nothing over the
+     * default while adding its name to every step title in the dashboard.
+     *
+     * ```ts
+     * const alice = await ctx.browser("alice", { url: "https://app.test" });
+     * const bob = await ctx.browser("bob", { url: "https://app.test" });
+     * await alice.getByRole("button", { name: "Share" }).click();
+     * await bob.reload();
+     * await expect(bob.getByText("Shared with you")).toBeVisible();
+     * ```
+     *
+     * Every rule of the default browser applies per name: the session rides
+     * the snapshot, so a `dependsOn` child inherits *each* named browser
+     * exactly where its parent left it (sign both users in once, in the
+     * parent); repeat calls with the same name in one test return the same
+     * handle; the first call for a name wins its options; `.close()` discards
+     * only that name. Sessions are named for the roles under test, not per
+     * row of data — each one is a live browser captured in every snapshot
+     * from here on, and opening too many is an error.
+     *
+     * The dashboard titles each step with the browser that performed it
+     * (`bob: click "Share"`) and labels the replay with the same name, so a
+     * two-user timeline stays readable and selecting a step shows that
+     * browser's session.
+     */
+    browser(name: string, opts?: BrowserOptions): Promise<Browser>;
     /**
      * Open a phone-emulated session for a mobile app and return a {@link Mobile}
      * handle already pointed at it — no `navigate`. Pass the app handle a
@@ -968,13 +1005,18 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * The session emulates the latest iPhone (viewport + DPR + mobile UA +
      * touch) and the dashboard replays it inside a phone bezel.
      *
-     * Sessions are persistent, one per app: like `ctx.browser()`, the live
-     * session is captured in the test's snapshot, so a `dependsOn` child
-     * picks up the app exactly where the parent left it (already signed in,
-     * mid-flow) instead of reloading it. `.close()` discards the session;
+     * Sessions are persistent, one per app per `name`: like `ctx.browser()`,
+     * the live session is captured in the test's snapshot, so a `dependsOn`
+     * child picks up the app exactly where the parent left it (already signed
+     * in, mid-flow) instead of reloading it. `.close()` discards the session;
      * the next `ctx.mobile(app)` opens the app fresh.
+     *
+     * Pass a `name` for a second phone running the same app — two users in
+     * one test: `ctx.mobile(ctx.svc.app, "alice")`. Names are independent
+     * sessions and are inherited per name by `dependsOn` children, exactly
+     * like named desktop browsers.
      */
-    mobile(app: MobileApp): Promise<Mobile>;
+    mobile(app: MobileApp, name?: string): Promise<Mobile>;
     /** The test's display name. */
     readonly testName: string;
     /**
@@ -1038,7 +1080,7 @@ export interface TestSuite<S extends ServicesMap = ServicesMap, F extends FakesM
     tests: TestCase<unknown, S, F>[];
 }
 /**
- * A fake server hosted in the spectest-daemon. Use this to stand in for
+ * A fake server hosted in the harness. Use this to stand in for
  * external HTTP APIs (auth providers, payment gateways, …) that you can't
  * call directly from the hermetic test VM.
  *
@@ -1176,7 +1218,7 @@ export interface TypedTest<S extends ServicesMap, F extends FakesMap = FakesMap>
 export interface Project<S extends ServicesMap = ServicesMap, F extends FakesMap = FakesMap> {
     environment: EnvironmentConfig<S>;
     /**
-     * Fake servers hosted in the spectest-daemon (see {@link defineFake}).
+     * Fake servers hosted in the harness (see {@link defineFake}).
      * Keyed by stable fake name; the key becomes the slot in
      * `ctx.fakes.<key>` from test code. Populated from the `fakes` declared
      * in `defineEnvironment(...)`.

package/dist/ingress.d.ts

@@ -1,5 +1,5 @@
 import type { Project, ServiceConfig } from "./index.js";
-/** Where a DNS name points. `ingress` = the spectest-daemon listener on the
+/** Where a DNS name points. `ingress` = the harness's listener on the
  *  bridge gateway (fakes, TLS-terminated proxies); `service` = a container's
  *  live IP on spectest-net (a plain peer alias, no daemon hop). */
 export type DnsTarget = {

package/dist/mobile.d.ts

@@ -49,14 +49,18 @@ export declare function openMobile(opts: {
     recorder: BrowserSessionRecorder | null;
 }): Promise<Mobile>;
 /**
- * Acquire the persistent phone-emulated session for an app (one per app URL,
- * created on first use). The daemon calls this from `ctx.mobile(app)` with a
- * per-test rrweb recorder; the resulting record carries `frame: "mobile"` so
- * the dashboard renders a phone bezel. `detach` is the test-end hook;
- * `mobile.close()` destroys the session for real.
+ * Acquire the persistent phone-emulated session for an app (one per app URL
+ * per `name`, created on first use). The daemon calls this from
+ * `ctx.mobile(app, name?)` with a per-test rrweb recorder; the resulting
+ * record carries `frame: "mobile"` so the dashboard renders a phone bezel.
+ * `detach` is the test-end hook; `mobile.close()` destroys the session for
+ * real.
  */
 export declare function openPersistentMobile(opts: {
     url: string;
+    /** Session name — `""` (the default) is the unnamed session every
+     *  `ctx.mobile(app)` call shares. Two names on one app are two phones. */
+    name?: string;
     recorder: BrowserSessionRecorder | null;
     /** Installed before the fresh session's first navigation (ignored on an
      *  attached session, which already carries it on the forked holder). */

package/dist/mobile.js

@@ -48,14 +48,15 @@ export async function openMobile(opts) {
     return backend;
 }
 /**
- * Acquire the persistent phone-emulated session for an app (one per app URL,
- * created on first use). The daemon calls this from `ctx.mobile(app)` with a
- * per-test rrweb recorder; the resulting record carries `frame: "mobile"` so
- * the dashboard renders a phone bezel. `detach` is the test-end hook;
- * `mobile.close()` destroys the session for real.
+ * Acquire the persistent phone-emulated session for an app (one per app URL
+ * per `name`, created on first use). The daemon calls this from
+ * `ctx.mobile(app, name?)` with a per-test rrweb recorder; the resulting
+ * record carries `frame: "mobile"` so the dashboard renders a phone bezel.
+ * `detach` is the test-end hook; `mobile.close()` destroys the session for
+ * real.
  */
 export async function openPersistentMobile(opts) {
-    const { browser, attached, detach } = await acquirePersistentMobileBackend(opts.url, opts.recorder, opts.initScript);
+    const { browser, attached, detach } = await acquirePersistentMobileBackend(opts.url, opts.name ?? "", opts.recorder, opts.initScript);
     return {
         mobile: browser,
         attached,

package/dist/recorder.d.ts

@@ -379,6 +379,16 @@ export interface BrowserEvent extends BaseEvent {
      * with a `BrowserSessionRecorder` attached (the daemon always does).
      */
     sessionId?: string;
+    /**
+     * Author-given name of that session — `ctx.browser("alice")` — absent
+     * for the default unnamed browser, so a single-browser test's steps
+     * carry no name and render exactly as they always have. Present, it is
+     * what the step list badges to say which browser acted. Duplicated here
+     * rather than resolved from the session record because the CLI's
+     * failure detail renders from persisted events alone, with no replay
+     * bundle to look the session up in.
+     */
+    sessionName?: string;
     /**
      * Wall-clock `Date.now()` captured at the moment this op *finished*.
      * Lives in the same time base as rrweb's `event.timestamp` fields,

package/dist/resolver.js

@@ -27,6 +27,7 @@
 import { createSocket } from "node:dgram";
 import { request as httpRequest } from "node:http";
 import { readFile, stat } from "node:fs/promises";
+import { lookup } from "./harness/names-registry.js";
 import * as dnsPacket from "dns-packet";
 const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
 const DOCKER_SOCKET = process.env.DOCKER_SOCKET ?? "/var/run/docker.sock";
@@ -37,7 +38,7 @@ const UPSTREAM_PORT = Number(process.env.SPECTEST_UPSTREAM_PORT ?? "53");
 const LISTEN_ADDR = process.env.SPECTEST_RESOLVER_ADDR ?? "127.0.0.53";
 const LISTEN_PORT = Number(process.env.SPECTEST_RESOLVER_PORT ?? "53");
 const TTL_SECONDS = Number(process.env.SPECTEST_RESOLVER_TTL ?? "5");
-/** Path the spectest-daemon writes when it brings fakes up. */
+/** Path the harness writes when it brings fakes up. */
 const FAKES_REGISTRY_PATH = process.env.SPECTEST_FAKES_REGISTRY ?? "/run/spectest-fakes.json";
 function dockerGet(path) {
     return new Promise((resolve) => {
@@ -129,13 +130,9 @@ async function lookupFake(name) {
  *  longest (most specific) matching suffix wins. */
 async function lookupWildcard(name) {
     await refreshRegistry();
-    let best = null;
-    for (const w of registryCache.wildcards) {
-        if (name.endsWith(w.suffix) && (!best || w.suffix.length > best.suffix.length)) {
-            best = w;
-        }
-    }
-    return best?.ip ?? null;
+    // Same module the harness writes with, so the two halves of this file
+    // format cannot drift apart.
+    return lookup({ hosts: {}, wildcards: registryCache.wildcards }, name);
 }
 async function forwardUpstream(query) {
     return new Promise((resolve) => {