예제 화면 /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)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다.
문제: 다섯 Playwright 설정의 서버 포트가 고정이다(e2e 4173, visual과
capability가 둘 다 4174, storybook 6006, dev 5173). 한 checkout이든 같은
기계의 두 worktree든 두 번째 실행은 `http://127.0.0.1:4173 is already
used`로 시작하지 못한다(00-R1). dev 설정만 `reuseExistingServer: true`라
5173에 다른 checkout·브랜치의 dev 서버가 떠 있으면 말없이 그 서버를
검사한다. vite는 `--strictPort` 없이 떠서, 포트가 그 사이 잡히면 다음
포트로 옮기고 Playwright는 원래 URL의 남의 서버를 검사할 수 있다
(1105/12-04).
고른 방법: 설정마다 `reservePort(TEST_<이름>_PORT)`로 빈 포트를 고른다
(`scripts/lib/run-isolation.ts`). 커널이 port 0에 준 포트를 받고 바로
닫는다. 고른 포트를 그 변수에 써 둔다. Playwright는 worker마다 설정을
다시 평가하고 worker는 runner 환경을 물려받으므로, worker의 평가가 같은
포트를 읽어 `baseURL`이 어디서나 같다. 변수를 미리 주면 그 포트를 쓴다
(디버깅용 고정). vite 서버 넷 모두 `--strictPort`로 띄우고, dev 설정은
`reuseExistingServer: false`로 바꿨다. run ID가 없어도 빈 포트를 쓴다.
두 worktree는 출력 경로가 이미 다르고 포트만 부딪히기 때문이다. 고정
번호를 읽는 곳은 없다. spec은 `baseURL`에서 origin을 얻는다
(`resumable-upload.spec.ts`, `production-csp.spec.ts`).
버린 대안: 포트 범위를 run ID에서 계산하기. 두 checkout이 같은 run ID를
쓰거나 다른 프로그램이 그 포트를 쓰면 다시 부딪힌다. Playwright
`webServer.wait`로 서버가 고른 포트를 stdout에서 읽기: `use.baseURL`은
설정을 읽을 때 정해져서 쓸 수 없다.
위험·한계: 포트를 고른 뒤 서버가 잡기 전에 다른 프로세스가 같은 포트를
잡을 수 있다. 그때는 `--strictPort`/serve-static의 listen 실패나
Playwright의 "already used"로 시작이 실패한다. 남의 서버로 검사가 새지
않는다. 기본 실행의 포트 번호가 매번 달라진다. 고정이 필요하면
`TEST_E2E_PORT=4173`처럼 준다. `test:e2e:dev`는 이제 떠 있는 dev 서버를
쓰지 않고 자기 서버를 띄운다. capability 설정이 없는 사본
(test:browser-file-storage-removal)에서는 그 설정의 포트 테스트를 돌리지 않는다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts
corepack pnpm test:browser-file-storage-removal
Refs: 1105/12-04
문제: 빌드는 `dist`, `.generated/frontend-runtime`, `artifacts/release`·
`artifacts/quality`에 고정으로 쓰고, 다섯 Playwright 설정은 결과·report·
JUnit을 `artifacts/tests/<이름>/`에 고정으로 쓴다. 한 checkout에서 두
번째 e2e 실행이 시작하면 빌드 1단계가 첫 실행의 preview가 서빙 중인
`dist`를 지우고, Playwright가 `outputDir`을 비워 첫 실행의 trace를 지운다.
증거 파일도 늦게 끝난 쪽 것으로 섞인다(1105/12-04).
고른 방법: 변수 두 개로 나눈다(`scripts/lib/run-isolation.ts`).
- `TEST_RUN_ID`: Playwright 설정이 읽는다. 값이 있으면 그 실행의 결과·
report·JUnit과 서빙할 빌드를 `.tmp/runs/<id>/` 아래 같은 상대 경로에
둔다. 없으면 지금 경로 그대로라 게이트, CI upload, 증거 검사가 읽는
곳이 바뀌지 않는다.
- `RUN_OUTPUT_ROOT`: 설정이 web server에만 넘긴다. 빌드 단계 전부
(`build-frontend`, contract set, runtime config, SW asset 목록, SW 빌드,
build manifest)와 `vite.config.ts`가 읽어 `dist`·생성 모듈·증거·Vite
캐시를 그 아래에 쓴다. preview는 `--outDir`로 같은 `dist`를 서빙한다.
빌드 코드는 `TEST_RUN_ID`를 읽지 않는다. e2e worker가 저장소 복사본을
빌드할 때(fixture-builds, service-worker-builds) runner 환경을 물려받는데,
그 빌드는 복사본 자기 `dist`에 써야 하기 때문이다.
두 루트는 `.` 또는 `.tmp/` 아래만 받는다. git, Tailwind 소스 스캔(report
안 문자열이 CSS에 들어가지 않게), Vite watcher, vitest, 저장소 복사
helper가 모두 `.tmp`를 건너뛴다. service-worker-builds의 복사 제외 목록에
`.tmp`를 더했다(fixture-builds와 같아짐). build manifest의 경로는 빌드가
쓴 폴더 기준 상대 경로로 둔다.
`vite.config.ts`가 새로 가져오는 `scripts/lib/run-isolation.ts`는 저장소
일부를 임시 루트에 복사해 빌드하는 두 목록(초기 JS 측정
`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에도 더한다.
Storybook은 run ID가 있으면 `build:storybook`의 두 단계를 다른 `-o`로
돌린다. 같은 단계인지는 단위 테스트가 package script와 대조한다.
버린 대안: 운영 증거 경로(54개 스크립트, `config/ci/gates.json`)까지 run
ID로 옮기기. 게이트와 workflow upload가 고정 경로를 읽으므로 이번 범위
밖이다(아래 한계). 실행마다 저장소를 임시 폴더로 복사하기: 매번 수십
MB 복사와 node_modules 링크가 들고, 개발자가 보는 결과 위치가 사라진다.
위험·한계: 포트는 아직 고정이라 이 커밋만으로는 두 실행이 함께 돌지
못한다(다음 커밋). `ci:gate`와 증거 검사(`check:test-evidence`,
`verify:browser-capability-evidence`)는 기본 경로만 읽는다. run ID를 준
채 게이트를 돌리면 증거가 기본 경로에 새로 생기지 않아 게이트가 "not
freshly produced"로 실패한다(통과로 새지 않는다). Storybook 내부 캐시
(`node_modules/.cache`)는 여전히 공유한다. capability 설정
(`playwright.capabilities.config.ts`)은 test:browser-file-storage-removal이
capability와 함께 지운다. 설정 테스트는 그 파일이 있을 때만 그 설정을 읽고,
경로를 변수로 두어 타입 검사가 그 파일을 요구하지 않는다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/run-isolation.test.ts tests/unit/playwright-run-isolation.test.ts tests/unit/run-output-root-build.test.ts
node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
corepack pnpm test:browser-file-storage-removal
Refs: 1105/12-04
문제
workflow는 모든 job에 CI=true와 CI 빌드 식별값을 준다. 메인 세션이 깨끗한
clone에서 그 env 그대로(CI=true 포함) merge 단계 14개를 돌리자 FE-GATE-005·
008·020이 실패했다.
- vitest 안의 fixture 빌드(tests/e2e/support/fixture-builds.ts →
build-frontend.ts)가 CI=true를 물려받아 release 빌드처럼 검사된다.
af312de가 vitest에서 VITE_COMMIT_SHA를 지워 "missing required CI build
environment: VITE_COMMIT_SHA"로 멈춘다(service-worker-build-output 7건이
돌지 않음, 제거 드릴 안에서도 같다).
- 시각 골든 build(9bddfa5)가 VITE_COMMIT_SHA="local"을 받는데 CI=true가
40·64자리 hex를 요구해 webServer가 뜨지 않는다.
내 X4가 CI=true 없이 돌아 놓쳤다. 1103/11-07과 같은 원인이다.
고른 방법
- scripts/lib/build-environment.ts에 둘을 둔다.
- localBuildEnvironment(env): spawn하는 로컬 빌드용. CI와 CI 빌드 식별값을
뺀 사본. fixture-builds.ts, service-worker-builds.ts가 쓴다.
- LOCAL_BUILD_IDENTITY: Playwright web server용. Playwright가 env를
process.env 위에 합치므로 CI를 지우지 않고 ""로 덮는다(검사는
CI === "true"일 때만). visual·capabilities·dev 설정이 쓴다.
- assertCiBuildEnvironment의 CI=true 검사는 그대로다. job 자신의 release
빌드(build:release-candidate 등)는 계속 검사된다.
- 버린 대안: 로컬 빌드에 유효한 가짜 커밋 id(0×40)를 주기. CI=true 검사의
다른 칸(CI_RUNNER_IMAGE, SOURCE_DATE_EPOCH)도 함께 맞춰야 하고, 로컬
빌드가 release 빌드인 척한다.
위험·한계
- 로컬 빌드 안에서 CI를 읽어 동작을 바꾸는 코드가 있으면 그 빌드는 이제
CI가 아닌 쪽으로 돈다(지금은 build-environment 검사뿐이다).
검증
- tests/unit/local-build-environment.test.ts 3건: 구현 전 2건 실패(RED),
CI job 자체 검사는 유지.
- CI=true·VITE_COMMIT_SHA·VITE_BUILD_ID=gitea-41-1·RELEASE_ID·
CI_RUNNER_IMAGE·SOURCE_DATE_EPOCH로: service-worker-build-output 7건,
test:visual 6/6, test:unit 2,883, test:component 270, test:integration 189
통과. 수정 전 service-worker-build-output은 7건 미실행.
- check:types, lint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-08
문제
홈 화면과 플랫폼 구성 화면은 build id와 release id를 글자로 그린다. CI는
workflow 전체에 VITE_BUILD_ID·VITE_COMMIT_SHA·RELEASE_ID를 준다. 그래서
test:visual(FE-GATE-008)의 build가 골든과 다른 글자를 그려, 셸 넓은 화면·
좁은 서랍·플랫폼 구성 3장이 1,109~1,545 px 달라 항상 실패한다. 깨끗한
clone에 CI env를 준 merge 단계 재실행에서 찾았다(af312de와 같은 원인,
1103/11-07).
고른 방법
- playwright.visual.config.ts webServer env로 로컬 식별값(local-build,
local, local-release)을 준다. 골든은 템플릿의 모양 계약이고 그 값으로
찍었다.
- 버린 대안: 식별값 글자를 화면마다 가리기. 가릴 곳이 화면마다 늘고,
식별값을 그리는 새 화면이 생길 때마다 다시 빠진다.
위험·한계
- 시각 테스트의 build는 CI 식별값을 쓰지 않는다. 식별값 표시 자체는
e2e(compact smoke, 11-06)가 CI 값으로 본다.
검증
- VITE_BUILD_ID=gitea-1-1·VITE_COMMIT_SHA·RELEASE_ID를 주고 test:visual 6/6,
env 없이 6/6 통과. 수정 전 CI env에서 3건 실패.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-07
문제: 시각 회귀 허용치가 maxDiffPixelRatio 0.002(이미지의 0.2%)라서
긴 화면일수록 허용 픽셀이 커진다. 넓은 셸 1440×900은 2,592 px를
허용한다. 그래서 UI-04 수정을 되돌린 회귀(선택 상자 값 잘림, 1,145 px)가
통과한다. 골든이 코드와 조금씩 달라져도 실패하지 않아 어느 골든이 낡았는지
알 수 없다. VD-08 8항은 작은 rasterization 차이만 허용한다고 적는다.
고른 방법: maxDiffPixels 50. 11-02로 글꼴과 래스터 설정을 고정한 뒤
같은 호스트에서 깨끗한 빌드를 다시 찍으면 0 px 차이다(아래 검증). 50은
흩어진 anti-aliasing만 덮고, 지금까지 잰 가장 작은 실제 변화(낡은
compact 골든 175 px)보다 작다. tests/unit/visual-regression-tolerance.test.ts가
비율 허용치가 다시 들어오거나 절대값이 175 이상이 되면 실패한다.
버린 대안:
- 0 px: 이 호스트에서는 흔들리지 않았지만 다른 Linux 러너의 래스터는
재 보지 못했다(U-1). 50은 실제 회귀를 놓치지 않는 범위의 여유다.
- 위험 영역만 따로 찍어 비율의 분모를 줄이기: 골든이 늘어난다.
- 현상 유지: 회귀를 놓친다.
위험·한계:
- 커밋된 골든 2장이 새 허용치에서 실패한다. 깨끗한 빌드 기준으로 넓은
셸 614 px, compact 6,955 px 다르다. compact는 이 변경 전 0.2%에서도
이미 실패한다(08-01의 서랍 변경). 골든은 다시 찍지 않았다. 오케스트레이터가
마지막에 한 번 찍는다. 나머지 3장은 0 px로 통과한다.
- 다른 호스트의 래스터 차이는 재 보지 못했다. 수십 px 넘게 나오면 그
측정값으로 허용치를 정한다(리뷰 재검토 조건).
검증 (pnpm을 부르지 않으려고 build-frontend.ts로 빌드하고 webServer만
vite preview로 바꾼 로컬 설정 사본으로 실행, flock, 비교 대상은 깨끗한
빌드로 새로 찍은 scratch 골든. 저장소 골든은 건드리지 않았다):
- 깨끗한 빌드 vs scratch 골든, 허용치 0, --repeat-each=3: 16 passed.
- RED: UI-04 변이(f1b9d3c의 shell.css 변경을 git apply -R)를 넣은 빌드,
0.2% 비율: 6 passed. 허용치 0: 넓은 셸만 "1145 pixels are different".
- GREEN: 같은 변이, maxDiffPixels 50: 넓은 셸 실패(1,145 px), 나머지 통과.
변이를 되돌리고 다시 빌드, --repeat-each=2: 11 passed.
- 새 단위 테스트는 수정 전 "expected 0.002 to be undefined"로 실패,
수정 뒤 2 passed. supply-chain·deletable-history-documents·
test-evidence-source-rules와 함께 37 passed.
- tsc(node·test), eslint, check-test-evidence --source-only PASS,
verify-documentation-readiness PASS_SCOPED.
Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-03
시각 골든은 작성자 PC가 고른 글꼴 4종(Noto Sans, Noto Sans CJK KR
Regular·Black, Liberation Mono)으로 찍혀 있는데, 설정은 글꼴을 고정하지
않는다. 같은 dist에서 FONTCONFIG_FILE만 Playwright가 맨 Ubuntu에 까는
글꼴 구성으로 바꿔도 5장이 모두 실패한다. 실패는 화면 전체가 밀린 pixel
diff라서 원인이 글꼴이라는 것을 알기 어렵다. CI 러너도 같은 처지다.
고른 방법 (리뷰 4.1절 c′, 사용자 결정):
- tests/visual/fonts.conf가 Debian/Ubuntu 경로의 세 디렉터리
(truetype/noto, opentype/noto, truetype/liberation)만 보이게 한다.
playwright.visual.config.ts가 use.launchOptions.env로 그 파일을
FONTCONFIG_FILE에 넣는다. 바깥 FONTCONFIG_FILE은 덮어쓴다. CI
workflow는 바꾸지 않았다.
- 같은 파일에서 래스터 설정(antialias, hintslight, rgb, lcddefault,
autohint 끔)을 호스트 규칙 뒤에 고정한다. 글꼴 이름이 같아도 hint와
sub-pixel 기본값이 다른 호스트에서는 5장이 모두 실패했다(검증 참고).
- visual-fonts setup 프로젝트(tests/visual/fonts.setup.ts)를
chromium-visual의 의존으로 둔다. 실제 앱 페이지에 탐침 요소를 넣고
CDP CSS.getPlatformFontsForNode로 실제로 그려진 글꼴을 비교한다.
다르면 설치할 패키지 이름과 함께 실패하고, 스크린샷 테스트는 돌지
않는다. 글꼴이 하나도 없으면 렌더러가 죽으므로 그 경우도 같은 안내로
감싼다. test:visual:update도 같은 검사를 먼저 거친다.
버린 대안:
- fc-match 사전 검사: fontconfig CLI가 러너에 있다는 보장이 없고,
Chromium이 실제로 고르는 글꼴과 다를 수 있다. 앱 페이지의 code는
Liberation Mono인데, lang 없는 빈 페이지에서는 Noto Mono가 잡혔다.
그래서 탐침도 앱 페이지 안에 넣는다.
- document.fonts.check: 시스템 글꼴은 없어도 true를 돌려준다.
- /etc/fonts/conf.d를 빼고 별칭 규칙을 직접 쓰기: system-ui와
Courier New(Chromium 기본 monospace) 해석을 다시 만들어야 한다.
리뷰 실험 D(호스트 규칙 포함, 5/5)에서 벗어난다.
- 컨테이너 이미지, 글꼴 파일 커밋, 임계값 완화: 리뷰 4.1절에서 기각.
위험·한계:
- 바이트가 아니라 패키지 이름을 고정한다. 배포판이 글꼴 버전을 바꾸면
이름 검사는 통과하고 pixel diff로 실패할 수 있다.
- generic family 별칭(sans-serif → Noto Sans, Courier New → Liberation
Mono)은 호스트의 /etc/fonts/conf.d를 따른다. 별칭이 다른 호스트
(예: Noto Sans를 우선하지 않는 fontconfig 2.14 미만)에서는
visual-fonts가 실패한다. 조용히 다른 글꼴로 바뀌지는 않는다.
- 사용자 fontconfig(50-user.conf)가 디렉터리를 더하면 그 글꼴도
보인다. 탐침 4종이 바뀌면 검사가 잡는다.
- Linux 전용이다. macOS와 Windows의 Chromium은 fontconfig를 읽지 않는다.
- 실제 Gitea 러너에서는 돌려 보지 못했다(U-1). CI에 apt 설치 단계를
넣지 않았고, 필요한 패키지는 테스트 전략 문서 13.4절에 적었다.
- 골든은 다시 찍지 않았다.
검증 (같은 dist, flock, `npx playwright test --config
playwright.visual.config.ts`. pnpm을 부르지 않으려고 webServer만
vite preview로 바꾼 로컬 사본으로 실행):
- 수정 전, 바깥 FONTCONFIG_FILE=A(Playwright Ubuntu 글꼴 + DejaVu):
5 failed, toHaveScreenshot diff(46,356 px, 4%)
- 검사만 넣고 같은 A: 1 failed, 5 did not run. 설치 안내와 함께
latin=DejaVu Sans, korean=WenQuanYi Zen Hei
- RED, fonts.conf가 빈 디렉터리만 볼 때: 1 failed, 5 did not run.
같은 설치 안내 + "The font probe page did not render"
- GREEN, 호스트 환경: 6 passed. 바깥 A: 6 passed(기존 골든 5/5)
- 러너 근사(호스트 conf.d에서 language-selector, ubuntulegacy,
sub-pixel-rgb 제외): 6 passed
- 다른 래스터 기본값(hinting-full, sub-pixel-none): 고정 블록 없이
5 failed(setup만 통과, diff 2%), 고정 블록 포함 6 passed
- tsc(app·node·test), eslint, check-test-evidence --source-only PASS,
verify-documentation-readiness PASS_SCOPED, vitest supply-chain과
tests/architecture 53 passed
Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-02, 4.1절
Only the capabilities config set forbidOnly, so a committed test.only ran one
e2e, visual or storybook test and passed. The skip check accepted any
quarantine marker without comparing its expiry date to today.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>