From 08b5ccc86edcfbea67cfecf28558bd2d22c442a2 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 20:49:50 +0900 Subject: [PATCH] =?UTF-8?q?test(visual):=20=EC=8B=9C=EA=B0=81=20=ED=85=8C?= =?UTF-8?q?=EC=8A=A4=ED=8A=B8=20=EA=B8=80=EA=BC=B4=EC=9D=84=20fonts.conf?= =?UTF-8?q?=EB=A1=9C=20=EA=B3=A0=EC=A0=95=ED=95=98=EA=B3=A0=20=EB=A8=BC?= =?UTF-8?q?=EC=A0=80=20=EA=B2=80=EC=82=AC=ED=95=9C=EB=8B=A4=20(11-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 시각 골든은 작성자 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절 --- docs/styling/design-system-platform.md | 2 +- .../frontend-platform-testing-strategy.md | 5 +- playwright.visual.config.ts | 18 ++++- tests/visual/fonts.conf | 37 +++++++++++ tests/visual/fonts.setup.ts | 66 +++++++++++++++++++ 5 files changed, 125 insertions(+), 3 deletions(-) create mode 100644 tests/visual/fonts.conf create mode 100644 tests/visual/fonts.setup.ts diff --git a/docs/styling/design-system-platform.md b/docs/styling/design-system-platform.md index 0f25b452..3f091efa 100644 --- a/docs/styling/design-system-platform.md +++ b/docs/styling/design-system-platform.md @@ -635,7 +635,7 @@ Form과 overlay는 다음 story를 추가한다. 필수 안정화: -- 동일한 Linux image, browser version, font +- 동일한 browser version과 글꼴(`tests/visual/fonts.conf`, Linux 전용) - animation과 caret 비활성화 - 시간·랜덤·network 응답 고정 - 동적 ID와 민감 데이터 mask diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/testing/frontend-platform-testing-strategy.md index 921906d1..0e53b1df 100644 --- a/docs/testing/frontend-platform-testing-strategy.md +++ b/docs/testing/frontend-platform-testing-strategy.md @@ -933,7 +933,10 @@ Playwright `toHaveScreenshot()`을 사용한다. 결정성 규칙: -- OS, browser, font, device scale을 CI image로 고정 +- browser 버전과 viewport·scale은 `playwright.visual.config.ts`로, 글꼴은 + `tests/visual/fonts.conf`로 고정(Linux 전용). 러너에는 + `fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation` + 패키지가 필요하고, 없으면 `visual-fonts` 검사가 설치 명령을 보여 주며 실패한다 - animation/caret 비활성화 - clock/random/network fixture 고정 - 개인정보와 동적 ID mask diff --git a/playwright.visual.config.ts b/playwright.visual.config.ts index 36528303..4fe52334 100644 --- a/playwright.visual.config.ts +++ b/playwright.visual.config.ts @@ -1,3 +1,5 @@ +import { fileURLToPath } from "node:url"; + import { defineConfig, devices } from "@playwright/test"; export default defineConfig({ @@ -27,6 +29,17 @@ export default defineConfig({ colorScheme: "light", locale: "en-US", trace: "retain-on-failure", + launchOptions: { + // 11-02. Chromium sees only the fonts the goldens were captured with, + // whatever the host or an outer FONTCONFIG_FILE says. The + // `visual-fonts` project checks them before any screenshot. + env: { + ...process.env, + FONTCONFIG_FILE: fileURLToPath( + new URL("./tests/visual/fonts.conf", import.meta.url), + ), + }, + }, }, webServer: { command: @@ -34,5 +47,8 @@ export default defineConfig({ url: "http://127.0.0.1:4174", reuseExistingServer: false, }, - projects: [{ name: "chromium-visual" }], + projects: [ + { name: "visual-fonts", testMatch: /fonts\.setup\.ts$/ }, + { name: "chromium-visual", dependencies: ["visual-fonts"] }, + ], }); diff --git a/tests/visual/fonts.conf b/tests/visual/fonts.conf new file mode 100644 index 00000000..c2f1f11d --- /dev/null +++ b/tests/visual/fonts.conf @@ -0,0 +1,37 @@ + + + + + /usr/share/fonts/truetype/noto + /usr/share/fonts/opentype/noto + /usr/share/fonts/truetype/liberation + /var/cache/fontconfig + fontconfig + + + /etc/fonts/conf.d + + + + true + true + hintslight + false + rgb + lcddefault + + diff --git a/tests/visual/fonts.setup.ts b/tests/visual/fonts.setup.ts new file mode 100644 index 00000000..70775bff --- /dev/null +++ b/tests/visual/fonts.setup.ts @@ -0,0 +1,66 @@ +import { + expect, + test, + type Page, +} from "../support/browser/strict-browser-test.ts"; + +// 11-02. The goldens were captured with these four faces. `fonts.conf` shows +// Chromium only the directories that hold them; this check runs before the +// screenshots so a missing or substituted font fails here with an install +// hint instead of as a whole-page pixel diff. Probes sit in the real page so +// they get its CSS (`--font-sans`) and `lang`, which decide the fallbacks. +const expectedFaces = { + latin: "Noto Sans", + korean: "Noto Sans CJK KR", + "korean-800": "Noto Sans CJK KR Black", + code: "Liberation Mono", +}; + +const installHint = [ + "Visual tests must draw with the fonts the goldens were captured with.", + "Debian/Ubuntu: sudo apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation", + "tests/visual/fonts.conf reads them from the Debian/Ubuntu font directories; other OSes have no Linux goldens.", +].join("\n"); + +async function drawnFaces(page: Page) { + await page.goto("/"); + await expect(page.getByRole("heading", { level: 1 })).toBeVisible(); + await page.evaluate(() => { + const probes = document.createElement("div"); + probes.innerHTML = ` +

Clean Architecture Frontend

+

플랫폼구성화면상태

+

플랫폼구성화면상태

+ const value = 42;`; + document.body.append(probes); + }); + + const cdp = await page.context().newCDPSession(page); + await cdp.send("DOM.enable"); + await cdp.send("CSS.enable"); + const { root } = await cdp.send("DOM.getDocument"); + const drawn: Record = {}; + for (const probe of Object.keys(expectedFaces)) { + const { nodeId } = await cdp.send("DOM.querySelector", { + nodeId: root.nodeId, + selector: `[data-font-probe="${probe}"]`, + }); + const { fonts } = await cdp.send("CSS.getPlatformFontsForNode", { nodeId }); + drawn[probe] = fonts.map((font) => font.familyName).join(" + "); + } + return drawn; +} + +test("visual fonts match the goldens", async ({ page }) => { + let drawn: Record; + try { + drawn = await drawnFaces(page); + } catch (error) { + // With no font at all the renderer crashes, so the page never draws. + throw new Error( + `${installHint}\nThe font probe page did not render: ${String(error)}`, + { cause: error }, + ); + } + expect(drawn, installHint).toEqual(expectedFaces); +});