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); } /** * 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). */ export const TEST_PORT_VARIABLES = Object.freeze({ e2e: "TEST_E2E_PORT", visual: "TEST_VISUAL_PORT", capabilities: "TEST_CAPABILITIES_PORT", storybook: "TEST_STORYBOOK_PORT", dev: "TEST_DEV_PORT", } as const); /** * 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}`; }