From c7e80f2f8a5b38168cbcf84d950ca35218e0d776 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 10:46:20 +0900 Subject: [PATCH] =?UTF-8?q?test(visual):=20=EA=B0=A4=EB=9F=AC=EB=A6=AC?= =?UTF-8?q?=EB=A5=BC=20Storybook=20story=EB=A1=9C=20=EC=98=AE=EA=B8=B0?= =?UTF-8?q?=EA=B3=A0=20=EA=B3=A8=EB=93=A0=20=EB=8C=80=EC=83=81=EC=9D=84=20?= =?UTF-8?q?=EB=B0=94=EA=BE=BC=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 예제 화면 /examples/ui·/examples/states가 visual 골든 2장과 갤러리 브라우저 시험의 대상이다. 2026-11-07 소유자 결정으로 예제 화면을 지우므로 그 역할을 먼저 옮긴다(design-docs repo-structure/ 04-frontend-layout.md 9.2절 2단계 (1)). 두 갤러리 화면을 그대로 src/presentation/design-system/ galleries.stories.tsx로 옮겼다. 화면 단위 story(parameters.page)는 preview가 여백을 더하지 않아 앱 안과 같은 폭으로 그려진다. visual 설정은 Storybook 정적 빌드를 두 번째 web server로 띄우고 (TEST_VISUAL_WORKSHOP_PORT, 빌드 명령은 workshop 설정과 같은 scripts/lib/storybook-static.ts), 골든 2장은 그 story를 찍는다. 어두운 골든은 테마 선택기가 없어 시스템 dark(colorScheme)로 그린다. e2e의 갤러리 상호작용(텍스트 필드, 모달 포커스, 메뉴·탭·토스트, 열린 대화 상자 axe, 320px 리플로)은 tests/storybook/galleries.spec.ts로 옮겼다. 위험: 골든의 픽셀 색 허용치(threshold 0.2)는 그대로다. 미세한 토큰 변화는 옛 골든처럼 새 골든도 잡지 못한다. 검증(desktop): test:storybook 6 passed, test:visual 7 passed, playwright-run-isolation 단위 시험 통과. 변이 확인: --color-action을 파랑→빨강으로 바꾸면 새 골든이 어두운 쪽 42,313px, 밝은 쪽 22,359px 차이로 실패했다. 옛 골든(main f33e4778)도 40,238px, 22,511px로 실패했다. 미세 변이(어두운 --color-danger red-500→600, 밝은 --color-danger-surface 색상각 25→145)는 옛·새 골든 모두 통과했다. 변이는 되돌렸다. --- .storybook/preview.tsx | 17 +- docs/styling/design-system-platform.md | 14 +- docs/styling/design-tokens.md | 3 +- .../frontend-platform-testing-strategy.md | 15 +- playwright.storybook.config.ts | 19 +- playwright.visual.config.ts | 39 +- scripts/lib/run-isolation.ts | 18 + scripts/lib/storybook-static.ts | 27 ++ .../design-system/galleries.stories.tsx | 442 ++++++++++++++++++ tests/e2e/accessibility.spec.ts | 16 - tests/e2e/design-system-interactions.spec.ts | 29 -- tests/e2e/ui-gallery.spec.ts | 34 -- tests/helpers/playwright-run-isolation.ts | 19 +- tests/storybook/galleries.spec.ts | 113 +++++ tests/unit/local-build-environment.test.ts | 3 +- tests/unit/playwright-run-isolation.test.ts | 39 ++ ...tem-gallery-dark-chromium-visual-linux.png | Bin 194419 -> 193564 bytes ...e-surfaces-light-chromium-visual-linux.png | Bin 121609 -> 126022 bytes tests/visual/platform.visual.spec.ts | 40 +- 19 files changed, 749 insertions(+), 138 deletions(-) create mode 100644 scripts/lib/storybook-static.ts create mode 100644 src/presentation/design-system/galleries.stories.tsx delete mode 100644 tests/e2e/design-system-interactions.spec.ts delete mode 100644 tests/e2e/ui-gallery.spec.ts create mode 100644 tests/storybook/galleries.spec.ts diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx index 2d0e8681..b920d0fc 100644 --- a/.storybook/preview.tsx +++ b/.storybook/preview.tsx @@ -86,7 +86,10 @@ const queryClient = createQueryClient(); const preview: Preview = { decorators: [ - (Story) => ( + // A page story (`parameters.page`, the galleries) draws its own + // `.ui-page`, as a route page does inside the shell's `main`; a component + // story gets a padded page around it. + (Story, context) => ( @@ -94,9 +97,15 @@ const preview: Preview = {
-
- -
+ {context.parameters["page"] === true ? ( +
+ +
+ ) : ( +
+ +
+ )} diff --git a/docs/styling/design-system-platform.md b/docs/styling/design-system-platform.md index 0618086b..d6eedf68 100644 --- a/docs/styling/design-system-platform.md +++ b/docs/styling/design-system-platform.md @@ -38,8 +38,8 @@ - local form facade, field/error summary, dirty navigation dialog - `src/presentation/templates` - Standard, Collection, Detail, Form, Status page template -- `/examples/ui`, `/examples/states` - - 실행 가능한 primitive와 상태 예제 +- `src/presentation/design-system/galleries.stories.tsx` + - 실행 가능한 primitive와 상태 예제(Storybook 갤러리 story) - component/E2E/axe 테스트 - 필드 설명과 오류 연결 - native dialog 닫기와 trigger focus 복원 @@ -623,8 +623,8 @@ RP-10의 Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어 ## 10. Storybook과 시각 검증 -현재 `/examples/ui`는 실행 중인 앱 셸과 primitive 통합을 확인하는 데 유지한다. -그러나 runtime gallery는 isolated component workshop을 대체하지 않는다. +디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story다. 앱 셸과 primitive의 +통합은 `/`와 `/examples/platform`을 여는 e2e가 확인한다. [Storybook 공식 UI 테스트 문서](https://storybook.js.org/docs/writing-tests)는 story를 기반으로 interaction, accessibility, visual test를 구성하는 방법을 @@ -796,8 +796,8 @@ long-content ### Step 9. 통합 예제를 추가한다 -- `/examples/ui`에는 primitive를 추가한다. -- `/examples/states`에는 새로운 공통 상태를 추가한다. +- 갤러리 story(`galleries.stories.tsx`)의 `DesignSystem`에는 primitive를 추가한다. +- 같은 파일의 `ScreenStates`에는 새로운 공통 상태를 추가한다. - pattern/template은 domain-neutral fixture로 실제 조합을 보여 준다. - production profile에서 예제 route를 제외할 수 있는 계약을 유지한다. @@ -919,7 +919,7 @@ component contract에 기록한다. 예를 들어 `Separator`에는 pending/erro 9. locale provider, pseudo-locale, RTL 검증을 추가한다. 10. Storybook, story a11y, interaction test를 추가한다. 11. pinned browser 환경의 visual regression gate를 추가한다. -12. `/examples/ui`와 `/examples/states`를 통합 smoke gallery로 유지한다. +12. 디자인 시스템·화면 상태 갤러리를 Storybook story로 유지하고 visual 골든의 대상으로 쓴다. 이 순서는 라이브러리 수를 늘리는 것이 목표가 아니다. 각 단계가 제품 개발자가 중복 구현할 문제를 하나씩 제거하고, 외부 공급자를 교체할 수 있는 로컬 계약과 diff --git a/docs/styling/design-tokens.md b/docs/styling/design-tokens.md index 1a2d94c5..bd31f947 100644 --- a/docs/styling/design-tokens.md +++ b/docs/styling/design-tokens.md @@ -7,7 +7,8 @@ the dark theme, and `component.css` maps roles to per-component values. `src/presentation/styles/theme.css` only imports the three files and the style files under `src/presentation/styles/theme/`. Components consume semantic color, spacing, typography, status, and radius tokens through static classes. -`/examples/ui` is the executable token and primitive gallery. +The executable token and primitive gallery is the workshop story +`src/presentation/design-system/galleries.stories.tsx` (`corepack pnpm storybook`). ## Rules a rebrand must keep diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/testing/frontend-platform-testing-strategy.md index e031a932..5cdd8456 100644 --- a/docs/testing/frontend-platform-testing-strategy.md +++ b/docs/testing/frontend-platform-testing-strategy.md @@ -808,8 +808,10 @@ production runtime config에 `MOCK_MODE`, `SCENARIO`, fake token 같은 key를 ## 12. Storybook 테스트 Storybook은 component를 격리해 state를 열거하고 실제 브라우저 interaction과 -접근성을 검사하는 개발·CI surface다. `/examples/ui`는 앱 통합 smoke로 유지하되 -Storybook을 대신하지 않는다. +접근성을 검사하는 개발·CI surface다. 디자인 시스템 갤러리와 화면 상태 갤러리도 +story다(`src/presentation/design-system/galleries.stories.tsx`). 갤러리의 브라우저 +상호작용 검사는 `tests/storybook/galleries.spec.ts`가, 앱 셸 안의 통합 확인은 +`/`와 `/examples/platform`을 여는 e2e가 맡는다. ### 12.1 Global decorator @@ -945,9 +947,10 @@ Playwright `toHaveScreenshot()`을 사용한다. - `app-shell-wide-light`: `/`, 1440×900, light, 전체 페이지 — wide app shell - `app-shell-compact-pseudo-drawer`: `/`, 390×844, en-XA, 메뉴 서랍 열림 — compact app shell, pseudo-locale, 열린 drawer -- `design-system-gallery-dark`: `/examples/ui`, dark — design-system 갤러리 -- `state-surfaces-light`: `/examples/states` — loading, background refresh, - empty, error, 401, 403, 404 +- `design-system-gallery-dark`: Storybook 정적 빌드의 갤러리 story + `platform-galleries--design-system`, 1280×900, 시스템 dark — design-system 갤러리 +- `state-surfaces-light`: Storybook 정적 빌드의 `platform-galleries--screen-states`, + 1280×1100 — loading, background refresh, empty, error, 401, 403, 404 - `platform-overview-light`: `/examples/platform` — 플랫폼 구성 개요 `check-test-evidence`는 기준선 PNG가 4장 이상인지만 본다. 위 목록의 각 @@ -1034,7 +1037,7 @@ TEST_RUN_ID=a playwright test |---|---|---| | `TEST_RUN_ID` | 다섯 Playwright 설정, `tests/e2e/preload-use.spec.ts` | `dist`, `artifacts/tests/<이름>/` | | `RUN_OUTPUT_ROOT` | 빌드 단계 전부(`scripts/build-frontend.ts`가 부르는 것), `vite.config.ts`. 설정이 web server에만 넘긴다. 빌드 뒤 검사(`scripts/generate-supply-chain.ts`, `scripts/check-bundle.ts`)는 `.`이 아니면 멈춘다 | `.` | -| `TEST_E2E_PORT`, `TEST_VISUAL_PORT`, `TEST_CAPABILITIES_PORT`, `TEST_STORYBOOK_PORT`, `TEST_DEV_PORT` | 각 설정 | 빈 포트 | +| `TEST_E2E_PORT`, `TEST_VISUAL_PORT`, `TEST_VISUAL_WORKSHOP_PORT`, `TEST_CAPABILITIES_PORT`, `TEST_STORYBOOK_PORT`, `TEST_DEV_PORT` | 각 설정(`TEST_VISUAL_WORKSHOP_PORT`는 visual 설정의 두 번째 서버, 갤러리 골든이 여는 Storybook 정적 빌드) | 빈 포트 | - run ID는 글자·숫자·`.`·`_`·`-` 64자 이하이고 글자나 숫자로 시작한다. - 포트 변수를 주면 그 포트를 쓴다. 디버깅할 때 고정하는 용도다. diff --git a/playwright.storybook.config.ts b/playwright.storybook.config.ts index a36bfb5f..af4eebe9 100644 --- a/playwright.storybook.config.ts +++ b/playwright.storybook.config.ts @@ -4,22 +4,14 @@ import { reservePort, TEST_PORT_VARIABLES, testRunPath, - testRunRoot, } from "./scripts/lib/run-isolation.ts"; +import { storybookStaticServer } from "./scripts/lib/storybook-static.ts"; -// 1105/12-04. Under TEST_RUN_ID the workshop is built into the run's own -// folder (.tmp/runs//artifacts/storybook/static) with build:storybook's -// two steps and another output folder, and the results and report are the -// run's own. Unset, the gate's build:storybook writes artifacts/storybook/static. -// The static server listens on a free port (TEST_STORYBOOK_PORT pins one). -const staticDirectory = testRunPath("artifacts/storybook/static"); +// 1105/12-04. Under TEST_RUN_ID the workshop build (storybookStaticServer), +// the results and the report are the run's own. The static server listens on +// a free port (TEST_STORYBOOK_PORT pins one). const port = await reservePort(TEST_PORT_VARIABLES.storybook); const origin = `http://127.0.0.1:${port}`; -const buildWorkshop = - testRunRoot() === "." - ? "corepack pnpm build:storybook" - : "node scripts/generate-product-feature-index.ts && " + - `corepack pnpm exec storybook build -o ${staticDirectory}`; export default defineConfig({ testDir: "./tests/storybook", @@ -45,8 +37,7 @@ export default defineConfig({ screenshot: "only-on-failure", }, webServer: { - command: - `${buildWorkshop} && node scripts/serve-static.ts ${staticDirectory} ${port}`, + command: storybookStaticServer(port).command, url: origin, reuseExistingServer: false, }, diff --git a/playwright.visual.config.ts b/playwright.visual.config.ts index 977fd864..9330b055 100644 --- a/playwright.visual.config.ts +++ b/playwright.visual.config.ts @@ -10,6 +10,7 @@ import { testRunPath, testRunRoot, } from "./scripts/lib/run-isolation.ts"; +import { storybookStaticServer } from "./scripts/lib/storybook-static.ts"; // 1105/12-04. Under TEST_RUN_ID the results, report and build are the run's // own (.tmp/runs//); the goldens in snapshotDir are shared and only read. @@ -18,6 +19,11 @@ import { const dist = testRunPath("dist"); const port = await reservePort(TEST_PORT_VARIABLES.visual); const origin = `http://127.0.0.1:${port}`; +// The design-system and screen-state galleries are workshop stories +// (src/presentation/design-system/galleries.stories.tsx); their goldens open +// the static workshop, which the second server serves +// (TEST_VISUAL_WORKSHOP_PORT pins its port). +const workshopPort = await reservePort(TEST_PORT_VARIABLES.visualWorkshop); export default defineConfig({ testDir: "./tests/visual", @@ -62,19 +68,26 @@ export default defineConfig({ }, }, }, - webServer: { - // The home page and the platform overview print the build and release - // identity. CI sets VITE_BUILD_ID, VITE_COMMIT_SHA and RELEASE_ID for the - // whole workflow, so its build drew other text than the goldens and every - // CI run failed here. The goldens are the template's shape, captured with - // the local identity. - // 1103/11-08: CI too, or the build is checked as a release build. - env: { ...LOCAL_BUILD_IDENTITY, [RUN_OUTPUT_ROOT_VARIABLE]: testRunRoot() }, - command: - `corepack pnpm build && corepack pnpm preview --host 127.0.0.1 --port ${port} --strictPort --outDir ${dist}`, - url: origin, - reuseExistingServer: false, - }, + webServer: [ + { + // The home page and the platform overview print the build and release + // identity. CI sets VITE_BUILD_ID, VITE_COMMIT_SHA and RELEASE_ID for + // the whole workflow, so its build drew other text than the goldens and + // every CI run failed here. The goldens are the template's shape, + // captured with the local identity. + // 1103/11-08: CI too, or the build is checked as a release build. + env: { ...LOCAL_BUILD_IDENTITY, [RUN_OUTPUT_ROOT_VARIABLE]: testRunRoot() }, + command: + `corepack pnpm build && corepack pnpm preview --host 127.0.0.1 --port ${port} --strictPort --outDir ${dist}`, + url: origin, + reuseExistingServer: false, + }, + { + command: storybookStaticServer(workshopPort).command, + url: `http://127.0.0.1:${workshopPort}`, + reuseExistingServer: false, + }, + ], projects: [ { name: "visual-fonts", testMatch: /fonts\.setup\.ts$/ }, { name: "chromium-visual", dependencies: ["visual-fonts"] }, diff --git a/scripts/lib/run-isolation.ts b/scripts/lib/run-isolation.ts index d51807bd..15cd263c 100644 --- a/scripts/lib/run-isolation.ts +++ b/scripts/lib/run-isolation.ts @@ -113,15 +113,33 @@ export function checkoutBuildReadFailure( /** * The port variable of each Playwright config's web server. Unset, the config * picks a free port; set, it uses that one (to pin a port while debugging). + * `visualWorkshop` is the visual config's second server, the static workshop + * the gallery goldens open. */ export const TEST_PORT_VARIABLES = Object.freeze({ e2e: "TEST_E2E_PORT", visual: "TEST_VISUAL_PORT", + visualWorkshop: "TEST_VISUAL_WORKSHOP_PORT", capabilities: "TEST_CAPABILITIES_PORT", storybook: "TEST_STORYBOOK_PORT", dev: "TEST_DEV_PORT", } as const); +/** + * The origin of a config's second server, for its specs. The runner reserved + * the port in `variable` (reservePort) and its workers inherit it. + */ +export function reservedOrigin( + variable: string, + environment: Readonly> = process.env, +): string { + const port = environment[variable]; + if (port === undefined || port === "") { + throw new Error(`${variable} is not set: run this spec through its Playwright config`); + } + return `http://127.0.0.1:${port}`; +} + /** * A port nothing listens on now: the one the kernel gives a socket bound to * port 0, which is closed again. Another process can still take it before the diff --git a/scripts/lib/storybook-static.ts b/scripts/lib/storybook-static.ts new file mode 100644 index 00000000..d916d957 --- /dev/null +++ b/scripts/lib/storybook-static.ts @@ -0,0 +1,27 @@ +import { testRunPath, testRunRoot } from "./run-isolation.ts"; + +/** + * The static workshop a Playwright config serves: the workshop tests + * (playwright.storybook.config.ts) and the gallery goldens + * (playwright.visual.config.ts) open the same build. + * + * 1105/12-04. Under TEST_RUN_ID the workshop is built into the run's own + * folder (.tmp/runs//artifacts/storybook/static) with build:storybook's + * two steps and another output folder. Unset, the gate's build:storybook + * writes artifacts/storybook/static. + */ +export function storybookStaticServer(port: number): Readonly<{ + directory: string; + command: string; +}> { + const directory = testRunPath("artifacts/storybook/static"); + const build = + testRunRoot() === "." + ? "corepack pnpm build:storybook" + : "node scripts/generate-product-feature-index.ts && " + + `corepack pnpm exec storybook build -o ${directory}`; + return Object.freeze({ + directory, + command: `${build} && node scripts/serve-static.ts ${directory} ${port}`, + }); +} diff --git a/src/presentation/design-system/galleries.stories.tsx b/src/presentation/design-system/galleries.stories.tsx new file mode 100644 index 00000000..7d9bdde1 --- /dev/null +++ b/src/presentation/design-system/galleries.stories.tsx @@ -0,0 +1,442 @@ +import type { Meta, StoryObj } from "@storybook/react-vite"; +import { useState, type FormEvent } from "react"; + +import { deriveAsyncState } from "../../application/view-models/async-state.ts"; +import { createFailure } from "../../contracts/errors.ts"; +import { + Alert, + AsyncSurface, + AuthRequiredSurface, + Badge, + Button, + Card, + Checkbox, + Dialog, + EmptySurface, + ForbiddenSurface, + LoadingSurface, + Menu, + NotFoundSurface, + PageHeader, + ProgressBar, + RadioGroup, + Select, + Switch, + Tabs, + TerminalErrorSurface, + TextArea, + TextField, + ToastProvider, + Tooltip, + useToast, +} from "./index.ts"; + +/** + * The design-system gallery and the screen-state gallery. They were the + * template's example screens `/examples/ui` and `/examples/states`; the + * visual goldens `design-system-gallery-dark` and `state-surfaces-light` + * (tests/visual/platform.visual.spec.ts) and the workshop tests + * (tests/storybook/galleries.spec.ts) open these stories in the static + * Storybook build. The primitives keep their own suites; these stories show + * them together, with the tokens they draw with. + */ +const meta = { + title: "Platform/Galleries", + parameters: { + layout: "fullscreen", + // Drawn like a route page: the preview's `main` adds no page of its own. + page: true, + }, +} satisfies Meta; + +export default meta; +type Story = StoryObj; + +export const DesignSystem: Story = { + render: () => , +}; + +export const ScreenStates: Story = { + render: () => , +}; + +const COLOR_TOKENS = Object.freeze([ + ["Surface", "--color-surface"], + ["Muted surface", "--color-surface-muted"], + ["Content", "--color-content"], + ["Muted content", "--color-content-muted"], + ["Action", "--color-action"], + ["Danger", "--color-danger"], + ["Focus", "--color-focus"], +]); + +function DesignSystemGallery() { + return ( + + + + ); +} + +function UiGalleryContent() { + const toast = useToast(); + const [projectName, setProjectName] = useState(""); + const [description, setDescription] = useState(""); + const [template, setTemplate] = useState("application"); + const [reviewed, setReviewed] = useState(false); + const [notifications, setNotifications] = useState(true); + const [density, setDensity] = useState("comfortable"); + const [fieldTouched, setFieldTouched] = useState(false); + const [dialogOpen, setDialogOpen] = useState(false); + const [notice, setNotice] = useState( + "구성요소를 조작하면 결과가 여기에 표시됩니다.", + ); + const [alertVisible, setAlertVisible] = useState(true); + const fieldError = + fieldTouched && projectName.trim().length === 0 + ? "프로젝트 이름을 입력해 주세요." + : undefined; + + function submitExample(event: FormEvent): void { + event.preventDefault(); + setFieldTouched(true); + if (projectName.trim().length === 0) { + setNotice("입력값을 확인해 주세요."); + return; + } + setNotice(`“${projectName.trim()}” 입력을 확인했습니다.`); + } + + return ( + // 08-07. Example copy is Korean in every locale (outside the catalog). +
+ + +
+
+

버튼과 입력

+

키보드, 비활성 상태, 오류 설명을 포함한 기본 상호작용입니다.

+
+
+ +
+ + + + +
+
+ +
+ setProjectName(event.currentTarget.value)} + /> + + +
+
+
+ +
+
+

폼과 선택 컨트롤

+

native semantics, 설명·오류 연결과 controlled 상태를 제공합니다.

+
+
+ +
+