test(component): UI 갤러리 화면의 검증·상태 전환을 component 테스트로 막는다 (1101/14.4)

문제: `src/presentation/examples/ui-gallery-page.tsx`는 component 커버리지가
0%였다. e2e(`tests/e2e/ui-gallery.spec.ts`, 폼 검증과 모달 포커스 2건)와
시각 회귀만 이 화면을 봤다. 화면이 primitive에 연결한 규칙(공백 이름 거절,
알림 줄 문구, 알림 숨김·다시 표시, 모달 확인만 알림 줄을 바꿈, 메뉴의 toast)은
게이트 안 단위 실행에서 아무도 확인하지 않았다.

고른 방법: `tests/component/starter-ui-gallery-page.test.tsx` 9건. 화면을
LocaleProvider만으로 그리고 사용자 동작(user-event)으로 확인한다. 섹션 5개와
토큰 7개 렌더, 버튼 3개의 알림 문구, 빈 이름·공백 이름 거절과 trim한 이름
수락, controlled 입력 6종, 알림 숨김·복원, 모달의 취소·닫기·확인, 메뉴 두
항목, 수동 탭 활성화, tooltip 설명. 파일 이름은 starter 화면 테스트 규칙
(`docs/architecture/starter-experience.md`, `starter-*.test.tsx`)을 따라
화면을 지울 때 같이 지운다.
버린 대안: 스냅샷 테스트. 문구가 바뀔 때마다 깨지고 동작은 확인하지 않는다.
앱 라우터(`/examples/ui`)로 띄우기. 라우팅은 router 테스트가 보고, 이
화면은 provider가 locale 하나만 필요하다.
화면 코드는 고치지 않았다.

위험·한계: primitive 자체 동작(포커스 트랩, Esc, 화살표 이동)은 각 primitive
테스트와 e2e가 보고 여기서는 다시 세지 않는다. jsdom이라 실제 레이아웃과
`showModal()`의 top layer는 확인하지 않는다(e2e 몫).

검증:
- 커버리지(`node scripts/run-vitest.ts run tests/component --coverage
  --coverage.include=src/presentation/examples/ui-gallery-page.tsx`):
  전 lines 0/38, functions 0/19, branches 0/8
  후 lines 38/38, functions 19/19, branches 8/8 (100%)
- 일부러 화면을 깨 봄(되돌림): fieldError의 trim 제거, 알림 onDismiss 무효화,
  메뉴 "상태 확인" onSelect 무효화 → 9건 중 3건 실패
