Files
clean-architecture-frontend…/tests/visual/platform.visual.spec.ts
DongHyeonka 0a6ff6e5ed test(visual): 시각 골든에서 설치된 기능의 링크와 목록을 뺀다
문제
merge 게이트 test:visual(FE-GATE-008)의 셸 전체 페이지, 좁은 서랍,
플랫폼 구성 스크린샷이 설치된 기능의 내비게이션 링크와 목록을 같이
찍었다. create:feature로 기능 하나를 더하면 세 장이 실패했고(185 px,
3,106 px, 이미지 높이 3814 -> 3964), 통과시키려면 템플릿 소유 PNG를
고정 글꼴 환경에서 다시 찍어야 했다.

고른 방법 (결정 D3 (a), 영역 밖 요소만 찍기)
- 스크린샷 직전에 style 태그로 설치된 기능이 정하는 부분을
  display: none으로 뺀다. mask는 목록이 길어지면 높이가 바뀌어 같은
  실패를 낸다.
  - 셸·홈: 기능 라우트로 가는 링크 전부(내비게이션은 li째). 목록은
    ROUTE_REGISTRY·ROUTE_FEATURE_OWNER에서 만들어서 기능을 더해도 spec을
    고치지 않는다. 09-04 뒤로 UI·상태·인증 예제 링크도 기능 링크라 같이
    빠진다.
  - 플랫폼 구성: 설치 요약, 라우트 표, 계약·오퍼레이션 표, 제품 기능
    절. 릴리스 신원의 계약 집합 다이제스트 값은 visibility: hidden(생성
    기능의 계약 패키지가 바꾼다). 서버 상태 표(DataTable)·실행 상한·능력
    카드·나머지 릴리스 신원은 남긴다.
- 15-01 뒤로 계약 표가 나중에 채워지므로 로딩이 끝난 뒤 찍는다.
- 골든 3장을 고정 글꼴 환경(tests/visual/fonts.conf, visual-fonts 통과)
  에서 한 번 다시 찍었다. 갤러리·상태 2장은 바뀌지 않았다.
- 버린 대안: 고정 fixture 제품으로 따로 빌드(빌드 경로가 하나 늘어남),
  골든을 제품 소유로 선언(동기화마다 PNG 충돌).

위험·한계
- 링크 목록·기능 표의 모양 회귀는 시각 검사 밖이 된다. 개수와 순서는
  component·e2e 테스트가 본다.
- 셸 골든에는 플랫폼 링크("홈", "플랫폼 구성")와 홈 화면의 "플랫폼 구성
  보기" 버튼만 남는다.

검증
heavy lock 안, 같은 worktree(.tmp/r1103/visual.sh), 부하 5.7~8.6:
- test:visual:update로 3장만 바뀜(셸 넓은 화면·좁은 서랍·플랫폼 구성).
- 깨끗한 상태 6/6 통과.
- create:feature probe-feature(새 context) 뒤 6/6 통과.
- probe-two·three·four(같은 context)를 더해 기능 4개에서 6/6 통과.
  생성 파일은 지웠다.
- 변이: shell.css .app-navigation__link padding 0.75rem -> 0.5rem.
  넓은 셸 847 px, 좁은 서랍 4,207 px 차이로 2건 실패. 되돌렸다.
- 다이제스트를 가리기 전 첫 시도에서는 기능 1개·4개 모두 플랫폼 구성이
  710·636 px로 실패했다(원인 확인 뒤 위 규칙 추가).
- eslint, check:types:test, check:test-evidence:source 통과(mask 전체
  가림 규칙에 걸리지 않음).

Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-01
2026-11-04 22:59:03 +09:00

120 lines
4.6 KiB
TypeScript

