import { createServer } from "node:net"; import path from "node:path"; /** * 1105/12-04. Where one run writes, so that two runs in one checkout do not * overwrite each other's build, results and reports. * * Two variables, read by different code: * * - `TEST_RUN_ID` names a Playwright run. The Playwright configs put its * results, HTML report, JUnit file and the build its web server serves under * `.tmp/runs//`, at the paths they have in the checkout: * `artifacts/tests/e2e/results` becomes * `.tmp/runs//artifacts/tests/e2e/results`, `dist` becomes * `.tmp/runs//dist`. Unset, a run writes where it always did, which is * where the gates, the CI upload and the evidence checks read. * - `RUN_OUTPUT_ROOT` is what a Playwright config hands its web server. The * build (`scripts/build-frontend.ts` and every step it runs) writes `dist/`, * `.generated/frontend-runtime/` and its `artifacts/` evidence under it, and * Vite keeps its cache there. Build code reads only this variable, never * `TEST_RUN_ID`: a test that builds a copy of the repository inherits the * runner's environment and must still build into the copy's own `dist`. * * Both roots are `.` or a folder under `.tmp/`. Git ignores `.tmp/`, and so do * Tailwind's source scan (a Playwright report there would add classes to the * CSS), Vite's file watcher, Vitest and the e2e helpers that copy the * repository. * * Ports are separate from the run ID: every config serves on a free port * unless its `TEST_*_PORT` variable pins one (`TEST_PORT_VARIABLES`), so two * checkouts on one machine do not collide either. */ export const TEST_RUN_ID_VARIABLE = "TEST_RUN_ID"; export const RUN_OUTPUT_ROOT_VARIABLE = "RUN_OUTPUT_ROOT"; export const TEST_RUN_DIRECTORY = ".tmp/runs"; type Environment = Readonly>; const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u; /** `.` without a run ID, `.tmp/runs/` with one. */ export function testRunRoot(environment: Environment = process.env): string { const runId = environment[TEST_RUN_ID_VARIABLE]; if (runId === undefined || runId === "") return "."; if (!RUN_ID.test(runId)) { throw new TypeError( `${TEST_RUN_ID_VARIABLE} must be 1 to 64 letters, digits, ".", "_" or "-", ` + `starting with a letter or digit; received ${JSON.stringify(runId)}`, ); } return `${TEST_RUN_DIRECTORY}/${runId}`; } /** `relativePath` as this run writes it: unchanged without a run ID. */ export function testRunPath( relativePath: string, environment: Environment = process.env, ): string { return path.posix.join(testRunRoot(environment), relativePath); } /** `.` when unset; otherwise a normalized folder under `.tmp/`. */ export function runOutputRoot(environment: Environment = process.env): string { const declared = environment[RUN_OUTPUT_ROOT_VARIABLE]; if (declared === undefined || declared === "") return "."; const root = path.posix.normalize(declared).replace(/\/+$/u, ""); if (root === ".") return "."; if (declared.includes("\\") || !root.startsWith(".tmp/") || root.split("/").includes("..")) { throw new TypeError( `${RUN_OUTPUT_ROOT_VARIABLE} must be "." or a folder under .tmp/ in this checkout; ` + `received ${JSON.stringify(declared)}`, ); } return root; } /** `relativePath` as the build writes it: unchanged without an output root. */ export function runOutputPath( relativePath: string, environment: Environment = process.env, ): string { return path.posix.join(runOutputRoot(environment), relativePath); } /** * 1106/12-02. Why `step`, which reads the build where the checkout keeps it * (`dist/`, the build manifest and the evidence under `artifacts/`), must not * run in this environment; `undefined` when it may. With RUN_OUTPUT_ROOT set * the build writes under that folder, so such a step would judge whatever * build the checkout still holds: check:bundle passed an over-budget build * that way, on the earlier one. `.` is the checkout itself, which is what a * Playwright config hands its web server without a run ID. */ export function checkoutBuildReadFailure( step: string, environment: Environment = process.env, ): string | undefined { let root: string; try { root = runOutputRoot(environment); } catch (error) { return `${step}: ${error instanceof Error ? error.message : String(error)}`; } if (root === ".") return undefined; return ( `${step} reads the build at this checkout's paths (dist/, artifacts/), but ` + `${RUN_OUTPUT_ROOT_VARIABLE}=${root} makes the build write under ${root}/, so it ` + `would judge an earlier build. Unset ${RUN_OUTPUT_ROOT_VARIABLE}, build again and ` + `run ${step} again.` ); } /** * The port variable of each Playwright config's web server. Unset, the config * picks a free port; set, it uses that one (to pin a port while debugging). * `visualWorkshop` is the visual config's second server, the static workshop * the gallery goldens open. */ export const TEST_PORT_VARIABLES = Object.freeze({ e2e: "TEST_E2E_PORT", visual: "TEST_VISUAL_PORT", visualWorkshop: "TEST_VISUAL_WORKSHOP_PORT", capabilities: "TEST_CAPABILITIES_PORT", storybook: "TEST_STORYBOOK_PORT", dev: "TEST_DEV_PORT", } as const); /** * The origin of a config's second server, for its specs. The runner reserved * the port in `variable` (reservePort) and its workers inherit it. */ export function reservedOrigin( variable: string, environment: Readonly> = process.env, ): string { const port = environment[variable]; if (port === undefined || port === "") { throw new Error(`${variable} is not set: run this spec through its Playwright config`); } return `http://127.0.0.1:${port}`; } /** * A port nothing listens on now: the one the kernel gives a socket bound to * port 0, which is closed again. Another process can still take it before the * web server binds it. The configs start their servers with `--strictPort` * (vite) or a fixed `listen` (serve-static) and `reuseExistingServer: false`, * so that case is a start failure, never a run against someone else's server. */ export async function findFreePort(host = "127.0.0.1"): Promise { return new Promise((resolve, reject) => { const server = createServer(); server.unref(); server.once("error", reject); server.listen(0, host, () => { const address = server.address(); server.close(() => { if (address !== null && typeof address === "object") resolve(address.port); else reject(new Error(`no port was bound on ${host}`)); }); }); }); } /** * The port one config's web server listens on, kept in `variable`. * * Playwright evaluates the config again in each worker process, and the * workers inherit the runner's environment. The runner's evaluation writes * the port it picked into `variable`; the workers' evaluations read it, so * `baseURL` is the same everywhere. A value already set is used as given. */ export async function reservePort( variable: string, environment: Record = process.env, find: () => Promise = findFreePort, ): Promise { const pinned = environment[variable]; if (pinned !== undefined && pinned !== "") { const port = Number(pinned); if (!/^\d+$/u.test(pinned) || port < 1 || port > 65_535) { throw new TypeError( `${variable} must be a port from 1 to 65535; received ${JSON.stringify(pinned)}`, ); } return port; } const port = await find(); environment[variable] = String(port); return port; } /** * The import specifier a generated module at `fromFile` uses for `toFile`, * both relative to the checkout. A generated module under an output root sits * deeper than `.generated/` and needs more `../`. */ export function moduleSpecifier(fromFile: string, toFile: string): string { const specifier = path.posix.relative(path.posix.dirname(fromFile), toFile); return specifier.startsWith(".") ? specifier : `./${specifier}`; }