- tests/component 전체 38파일 253건 통과
- `npx eslint` 새 파일, `npx tsc --project tsconfig.test.json --noEmit` 통과
This commit is contained in:
DongHyeonka
2026-11-03 20:09:49 +09:00
parent ec7435c3f7
commit 7ee1df56f1
@@ -0,0 +1,227 @@
// @vitest-environment jsdom
import { render, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it } from "vitest";
import UiGalleryPage from "../../src/presentation/examples/ui-gallery-page.tsx";
import { LocaleProvider } from "../../src/presentation/i18n/index.ts";
/**
* A starter screen (0929/10-02): `/examples/ui` is template content, so a
* product that replaces it deletes this file with it. The primitives have
* their own suites; this one checks what the page wires them to — the
* validation rule, the shared notice line and the show/hide state.
*/
function renderPage() {
const user = userEvent.setup();
const view = render(
<LocaleProvider>
<UiGalleryPage />
</LocaleProvider>,
);
// The Alert is a status too; the page's notice line is the `<output>`.
const notice = view.container.querySelector("output.gallery-notice");
if (!(notice instanceof HTMLOutputElement)) {
throw new Error("The gallery notice output is missing");
}
return { user, notice };
}
describe("starter UI gallery page", () => {
it("renders every gallery section and the colour token swatches", () => {
const { notice } = renderPage();
expect(
screen.getByRole("heading", { level: 1, name: "UI 구성요소" }),
).toBeVisible();
for (const section of [
"버튼과 입력",
"폼과 선택 컨트롤",
"피드백과 모달",
"탐색 패턴",
"디자인 토큰",
]) {
expect(screen.getByRole("region", { name: section })).toBeVisible();
}
const tokens = screen.getByRole("region", { name: "디자인 토큰" });
expect(within(tokens).getAllByRole("article")).toHaveLength(7);
expect(within(tokens).getByText("--color-focus")).toBeVisible();
expect(notice).toHaveAttribute("aria-live", "polite");
expect(notice).toHaveTextContent(
"구성요소를 조작하면 결과가 여기에 표시됩니다.",
);
});
it("reports each button action on the notice line", async () => {
const { user, notice } = renderPage();
await user.click(screen.getByRole("button", { name: "기본 작업" }));
expect(notice).toHaveTextContent("기본 작업을 실행했습니다.");
await user.click(screen.getByRole("button", { name: "보조 작업" }));
expect(notice).toHaveTextContent("보조 작업을 실행했습니다.");
await user.click(screen.getByRole("button", { name: "위험 작업" }));
expect(notice).toHaveTextContent("위험 작업 예제를 선택했습니다.");
expect(screen.getByRole("button", { name: "사용 불가" })).toBeDisabled();
});
it("rejects a blank project name and accepts a trimmed one", async () => {
const { user, notice } = renderPage();
const field = screen.getByRole("textbox", { name: "프로젝트 이름" });
const submit = screen.getByRole("button", { name: "입력 확인" });
// Untouched: no error yet, even though the field is empty.
expect(field).not.toHaveAttribute("aria-invalid", "true");
await user.click(submit);
expect(field).toHaveAttribute("aria-invalid", "true");
expect(field).toHaveAccessibleDescription(
/프로젝트 이름을 입력해 주세요\./u,
);
expect(notice).toHaveTextContent("입력값을 확인해 주세요.");
// Whitespace is still blank.
await user.type(field, " ");
await user.click(submit);
expect(field).toHaveAttribute("aria-invalid", "true");
await user.type(field, "Starter ");
expect(field).not.toHaveAttribute("aria-invalid", "true");
await user.click(submit);
expect(notice).toHaveTextContent("“Starter” 입력을 확인했습니다.");
});
it("keeps the form and choice controls controlled by page state", async () => {
const { user } = renderPage();
const description = screen.getByRole("textbox", { name: "설명" });
await user.type(description, "공통 예제");
expect(description).toHaveValue("공통 예제");
const template = screen.getByRole("combobox", { name: "시작 템플릿" });
expect(template).toHaveValue("application");
await user.selectOptions(template, "library");
expect(template).toHaveValue("library");
const reviewed = screen.getByRole("checkbox", {
name: "접근성 계약을 확인했습니다.",
});
expect(reviewed).not.toBeChecked();
await user.click(reviewed);
expect(reviewed).toBeChecked();
expect(screen.getByRole("radio", { name: "여유롭게" })).toBeChecked();
await user.click(screen.getByRole("radio", { name: "조밀하게" }));
expect(screen.getByRole("radio", { name: "조밀하게" })).toBeChecked();
expect(screen.getByRole("radio", { name: "여유롭게" })).not.toBeChecked();
const notifications = screen.getByRole("switch", { name: "알림 사용" });
expect(notifications).toBeChecked();
await user.click(notifications);
expect(notifications).not.toBeChecked();
// Native <progress value={3} max={4}>; the label shows the rounded share.
const readiness = screen.getByRole("progressbar", { name: "설정 준비도" });
expect(readiness).toHaveAttribute("value", "3");
expect(readiness).toHaveAttribute("max", "4");
expect(screen.getByText("75%")).toBeVisible();
});
it("dismisses the alert and shows it again", async () => {
const { user } = renderPage();
await user.click(
screen.getByRole("button", { name: "설정이 저장되었습니다. 알림 닫기" }),
);
expect(
screen.queryByText("설정이 저장되었습니다."),
).not.toBeInTheDocument();
await user.click(screen.getByRole("button", { name: "알림 다시 표시" }));
expect(screen.getByText("설정이 저장되었습니다.")).toBeVisible();
expect(
screen.queryByRole("button", { name: "알림 다시 표시" }),
).not.toBeInTheDocument();
});
it("closes the dialog by cancel, close and confirm, and only confirm reports", async () => {
const { user, notice } = renderPage();
const trigger = screen.getByRole("button", { name: "모달 열기" });
const initial = notice.textContent;
await user.click(trigger);
let dialog = screen.getByRole("dialog", { name: "연동 확인" });
expect(dialog).toHaveAttribute("open");
await user.click(within(dialog).getByRole("button", { name: "취소" }));
expect(screen.getByRole("dialog", { hidden: true })).not.toHaveAttribute(
"open",
);
expect(notice).toHaveTextContent(initial ?? "");
await waitFor(() => expect(trigger).toHaveFocus());
await user.click(trigger);
dialog = screen.getByRole("dialog", { name: "연동 확인" });
await user.click(
within(dialog).getByRole("button", { name: "연동 확인 닫기" }),
);
expect(screen.getByRole("dialog", { hidden: true })).not.toHaveAttribute(
"open",
);
expect(notice).toHaveTextContent(initial ?? "");
await user.click(trigger);
dialog = screen.getByRole("dialog", { name: "연동 확인" });
await user.click(within(dialog).getByRole("button", { name: "확인" }));
expect(screen.getByRole("dialog", { hidden: true })).not.toHaveAttribute(
"open",
);
expect(notice).toHaveTextContent("모달의 확인 작업을 실행했습니다.");
});
it("runs the menu actions: one reports on the notice, one pushes a toast", async () => {
const { user, notice } = renderPage();
const trigger = screen.getByRole("button", { name: "작업 메뉴" });
await user.click(trigger);
await user.click(screen.getByRole("menuitem", { name: "상태 확인" }));
expect(notice).toHaveTextContent("메뉴 작업을 실행했습니다.");
expect(screen.queryByRole("menu")).not.toBeInTheDocument();
await user.click(trigger);
await user.click(screen.getByRole("menuitem", { name: "Toast 표시" }));
const region = screen.getByRole("region", { name: "알림" });
expect(
within(region).getByText("예제가 저장되었습니다."),
).toBeVisible();
});
it("switches tab panels only on explicit activation", async () => {
const { user } = renderPage();
const tokens = screen.getByRole("tab", { name: "토큰" });
expect(tokens).toHaveAttribute("aria-selected", "true");
tokens.focus();
await user.keyboard("{ArrowRight}");
const primitives = screen.getByRole("tab", { name: "프리미티브" });
expect(primitives).toHaveFocus();
expect(primitives).toHaveAttribute("aria-selected", "false");
await user.keyboard("{Enter}");
expect(primitives).toHaveAttribute("aria-selected", "true");
expect(
screen.getByRole("tabpanel", { name: "프리미티브" }),
).toHaveTextContent("native semantics와 interaction을 닫습니다.");
});
it("describes the help button with its tooltip", async () => {
const { user } = renderPage();
const help = screen.getByRole("button", { name: "도움말" });
await user.hover(help);
expect(screen.getByRole("tooltip")).toHaveTextContent(
"이 설명은 필수 정보가 아닙니다.",
);
expect(help).toHaveAccessibleDescription("이 설명은 필수 정보가 아닙니다.");
});
});