Files
clean-architecture-frontend…/tests/unit/visual-regression-tolerance.test.ts
T
DongHyeonka 5ce3db98ef test(visual): 시각 회귀 허용치를 절대 픽셀 50으로 바꾼다 (11-03)
문제: 시각 회귀 허용치가 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
2026-11-01 23:18:45 +09:00

27 lines
1.0 KiB
TypeScript

import { describe, expect, it } from "vitest";
import visualConfig from "../../playwright.visual.config.ts";
// 11-03. Measured on this template's goldens: undoing the UI-04 fix changed
// 1,146 px of the wide shell, and the compact golden drifted 175 px from the
// code without failing. A 0.2% share of the image allowed 2,592 px on the
// wide shell, 985 px on the compact shell and 7,781 px on the platform
// overview, so the allowance grew with the page instead of covering only
// rasterization noise (VD-08 item 8).
const SMALLEST_MEASURED_REGRESSION_PX = 175;
describe("visual regression tolerance", () => {
const screenshot = visualConfig.expect?.toHaveScreenshot;
it("does not scale with the image size", () => {
expect(screenshot?.maxDiffPixelRatio).toBeUndefined();
});
it("stays below the smallest real change measured", () => {
expect(screenshot?.maxDiffPixels).toBeGreaterThanOrEqual(0);
expect(screenshot?.maxDiffPixels).toBeLessThan(
SMALLEST_MEASURED_REGRESSION_PX,
);
});
});