예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리
브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을
지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/
04-frontend-layout.md 9.2절 2단계 (1)).
두 갤러리 화면을 그대로 src/presentation/design-system/
galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는
preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual
설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고
(TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은
scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운
골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의
갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화
상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다.
위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰
변화는 옛 골든처럼 새 골든도 잡지 못한다.
검증(desktop): test:storybook 6 passed, test:visual 7 passed,
playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을
파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px
차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다.
미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface
색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
202 lines
8.0 KiB
TypeScript
202 lines
8.0 KiB
TypeScript
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/<id>/`, at the paths they have in the checkout:
|
|
* `artifacts/tests/e2e/results` becomes
|
|
* `.tmp/runs/<id>/artifacts/tests/e2e/results`, `dist` becomes
|
|
* `.tmp/runs/<id>/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<Record<string, string | undefined>>;
|
|
|
|
const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
|
|
|
|
/** `.` without a run ID, `.tmp/runs/<id>` 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<Record<string, string | undefined>> = 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<number> {
|
|
return new Promise<number>((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<string, string | undefined> = process.env,
|
|
find: () => Promise<number> = findFreePort,
|
|
): Promise<number> {
|
|
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}`;
|
|
}
|