test(visual): 시각 테스트 글꼴을 fonts.conf로 고정하고 먼저 검사한다 (11-02)

시각 골든은 작성자 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절
This commit is contained in:
DongHyeonka
2026-11-01 21:00:06 +09:00
parent a6560be93e
commit 08b5ccc86e
5 changed files with 125 additions and 3 deletions
+1 -1
View File
@@ -635,7 +635,7 @@ Form과 overlay는 다음 story를 추가한다.
필수 안정화:
- 동일한 Linux image, browser version, font
- 동일한 browser version과 글꼴(`tests/visual/fonts.conf`, Linux 전용)
- animation과 caret 비활성화
- 시간·랜덤·network 응답 고정
- 동적 ID와 민감 데이터 mask
@@ -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
+17 -1
View File
@@ -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"] },
],
});
+37
View File
@@ -0,0 +1,37 @@
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<!--
11-02. Font set for the visual tests (playwright.visual.config.ts passes it
to Chromium as FONTCONFIG_FILE). The goldens were captured with Noto Sans,
Noto Sans CJK KR (Regular and Black) and Liberation Mono, so Chromium sees
only the directories that hold them, at their Debian/Ubuntu paths:
sudo apt-get install -y fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation
A missing directory is skipped silently here; tests/visual/fonts.setup.ts
fails the run with that install line instead. Linux only: Chromium on macOS
and Windows does not read fontconfig.
-->
<fontconfig>
<dir>/usr/share/fonts/truetype/noto</dir>
<dir>/usr/share/fonts/opentype/noto</dir>
<dir>/usr/share/fonts/truetype/liberation</dir>
<cachedir>/var/cache/fontconfig</cachedir>
<cachedir prefix="xdg">fontconfig</cachedir>
<!-- The host's generic-family aliases: sans-serif to Noto Sans, Courier
New (Chromium's default monospace) to Liberation Mono. -->
<include ignore_missing="yes">/etc/fonts/conf.d</include>
<!-- Rasterization the goldens were captured with. Placed after the host
rules so a runner whose fontconfig defaults differ (sub-pixel order,
hint style) still draws the same pixels. -->
<match target="font">
<edit name="antialias" mode="assign"><bool>true</bool></edit>
<edit name="hinting" mode="assign"><bool>true</bool></edit>
<edit name="hintstyle" mode="assign"><const>hintslight</const></edit>
<edit name="autohint" mode="assign"><bool>false</bool></edit>
<edit name="rgba" mode="assign"><const>rgb</const></edit>
<edit name="lcdfilter" mode="assign"><const>lcddefault</const></edit>
</match>
</fontconfig>
+66
View File
@@ -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 = `
<p data-font-probe="latin">Clean Architecture Frontend</p>
<p data-font-probe="korean">플랫폼구성화면상태</p>
<p data-font-probe="korean-800" style="font-weight: 800">플랫폼구성화면상태</p>
<code data-font-probe="code">const value = 42;</code>`;
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<string, string> = {};
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<string, string>;
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);
});