@jskit-ai/jskit-catalog 0.2.32 → 0.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-catalog",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "description": "Published metadata catalog for JSKIT package metadata.",
   "type": "module",
   "files": [
@@ -15,6 +15,7 @@
     "./packages": "./catalog/packages.json",
     "./project-packages": "./scripts/project-packages.mjs",
     "./test-budget": "./scripts/test-budget.mjs",
+    "./browser-tests": "./scripts/browser-tests.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {

package/scripts/browser-test-build.mjs

@@ -0,0 +1,153 @@
+// The production build of the frontend that every browser-test server serves, as a deployed server does: a page then
+// loads a few bundled files instead of every source module from a development server. The build goes where the app
+// server serves it from (dist/), never a folder of its own: the server tells every page which build it serves from
+// dist/index.html, and a page from any other build offers a reload over the screen. It is reused while its inputs' contents
+// are unchanged and dist/index.html is still the one it made, so a repeated focused run does not rebuild, even though a
+// build rewrites files it generates among its inputs (vue-router's src/typed-router.d.ts). Two runs in one tree build one
+// at a time: the second waits, then reuses the first one's build.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+// What the last browser-test build was made from, and the dist/index.html it made.
+const FINGERPRINT_FILE = path.join("node_modules", ".cache", "jskit-browser-test-build.json");
+// Held, with its holder's process id, while a run builds.
+const BUILD_LOCK = path.join("node_modules", ".cache", "jskit-browser-test-build.lock");
+const BUILD_WAIT_MS = 10 * 60_000;
+const SERVED_INDEX = path.join("dist", "index.html");
+// The app's folders a frontend build reads, and the installed packages it bundles. Every file at the app's root is an
+// input too (index.html, vite.config.*, favicon.svg, package.json, the .env files Vite reads), except other dotfiles,
+// such as caches, and notes.
+const BUILD_DIRECTORIES = Object.freeze(["src", "packages", "shared", "config", "public", "node_modules/@jskit-ai"]);
+const INSTALLED_PACKAGES = "node_modules/.package-lock.json";
+const NOT_AN_INPUT = /^\.(?!env(?:\.|$))|\.(?:md|log|txt)$/u;
+
+const seconds = (since) => `${((performance.now() - since) / 1000).toFixed(1)}s`;
+const digest = (file) => (existsSync(file) ? createHash("sha256").update(readFileSync(file)).digest("hex") : "");
+
+/** Every build input's path and contents, the build command and the VITE_ settings, hashed. */
+function buildFingerprint(appRoot, build, env = process.env) {
+  const hash = createHash("sha256").update(`${build}\n`);
+  const visit = (relative) => {
+    const absolute = path.join(appRoot, relative);
+    if (!existsSync(absolute)) return;
+    const stats = statSync(absolute);
+    if (!stats.isDirectory()) {
+      hash.update(`${relative}\0${stats.size}\0`).update(readFileSync(absolute));
+      return;
+    }
+    for (const entry of readdirSync(absolute).sort()) {
+      if (entry !== "node_modules" && !entry.startsWith(".")) visit(path.join(relative, entry));
+    }
+  };
+  for (const entry of readdirSync(appRoot, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory() && !NOT_AN_INPUT.test(entry.name)) visit(entry.name);
+  }
+  [INSTALLED_PACKAGES, ...BUILD_DIRECTORIES].forEach(visit);
+  for (const [name, value] of Object.entries(env).filter(([key]) => key.startsWith("VITE_")).sort()) {
+    hash.update(`${name}=${value}\n`);
+  }
+  return hash.digest("hex");
+}
+
+function runToCompletion(command, appRoot) {
+  const [program, ...args] = String(command).trim().split(/\s+/u);
+  return new Promise((resolve, reject) => {
+    // The build a deployment serves, whatever NODE_ENV the launcher was given.
+    const child = spawn(program, args, {
+      cwd: appRoot,
+      env: { ...process.env, NODE_ENV: "production" },
+      stdio: ["ignore", "ignore", "inherit"]
+    });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => (code === 0 ? resolve() : reject(new Error(`${command} failed (${signal || `exit ${code}`}).`))));
+  });
+}
+
+function lastBuild(appRoot) {
+  try {
+    return JSON.parse(readFileSync(path.join(appRoot, FINGERPRINT_FILE), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function isRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+
+/** Takes the tree's build lock, waiting while another live run holds it; a dead holder's lock is taken over. */
+async function lockBuild(appRoot) {
+  const lock = path.join(appRoot, BUILD_LOCK);
+  mkdirSync(path.dirname(lock), { recursive: true });
+  const deadline = Date.now() + BUILD_WAIT_MS;
+  let reported = false;
+  while (true) {
+    try {
+      const descriptor = openSync(lock, "wx");
+      writeSync(descriptor, String(process.pid));
+      closeSync(descriptor);
+      return () => rmSync(lock, { force: true });
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    let holder = 0;
+    try {
+      holder = Number.parseInt(readFileSync(lock, "utf8"), 10);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (holder && !isRunning(holder)) {
+      rmSync(lock, { force: true });
+      continue;
+    }
+    if (Date.now() > deadline) throw new Error(`Another run (process ${holder}) has been building the frontend for 10 minutes.`);
+    if (!reported) console.log(`[browser-tests] Waiting for another run's frontend build (process ${holder}).`);
+    reported = true;
+    await new Promise((resolve) => setTimeout(resolve, 200));
+  }
+}
+
+function isCurrent(appRoot, inputs) {
+  const last = lastBuild(appRoot);
+  return last.inputs === inputs && Boolean(last.index) && last.index === digest(path.join(appRoot, SERVED_INDEX));
+}
+
+/**
+ * Builds the frontend with `build` unless dist/ already holds the build of the current inputs.
+ * @param {{ appRoot?: string, build?: string, run?: (command: string, appRoot: string) => Promise<void> }} [options]
+ * @returns {Promise<{ built: boolean }>}
+ */
+async function buildFrontend({ appRoot = process.cwd(), build = "npm run build", run = runToCompletion } = {}) {
+  const started = performance.now();
+  const inputs = buildFingerprint(appRoot, build);
+  if (isCurrent(appRoot, inputs)) {
+    console.log(`[browser-tests] Frontend build unchanged, reused (${seconds(started)}).`);
+    return { built: false };
+  }
+  const unlock = await lockBuild(appRoot);
+  try {
+    // The run that held the lock may have just built these inputs.
+    if (isCurrent(appRoot, inputs)) {
+      console.log(`[browser-tests] Frontend built by another run, reused (${seconds(started)}).`);
+      return { built: false };
+    }
+    await run(build, appRoot);
+    const index = digest(path.join(appRoot, SERVED_INDEX));
+    if (!index) throw new Error(`${build} made no ${SERVED_INDEX}, which the app server serves.`);
+    writeFileSync(path.join(appRoot, FINGERPRINT_FILE), JSON.stringify({ inputs, index }));
+    console.log(`[browser-tests] Frontend built in ${seconds(started)}.`);
+    return { built: true };
+  } finally {
+    unlock();
+  }
+}
+
+export { buildFrontend };

package/scripts/browser-test-servers.mjs

@@ -0,0 +1,132 @@
+// The webServer of a local browser run (browser-tests.mjs): builds the production frontend unless its build is current
+// (browser-test-build.mjs), runs the app's `prepare` module once for every worker's environment (its own database), then
+// starts one app server per Playwright worker, each on its own port, and prints the ready line Playwright waits for.
+// Each worker's server environment is also left, readable only by this user, where the worker's own process takes it
+// (browser-tests.mjs). With the app's `signIn` module, each server is then signed in once, and its storage state left
+// for its worker. Each server's output goes to test-results/browser-test-servers/worker-<n>.log; a server that stops
+// ends the run.
+import { spawn } from "node:child_process";
+import { createWriteStream, mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { buildFrontend } from "./browser-test-build.mjs";
+
+const SETTINGS_VARIABLE = "JSKIT_BROWSER_TESTS";
+const LOG_DIRECTORY = path.join("test-results", "browser-test-servers");
+const READY_TIMEOUT_MS = 60_000;
+
+const seconds = (since) => `${((performance.now() - since) / 1000).toFixed(1)}s`;
+const words = (command) => String(command).trim().split(/\s+/u).filter(Boolean);
+
+/** Each worker's server environment from the app's prepare module, given each worker's base URL, or none. */
+async function prepareWorkers(appRoot, prepare, workers, baseUrls) {
+  if (!prepare) return Array.from({ length: workers }, () => ({}));
+  const { default: prepareWorkerEnvironments } = await import(pathToFileURL(path.resolve(appRoot, prepare)).href);
+  const environments = await prepareWorkerEnvironments({ workers, baseUrls });
+  if (!Array.isArray(environments) || environments.length < workers) {
+    throw new Error(`${prepare} prepared ${environments?.length ?? 0} worker environment(s) for ${workers} worker(s); ` +
+      "let the database user create the copies, or set PLAYWRIGHT_WORKERS lower.");
+  }
+  return environments;
+}
+
+/** Signs each worker's server in once through the app's signIn module, and leaves its storage state for that worker. */
+async function signInWorkers(appRoot, signIn, baseUrls, environments, signedInStates) {
+  const started = performance.now();
+  const { default: signInWorker } = await import(pathToFileURL(path.resolve(appRoot, signIn)).href);
+  // The app's own Playwright, which its tests run on.
+  const { request } = createRequire(path.join(appRoot, "package.json"))("@playwright/test");
+  await Promise.all(baseUrls.map(async (baseURL, index) => {
+    const context = await request.newContext({ baseURL });
+    try {
+      await signInWorker({ request: context, baseURL, workerIndex: index, env: environments[index] });
+      // It holds a session's cookies: only this user may read it.
+      writeFileSync(`${signedInStates}-${index}.json`, JSON.stringify(await context.storageState()), { mode: 0o600 });
+    } finally {
+      await context.dispose();
+    }
+  }));
+  console.log(`[browser-tests] ${baseUrls.length} worker(s) signed in in ${seconds(started)}.`);
+}
+
+async function waitUntilReady(url, server, name) {
+  const started = performance.now();
+  const deadline = Date.now() + READY_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (server.exitCode !== null || server.signalCode !== null) throw new Error(`${name} stopped while starting.`);
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(2_000) });
+      if (response.ok) {
+        console.log(`[browser-tests] ${name} started in ${seconds(started)}.`);
+        return;
+      }
+    } catch {
+      // Not listening yet.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`${name} was not ready at ${url} within ${READY_TIMEOUT_MS / 1000}s.`);
+}
+
+const servers = [];
+let stopping = false;
+function stopServers() {
+  stopping = true;
+  for (const server of servers) server.kill("SIGTERM");
+}
+process.once("SIGINT", () => { stopServers(); process.exit(130); });
+process.once("SIGTERM", () => { stopServers(); process.exit(143); });
+process.once("exit", stopServers);
+
+const started = performance.now();
+const appRoot = process.cwd();
+const {
+  workers, host, basePort, server, build, prepare, env, health, workerEnvironments: workerEnvironmentsFile, signIn,
+  signedInStates
+} = JSON.parse(process.env[SETTINGS_VARIABLE] || "{}");
+const baseEnvironment = { ...process.env };
+delete baseEnvironment[SETTINGS_VARIABLE];
+const baseUrls = Array.from({ length: workers }, (_, index) => `http://${host}:${basePort + index}`);
+try {
+  const [, workerEnvironments] = await Promise.all([
+    buildFrontend({ appRoot, build }),
+    prepareWorkers(appRoot, prepare, workers, baseUrls)
+  ]);
+  mkdirSync(path.join(appRoot, LOG_DIRECTORY), { recursive: true });
+  mkdirSync(path.dirname(workerEnvironmentsFile), { recursive: true });
+  writeFileSync(workerEnvironmentsFile, JSON.stringify(workerEnvironments.slice(0, workers)), { mode: 0o600 });
+  const [program, ...args] = words(server);
+  const serverEnvironments = workerEnvironments.slice(0, workers).map((workerEnvironment, index) => ({
+    ...baseEnvironment,
+    ...env,
+    ...workerEnvironment,
+    HOST: host,
+    PORT: String(basePort + index),
+    TEST_PARALLEL_INDEX: String(index)
+  }));
+  await Promise.all(serverEnvironments.map((serverEnvironment, index) => {
+    const baseUrl = baseUrls[index];
+    const name = `The browser test server of worker ${index} (${baseUrl})`;
+    const log = path.join(LOG_DIRECTORY, `worker-${index}.log`);
+    const child = spawn(program, args, { cwd: appRoot, env: serverEnvironment, stdio: ["ignore", "pipe", "pipe"] });
+    const output = createWriteStream(path.join(appRoot, log));
+    child.stdout.pipe(output);
+    child.stderr.pipe(output);
+    child.once("exit", (code, signal) => {
+      if (stopping) return;
+      console.error(`[browser-tests] ${name} stopped (${signal || `exit ${code}`}); log: ${log}`);
+      stopServers();
+      process.exit(1);
+    });
+    servers.push(child);
+    return waitUntilReady(new URL(health, baseUrl), child, name);
+  }));
+  if (signIn) await signInWorkers(appRoot, signIn, baseUrls, serverEnvironments, signedInStates);
+  console.log(`jskit browser tests: ${workers} server(s) ready in ${seconds(started)}; logs in ${LOG_DIRECTORY}.`);
+} catch (error) {
+  console.error(`[browser-tests] ${error.message}`);
+  stopServers();
+  process.exit(1);
+}

package/scripts/browser-test-times.mjs

@@ -0,0 +1,33 @@
+import path from "node:path";
+import process from "node:process";
+
+const SLOWEST_REPORTED = 10;
+
+// A Playwright reporter (browser-tests.mjs adds it beside "list"): every run ends with its slowest tests and their
+// times, so a test that got slow shows instead of hiding inside a longer run.
+class SlowestTests {
+  constructor() {
+    this.times = [];
+  }
+
+  onTestEnd(test, result) {
+    const file = path.relative(process.cwd(), test.location.file);
+    this.times.push({ name: `${file}:${test.location.line} ${test.title}`, duration: result.duration, status: result.status });
+  }
+
+  onEnd() {
+    const slowest = [...this.times].sort((left, right) => right.duration - left.duration).slice(0, SLOWEST_REPORTED);
+    if (slowest.length < 1) return;
+    const lines = [`[test-time] Slowest ${slowest.length} of ${this.times.length} tests:`];
+    for (const { name, duration, status } of slowest) {
+      lines.push(`[test-time]   ${(duration / 1000).toFixed(1)} s  ${name}${status === "passed" ? "" : ` (${status})`}`);
+    }
+    process.stdout.write(`${lines.join("\n")}\n`);
+  }
+
+  printsToStdio() {
+    return true;
+  }
+}
+
+export default SlowestTests;

package/scripts/browser-tests.mjs

@@ -0,0 +1,166 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { testConcurrency } from "./test-budget.mjs";
+
+// An application's Playwright configuration: `defineConfig(browserTestConfig({ ... }))`. A local run builds the
+// production frontend once (cached by its sources) and starts one app server per Playwright worker, each on its own port
+// and, through the app's `prepare` module, its own database, so workers run in parallel without sharing data
+// (browser-test-servers.mjs). With the app's `signIn` module, each worker's server is signed in once and every test of
+// that worker starts from its signed-in state. With PLAYWRIGHT_BASE_URL set, the tests use that managed target instead,
+// as its host serves it and with the login state its host supplies, one worker at a time unless the runner sets
+// PLAYWRIGHT_WORKERS.
+
+const SERVERS = fileURLToPath(new URL("./browser-test-servers.mjs", import.meta.url));
+const SLOWEST_TESTS = fileURLToPath(new URL("./browser-test-times.mjs", import.meta.url));
+const SETTINGS_VARIABLE = "JSKIT_BROWSER_TESTS";
+const READY = /^jskit browser tests: \d+ server\(s\) ready/mu;
+const HOST = "127.0.0.1";
+const DEFAULT_PORT = 4173;
+// A whole run's default bound: a suite that would take hours stops instead, and says so. A suite measured to need
+// longer passes its own globalTimeout, with the measurement beside it.
+const GLOBAL_TIMEOUT_MS = 20 * 60_000;
+// Building the frontend when its sources changed, preparing the databases and starting every server.
+const SERVERS_TIMEOUT_MS = 180_000;
+// Where the servers' launcher leaves each worker's server environment, for that worker's own process.
+const WORKER_ENVIRONMENTS = path.join("node_modules", ".cache", "jskit-browser-tests");
+
+const positiveInteger = (value) => (/^[1-9]\d*$/u.test(String(value ?? "").trim()) ? Number(String(value).trim()) : 0);
+
+function managedBaseUrl(env) {
+  return String(env.PLAYWRIGHT_BASE_URL || "").trim().replace(/\/+$/u, "");
+}
+
+/**
+ * The `--workers`/`-j` count given on the Playwright command line, or 0. A percentage is refused: the servers are
+ * started before Playwright resolves it.
+ * @param {ReadonlyArray<string>} argv
+ */
+function commandLineWorkers(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const match = /^(?:--workers|-j)(?:=(.*))?$/u.exec(argv[index]);
+    if (!match) continue;
+    const value = String(match[1] ?? argv[index + 1] ?? "").trim();
+    const count = positiveInteger(value);
+    if (!count) throw new Error(`Give --workers a whole number of workers, not ${value || "nothing"}.`);
+    return count;
+  }
+  return 0;
+}
+
+/**
+ * How many workers a browser run uses: the command line's `--workers`, else PLAYWRIGHT_WORKERS, else half the machine's
+ * test budget for a local run and 1 for a managed target (one server). A local worker drives a browser and its own app
+ * server, about two threads' work: with a budget of 4, the shell foundation's 9 tests took 11.5 s on 4 workers and
+ * 7.9 s on 2.
+ * @param {{ env?: Record<string, string | undefined>, argv?: ReadonlyArray<string> }} [options]
+ */
+function browserTestWorkers({ env = process.env, argv = process.argv } = {}) {
+  return commandLineWorkers(argv) || positiveInteger(env.PLAYWRIGHT_WORKERS) ||
+    (managedBaseUrl(env) ? 1 : Math.max(1, Math.floor(testConcurrency({ env }) / 2)));
+}
+
+/** The environment the launcher gave worker `index`'s server, from the app's prepare module, or none. */
+function preparedWorkerEnvironment(file, index) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))[index] ?? {};
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+/**
+ * The Playwright configuration of an application's browser tests.
+ * @param {object} [options]
+ * @param {string} [options.testDir] Where the specs are.
+ * @param {number} [options.port] The first worker's port; worker n uses port + n. PLAYWRIGHT_PORT overrides it.
+ * @param {string} [options.server] The command that starts the app server, reading PORT and HOST.
+ * @param {string} [options.build] The command that builds the production frontend into the folder the server serves.
+ * @param {string} [options.prepare] An app module, run once before the servers start, whose default export
+ *   `({ workers, baseUrls })` returns each worker's server environment, such as its own DB_NAME. The worker's own
+ *   process gets it too, so a test that opens the database itself reaches its own server's copy.
+ * @param {string} [options.signIn] An app module whose default export `({ request, baseURL, workerIndex, env })` signs
+ *   `request`, a Playwright APIRequestContext on one worker's server (`env` is that server's environment), in once,
+ *   such as with `loginRequestAsExistingUser()` from @jskit-ai/auth-web/test/playwright. Each of that worker's tests
+ *   starts from the signed-in state, which its process also finds in PLAYWRIGHT_STORAGE_STATE, as on a managed target.
+ *   A test that must start signed out uses `test.use({ storageState: { cookies: [], origins: [] } })`; one that signs
+ *   out or ends sessions signs in on its own first, so the worker's shared session lives on.
+ * @param {Record<string, string>} [options.env] Environment every server gets, such as its test-only drivers.
+ * @param {string} [options.health] The path that answers 200 once a server is ready.
+ * @param {number} [options.globalTimeout] The whole run's bound in milliseconds (20 minutes); never 0.
+ * @param {Record<string, string | undefined>} [options.environment] Read, and given a worker's prepared environment,
+ *   instead of process.env (tests).
+ * @param {string} [options.cwd] The directory Playwright runs in (tests).
+ */
+function browserTestConfig({
+  testDir = "./tests/e2e",
+  port = DEFAULT_PORT,
+  server = "node ./bin/server.js",
+  build = "npm run build",
+  prepare = "",
+  signIn = "",
+  env = {},
+  health = "/api/health",
+  globalTimeout = GLOBAL_TIMEOUT_MS,
+  environment = process.env,
+  cwd = process.cwd()
+} = {}) {
+  if (!Number.isInteger(globalTimeout) || globalTimeout < 1) {
+    throw new Error("browserTestConfig() needs a globalTimeout of at least 1 ms; a run is always bounded.");
+  }
+  const managed = managedBaseUrl(environment);
+  const workers = browserTestWorkers({ env: environment });
+  const basePort = positiveInteger(environment.PLAYWRIGHT_PORT) || port;
+  // A Playwright worker loads this config again, with its own TEST_PARALLEL_INDEX, and reaches its own server; its
+  // process takes the environment prepare gave that server, such as its DB_NAME, before any test file loads.
+  const workerIndex = managed ? 0 : Number.parseInt(String(environment.TEST_PARALLEL_INDEX || "0"), 10) || 0;
+  const workerEnvironments = path.resolve(cwd, WORKER_ENVIRONMENTS, `workers-${basePort}.json`);
+  // A login state the host supplies is used as it is; the servers sign in only when there is none.
+  const signedInStates = signIn && !managed && !String(environment.PLAYWRIGHT_STORAGE_STATE || "").trim()
+    ? path.resolve(cwd, WORKER_ENVIRONMENTS, `signed-in-${basePort}`)
+    : "";
+  if (!managed && environment.TEST_PARALLEL_INDEX !== undefined) {
+    Object.assign(environment, preparedWorkerEnvironment(workerEnvironments, workerIndex));
+    if (signedInStates) environment.PLAYWRIGHT_STORAGE_STATE = `${signedInStates}-${workerIndex}.json`;
+  }
+  const storageState = String(environment.PLAYWRIGHT_STORAGE_STATE || "").trim();
+  const settings = {
+    workers, host: HOST, basePort, server, build, prepare, env, health, workerEnvironments,
+    ...(signedInStates ? { signIn, signedInStates } : {})
+  };
+
+  return {
+    testDir,
+    workers,
+    globalTimeout,
+    timeout: 60_000,
+    expect: { timeout: 10_000 },
+    // Every run ends with its 10 slowest tests and their times.
+    reporter: [["list"], [SLOWEST_TESTS]],
+    use: {
+      baseURL: managed || `http://${HOST}:${basePort + workerIndex}`,
+      headless: true,
+      // A click, fill or navigation waiting on something that never comes fails in seconds, with its own error.
+      actionTimeout: 15_000,
+      navigationTimeout: 30_000,
+      // A failed test keeps its trace to read; no screencast is recorded while tests run.
+      trace: { mode: "retain-on-failure", screenshots: false, snapshots: true, sources: true },
+      ...(storageState ? { storageState } : {})
+    },
+    ...(managed ? {} : {
+      webServer: {
+        command: `node ${JSON.stringify(SERVERS)}`,
+        env: { [SETTINGS_VARIABLE]: JSON.stringify(settings) },
+        wait: { stdout: READY },
+        timeout: SERVERS_TIMEOUT_MS,
+        stdout: "pipe",
+        stderr: "pipe",
+        gracefulShutdown: { signal: "SIGTERM", timeout: 10_000 }
+      }
+    })
+  };
+}
+
+export { SETTINGS_VARIABLE, browserTestConfig, browserTestWorkers };

package/scripts/jskit.mjs

@@ -42,7 +42,10 @@ function usage() {
     "               page without a declared parent, or a main-navigation page that declares one. It also fails when",
     "               a package script runs tests outside the machine's test budget (test/*): node --test instead of",
     "               jskit test, a fixed test concurrency or worker count, or a Playwright or Vitest config whose",
-    "               workers do not come from testConcurrency() of @jskit-ai/jskit-catalog/test-budget.",
+    "               workers do not come from testConcurrency() of @jskit-ai/jskit-catalog/test-budget. A Playwright",
+    "               config with a webServer uses browserTestConfig() of @jskit-ai/jskit-catalog/browser-tests (one",
+    "               production-build server and database per worker), never a development server, and every one",
+    "               has a globalTimeout.",
     "  check m3     List application UI source that departs from the JSKIT Material 3 guide, each finding with its",
     "               guide section: the whole app, or only the given files and directories (a section, or a task's",
     "               changed files). Its visual rules (m3/*) are a report; its nav/* rules are plain jskit check's.",
@@ -53,7 +56,9 @@ function usage() {
     "  test         Run node --test with these arguments, test files in parallel within the machine's test budget:",
     "               V64_TEST_CONCURRENCY when it is a positive whole number, otherwise half of the machine's CPUs",
     "               (at least 1). A file whose first line is `// jskit-test: alone - <reason>` runs after the others,",
-    "               on its own.",
+    "               on its own. With --databases, each file running at once gets its own copy of TEST_DB_NAME,",
+    "               restored from a schema snapshot (the app's knexfile.js and @jskit-ai/database-runtime); with no",
+    "               usable TEST_DB_NAME, the files run one at a time on the connected database.",
     "",
     "<locale> is a BCP 47 language tag, such as fr or pt-BR."
   ].join("\n");