From 91b3aaac467abc9365ff6fa8755764c833e42b6e Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 13 Nov 2026 18:37:29 +0900 Subject: [PATCH] =?UTF-8?q?test(visual):=20=EC=8B=9C=EA=B0=81=20=EA=B3=A8?= =?UTF-8?q?=EB=93=A0=EC=9D=98=20=EC=83=89=20=ED=97=88=EC=9A=A9=EC=B9=98?= =?UTF-8?q?=EB=A5=BC=200.05=EB=A1=9C=20=EC=A2=81=ED=9E=8C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 시각 골든은 `maxDiffPixels: 50`만 정하고 색 허용치(threshold)를 두지 않아 Playwright 기본값 0.2를 쓴다. 0.2는 pixelmatch YIQ 거리로 1408.6까지 같은 색으로 본다. 밝은 `--color-danger-surface`의 색상각 25 → 145(분홍 → 초록, 거리 154.5)와 어두운 `--color-danger` 한 단계(거리 1260.1)가 옛 골든과 새 골든을 모두 통과했다. 그래서 위험 표면이 초록빛으로 바뀌어도 골든이 통과한다. CHANGELOG 알려진 제한으로만 적혀 있었다. 고른 방법: 결정(2026-11-12, 총괄: 흔들림 없는 값을 재서 낮춘다)대로 0.05(거리 88.0)를 쓴다. 기준을 올리는 쪽이다. `playwright.visual.config.ts`는 지금 w2-fe-2가 브라우저 실행 설정을 고치는 중이라 이번에 건드리지 않고, 시각 spec이 모든 screenshot에 `GOLDEN`(threshold 0.05)을 넘긴다. 새 screenshot이 빠뜨리지 않도록 `tests/unit/visual-golden-threshold.test.ts`가 대조한다. 버린 대안: 0.1(거리 352.2라 첫 변이가 다시 통과한다). 위험·한계: 글꼴·래스터 설정을 고정한 깨끗한 빌드는 0 px 차이라는 기존 주장에 기댄다. desktop에서 변이 없이 세 번, 변이로 한 번 돌려 PR 본문에 적는다. 설정 기본값은 0.2 그대로라 다른 Playwright 설정의 screenshot은 이 값을 받지 않는다(지금 다른 곳에는 screenshot이 없다). 검증: 실험 X-02(변이 `--color-danger-surface` 색상각 145에서 0.2는 통과, 0.05는 `state-surfaces-light` 실패, 변이 없이 세 번 통과)는 desktop에서 돌려 PR 본문에 적는다. Refs: 1112/04-11 --- .claude/skills/fe-design-system/SKILL.md | 2 +- tests/unit/visual-golden-threshold.test.ts | 28 ++++++++++++++++++++++ tests/visual/platform.visual.spec.ts | 15 ++++++++++++ 3 files changed, 44 insertions(+), 1 deletion(-) create mode 100644 tests/unit/visual-golden-threshold.test.ts diff --git a/.claude/skills/fe-design-system/SKILL.md b/.claude/skills/fe-design-system/SKILL.md index a9ee5c73..d6c84dfe 100644 --- a/.claude/skills/fe-design-system/SKILL.md +++ b/.claude/skills/fe-design-system/SKILL.md @@ -39,7 +39,7 @@ paths: 7. 컴포넌트 API를 열어 둔다: 날 색 prop, vendor 타입 노출, 무제한 `as`, 범위 없는 `className`. — `docs/design/2026-07-26-design-system-platform-design.md` 11절 4단계, 13절 8. primitive가 API·query·인증·저장소를 직접 부른다. pattern·template도 use case를 고르지 않고 상태와 callback을 props로 받는다. — 같은 문서 2절 9. 세 번째 사용 사례가 나오기 전에 제품 전용 조합을 primitive로 올린다. — 같은 문서 2절 -10. 시각 골든을 그냥 다시 찍는다. 골든은 코드 리뷰 대상이다. Chromium 하나, Linux, 글꼴 고정(`tests/visual/fonts.conf`)이고 허용 차이는 절대 픽셀 수다. 비율 허용이 1천 px 넘는 회귀를 통과시킨 일이 있어 절대 수로 바꿨다. 실패 screenshot은 시각 회귀가 아니다. — `playwright.visual.config.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 10.3절 +10. 시각 골든을 그냥 다시 찍는다. 골든은 코드 리뷰 대상이다. Chromium 하나, Linux, 글꼴 고정(`tests/visual/fonts.conf`)이고 허용 차이는 절대 픽셀 수(`maxDiffPixels`)이고, 한 픽셀의 색 허용치는 0.05다(시각 spec의 `GOLDEN`). 비율 허용이 1천 px 넘는 회귀를, 기본 색 허용치 0.2가 위험 표면의 색상 변경을 통과시킨 일이 있다. 실패 screenshot은 시각 회귀가 아니다. — `playwright.visual.config.ts`, `docs/design/2026-07-26-design-system-platform-design.md` 10.3절 11. 골든이 그리는 범위를 넘겨 짐작한다. 골든은 셸·홈·플랫폼 구성·갤러리 story만 찍고 기능 영역은 가린다. 새 primitive·상태는 갤러리 story에 넣어야 골든에 든다. — `tests/visual/platform.visual.spec.ts`, `PRODUCT.md` 「Capabilities and Constraints」 12. 디자인 시스템이 side effect를 갖거나 무거운 것을 끌어와 초기 청크에 실린다. — `docs/work/reference/defect-patterns.md` B3, `tests/unit/design-system-initial-chunk.test.ts` diff --git a/tests/unit/visual-golden-threshold.test.ts b/tests/unit/visual-golden-threshold.test.ts new file mode 100644 index 00000000..feb10f8c --- /dev/null +++ b/tests/unit/visual-golden-threshold.test.ts @@ -0,0 +1,28 @@ +import { readFile, readdir } from "node:fs/promises"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +/** + * 1112/04-11. Playwright's colour threshold 0.2 let a danger surface turn + * green and still match its golden. tests/visual/platform.visual.spec.ts + * passes `GOLDEN` (threshold 0.05) to each screenshot; a new screenshot that + * leaves it out falls back to 0.2. + */ +describe("visual golden colour threshold", () => { + it("passes GOLDEN to every screenshot of the visual specs", async () => { + const folder = "tests/visual"; + const specs = (await readdir(folder)).filter((file) => file.endsWith(".spec.ts")); + const calls = ( + await Promise.all(specs.map(async (file) => ({ file, source: await readFile(path.join(folder, file), "utf8") }))) + ).flatMap(({ file, source }) => + source + .split("toHaveScreenshot(") + .slice(1) + .map((rest) => ({ file, args: rest.slice(0, rest.indexOf(");")) })), + ); + + expect(calls.length).toBeGreaterThan(0); + expect(calls.filter(({ args }) => !/\bGOLDEN\b/u.test(args)).map(({ file, args }) => `${file}: ${args.trim()}`)).toEqual([]); + }); +}); diff --git a/tests/visual/platform.visual.spec.ts b/tests/visual/platform.visual.spec.ts index 182b19e3..c34b810b 100644 --- a/tests/visual/platform.visual.spec.ts +++ b/tests/visual/platform.visual.spec.ts @@ -30,6 +30,16 @@ async function openGalleryStory(page: Page, storyId: string, title: string) { await expect(page.getByRole("heading", { level: 1 })).toHaveText(title); } +/** + * 1112/04-11. How far one pixel's colour may move before it counts as + * changed (pixelmatch's YIQ distance; Playwright's default is 0.2). At 0.2 a + * danger surface turned green (hue 25 to 145) and the dark danger colour one + * palette step darker both passed the goldens. 0.05 fails the first; a clean + * build still differs by 0 px. Every screenshot below takes it; the pixel + * count `maxDiffPixels` stays in playwright.visual.config.ts. + */ +const GOLDEN = Object.freeze({ threshold: 0.05 }); + /** `toHaveScreenshot` takes a stylesheet only as a file; a tag does the same. */ async function hide(page: Page, css: string) { if (css !== "") await page.addStyleTag({ content: css }); @@ -75,6 +85,7 @@ test("wide application shell visual contract", async ({ page }) => { await expectRouteHeading(page, "Clean Architecture Frontend"); await hide(page, WITHOUT_FEATURE_LINKS); await expect(page).toHaveScreenshot("app-shell-wide-light.png", { + ...GOLDEN, fullPage: true, }); }); @@ -88,6 +99,7 @@ test("compact drawer and pseudo-locale visual contract", async ({ page }) => { await expect(page.locator(".ui-drawer")).toHaveJSProperty("open", true); await hide(page, WITHOUT_FEATURE_LINKS); await expect(page).toHaveScreenshot("app-shell-compact-pseudo-drawer.png", { + ...GOLDEN, fullPage: true, }); }); @@ -103,6 +115,7 @@ test.describe("in the dark color scheme", () => { await expect(page.locator("html")).toHaveAttribute("data-theme", "dark"); await expect(page.getByRole("main")).toHaveScreenshot( "design-system-gallery-dark.png", + GOLDEN, ); }); }); @@ -114,6 +127,7 @@ test("loading empty error and access surfaces visual contract", async ({ await openGalleryStory(page, "platform-galleries--screen-states", "화면 상태"); await expect(page.getByRole("main")).toHaveScreenshot( "state-surfaces-light.png", + GOLDEN, ); }); @@ -135,5 +149,6 @@ test("platform composition overview visual contract", async ({ page }) => { await hide(page, WITHOUT_INSTALLED_FEATURE_SECTIONS); await expect(page.getByRole("main")).toHaveScreenshot( "platform-overview-light.png", + GOLDEN, ); });