import {
expect,
test,
type Page,
} from "../support/browser/strict-browser-test.ts";
import {
ROUTE_FEATURE_OWNER,
ROUTE_REGISTRY,
} from "../../src/features/installed-feature-contracts.ts";
// 11-02. `main` is drawn before the route chunk arrives; a screenshot taken
// then pins the loading surface instead of the page.
async function expectRouteHeading(page: Page, title: string) {
await expect(page.getByRole("heading", { level: 1 })).toHaveText(title);
}
/** `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 });
}
/**
* 1103/12-01. These goldens are the template's own drawing: the shell, the
* home page and the platform overview. Those screens also draw whatever
* features are installed, so one `create:feature` failed this merge gate and
* only re-capturing template-owned PNGs made it pass. The screenshots leave
* the installed features' parts out (`display: none`, so a longer list does
* not move the rest): every link to a feature route, with its list item, and
* the overview sections that count or list the installed features. Their
* number and order are the component tests' subject; the shell's own CSS
* still fails here.
*/
const FEATURE_ROUTE_PATHS = Object.values(ROUTE_REGISTRY)
.filter((route) => ROUTE_FEATURE_OWNER[route.routeId] !== undefined)
.map((route) => route.path);
const WITHOUT_FEATURE_LINKS =
FEATURE_ROUTE_PATHS.length === 0
? ""
: `${FEATURE_ROUTE_PATHS.flatMap((path) => [
`li:has(> a[href="${path}"])`,
`a[href="${path}"]`,
]).join(",\n")} { display: none !important; }`;
const WITHOUT_INSTALLED_FEATURE_SECTIONS = `${[
"platform-summary-title",
"platform-routes-title",
"platform-contracts-title",
"platform-features-title",
]
.map((id) => `section[aria-labelledby="${id}"]`)
.join(",\n")} { display: none !important; }
section[aria-labelledby="platform-release-title"] .platform-metric:nth-child(4) dd {
/* The contract-set digest: a feature's contract package changes it. */
visibility: hidden !important;
}`;
test("wide application shell visual contract", async ({ page }) => {
await page.setViewportSize({ width: 1440, height: 900 });
await page.goto("/");
await expectRouteHeading(page, "Clean Architecture Frontend");
await hide(page, WITHOUT_FEATURE_LINKS);
await expect(page).toHaveScreenshot("app-shell-wide-light.png", {
fullPage: true,
});
});
test("compact drawer and pseudo-locale visual contract", async ({ page }) => {
await page.setViewportSize({ width: 390, height: 844 });
await page.goto("/");
await expectRouteHeading(page, "Clean Architecture Frontend");
await page.locator("#locale-preference").selectOption("en-XA");
await page.locator(".app-shell__menu-button").click();
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", {
fullPage: true,
});
});
test("design-system gallery dark visual contract", async ({ page }) => {
await page.setViewportSize({ width: 1280, height: 900 });
await page.goto("/examples/ui");
await expectRouteHeading(page, "UI 구성요소");
await page.locator("#theme-preference").selectOption("dark");
await expect(page.getByRole("main")).toHaveScreenshot(
"design-system-gallery-dark.png",
);
});
test("loading empty error and access surfaces visual contract", async ({
page,
}) => {
await page.setViewportSize({ width: 1280, height: 1100 });
await page.goto("/examples/states");
await expectRouteHeading(page, "화면 상태");
await expect(page.getByRole("main")).toHaveScreenshot(
"state-surfaces-light.png",
);
});
test("platform composition overview visual contract", async ({ page }) => {
await page.setViewportSize({ width: 1280, height: 1100 });
await page.goto("/examples/platform");
await expectRouteHeading(page, "플랫폼 구성");
await expect(
page.locator("section[aria-labelledby='platform-capabilities-title']"),
).toBeVisible();
// 1103/15-01. The contract tables fill in after the title; wait for them so
// the hidden sections are drawn in their final state either way.
await expect(page.locator("main [aria-busy='true']")).toHaveCount(0);
await expect(
page
.locator("section[aria-labelledby='platform-release-title'] dt")
.filter({ hasText: "계약 집합 다이제스트" }),
).toBeVisible();
await hide(page, WITHOUT_INSTALLED_FEATURE_SECTIONS);
await expect(page.getByRole("main")).toHaveScreenshot(
"platform-overview-light.png",
);
});