문제: 접근성 기본 장치 일부를 지키는 테스트가 없었다. 리뷰 변이 중 M3(건너뛰기 링크 대상을 #content로), M4(LoadingSurface의 aria-live 제거), M5(상태 화면 제목을 <p>로), M6(사이드바 aria-label 제거)가 component 211개를 모두 통과했다. e2e의 axe는 WCAG 태그만 돌려 best-practice인 skip-link 규칙이 빠지고, 건너뛰기 링크를 누르는 e2e도 없었다. 고른 방법: 리뷰의 최소 개선 방향 그대로 단언을 더했다. - app-shell.test.tsx: 건너뛰기 링크 href가 main의 id와 같고, 이름 있는 complementary 안에 주요 탐색이 있다. - async-surface.test.tsx: LoadingSurface가 aria-busy와 aria-live="polite"를 가진다. - accessibility.spec.ts: 건너뛰기 링크 Enter 뒤 포커스가 main 안에 있다. - M5는 08-05 커밋의 제목 수준 테스트가 이미 잡는다. 버린 대안: axe에 best-practice 태그를 켜기 — 이번 범위 밖의 위반까지 한꺼번에 게이트가 된다. 위험·한계: 사이드바 이름 "사이드바"는 위치를 말하는 이름이라 리뷰가 관찰로 남겼다. 테스트는 지금 이름을 고정하므로 이름을 바꾸면 테스트도 같이 바꾼다. M3 변이 빌드에서 e2e는 공용 실행 잠금이 길게 잡혀 돌리지 못했다(component 테스트가 M3를 잡는다). 검증(테스트만 추가라 RED는 변이로 확인): - M3: app-shell landmarks 테스트 실패(1 failed | 221 passed) - M4: loading surface 테스트 실패(1 failed | 221 passed) - M5(state-surfaces.tsx 제목을 <p>로): 08-05 테스트 2건 실패 - M6: app-shell landmarks 테스트 실패(1 failed | 221 passed) - 변이 없음: tests/component 222/222, 새 e2e chromium·firefox·webkit 3/3. tsc test 통과, eslint 통과. Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-09
370 lines
12 KiB
TypeScript
370 lines
12 KiB
TypeScript
// @vitest-environment jsdom
|
|
|
|
import { render, screen } from "@testing-library/react";
|
|
import userEvent from "@testing-library/user-event";
|
|
import { describe, expect, it, vi } from "vitest";
|
|
|
|
import { deriveAsyncState } from "../../src/application/view-models/async-state.ts";
|
|
import { AsyncSurface } from "../../src/presentation/components/async-surface.tsx";
|
|
import { createFailure } from "../../src/contracts/errors.ts";
|
|
import {
|
|
AccessSurface,
|
|
EmptySurface,
|
|
ErrorSummary,
|
|
LoadingSurface,
|
|
TerminalErrorSurface,
|
|
} from "../../src/presentation/design-system/index.ts";
|
|
import StateGalleryPage from "../../src/presentation/examples/state-gallery-page.tsx";
|
|
|
|
describe("async UI state matrix", () => {
|
|
it.each([
|
|
[{ isInitialLoading: true }, "initial-loading"],
|
|
[{ data: [{ id: "1" }] }, "success"],
|
|
[{ data: [] }, "empty"],
|
|
[{ data: null }, "empty"],
|
|
[{}, "idle"],
|
|
[
|
|
{ failure: createFailure("SERVER_FAILURE", "LIST", 0) },
|
|
"terminal-error",
|
|
],
|
|
])("derives base state %#", (signals, expected) => {
|
|
expect(deriveAsyncState(signals).base).toBe(expected);
|
|
});
|
|
|
|
it.each([
|
|
[{ data: ["value"], isFetching: true }, "refreshing"],
|
|
[{ data: ["value"], isStale: true, isDegraded: true }, "stale-degraded"],
|
|
[{ data: ["value"], isMutationPending: true }, "mutation-pending"],
|
|
[
|
|
{ data: ["value"], hasMutationEffectUnknown: true },
|
|
"mutation-effect-unknown",
|
|
],
|
|
[{ data: ["value"], hasMutationConflict: true }, "mutation-conflict"],
|
|
])("derives overlay state %#", (signals, indicator) => {
|
|
expect(deriveAsyncState(signals).indicator).toBe(indicator);
|
|
});
|
|
|
|
it("makes crossed overlay inputs mutually exclusive by priority", () => {
|
|
const state = deriveAsyncState({
|
|
data: ["value"],
|
|
isFetching: true,
|
|
isMutationPending: true,
|
|
hasMutationEffectUnknown: true,
|
|
hasMutationConflict: true,
|
|
});
|
|
expect(state.indicator).toBe("mutation-effect-unknown");
|
|
expect(state.overlay).toMatchObject({
|
|
refreshing: false,
|
|
mutationPending: false,
|
|
mutationEffectUnknown: true,
|
|
mutationConflict: false,
|
|
});
|
|
});
|
|
|
|
it("renders unknown mutation effects with confirm-applied and resend only", async () => {
|
|
const user = userEvent.setup();
|
|
const retry = vi.fn();
|
|
const reconcile = vi.fn();
|
|
const resend = vi.fn();
|
|
const state = deriveAsyncState({
|
|
data: ["value"],
|
|
hasMutationEffectUnknown: true,
|
|
});
|
|
|
|
render(
|
|
<AsyncSurface
|
|
state={state}
|
|
onRetry={retry}
|
|
onReconcileUnknownEffect={reconcile}
|
|
onResendUnknownEffect={resend}
|
|
>
|
|
existing content
|
|
</AsyncSurface>,
|
|
);
|
|
|
|
expect(screen.getByRole("status")).toHaveTextContent(
|
|
"변경 결과를 확인할 수 없습니다.",
|
|
);
|
|
expect(
|
|
screen.getByText("existing content").closest("section"),
|
|
).toHaveAttribute("aria-busy", "false");
|
|
expect(
|
|
screen.queryByRole("button", { name: "다시 시도" }),
|
|
).not.toBeInTheDocument();
|
|
expect(
|
|
screen.queryByRole("button", { name: "변경되지 않음으로 확인" }),
|
|
).not.toBeInTheDocument();
|
|
await user.click(screen.getByRole("button", { name: "변경됨으로 확인" }));
|
|
await user.click(
|
|
screen.getByRole("button", { name: "같은 요청으로 다시 보내기" }),
|
|
);
|
|
expect(reconcile).toHaveBeenCalledExactlyOnceWith("APPLIED");
|
|
expect(resend).toHaveBeenCalledOnce();
|
|
expect(retry).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("keeps content visible while a non-blocking refresh runs", () => {
|
|
const state = deriveAsyncState({ data: ["value"], isFetching: true });
|
|
render(<AsyncSurface state={state}>existing content</AsyncSurface>);
|
|
|
|
expect(screen.getByText("existing content")).toBeVisible();
|
|
expect(screen.getByRole("status")).toHaveTextContent(
|
|
"최신 정보를 확인하고 있습니다.",
|
|
);
|
|
});
|
|
|
|
it("connects stale retry and conflict resolution to real callbacks", async () => {
|
|
const user = userEvent.setup();
|
|
const retry = vi.fn();
|
|
const resolveConflict = vi.fn();
|
|
const stale = deriveAsyncState({
|
|
data: ["value"],
|
|
isStale: true,
|
|
isDegraded: true,
|
|
});
|
|
const view = render(
|
|
<AsyncSurface state={stale} onRetry={retry}>
|
|
existing content
|
|
</AsyncSurface>,
|
|
);
|
|
await user.click(screen.getByRole("button", { name: "다시 시도" }));
|
|
expect(retry).toHaveBeenCalledOnce();
|
|
|
|
const conflict = deriveAsyncState({
|
|
data: ["value"],
|
|
hasMutationConflict: true,
|
|
});
|
|
view.rerender(
|
|
<AsyncSurface
|
|
state={conflict}
|
|
onResolveConflict={resolveConflict}
|
|
>
|
|
existing content
|
|
</AsyncSurface>,
|
|
);
|
|
await user.click(screen.getByRole("button", { name: "충돌 해결" }));
|
|
expect(resolveConflict).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
// 08-07. The id a user quotes when asking for help is the one the request
|
|
// diagnostics carry as `correlation_id`.
|
|
it("shows the failure's request id as its support reference", () => {
|
|
const failure = {
|
|
...createFailure("SERVER_FAILURE", "LIST", 1),
|
|
requestId: "req-7f3a",
|
|
};
|
|
render(<AsyncSurface state={deriveAsyncState({ failure })} />);
|
|
expect(screen.getByRole("alert")).toHaveTextContent("지원 참조: req-7f3a");
|
|
});
|
|
|
|
it("renders only safe error vocabulary", () => {
|
|
const failure = createFailure("SERVER_FAILURE", "LIST", 0, {
|
|
code: "SERVER_FAILURE",
|
|
});
|
|
const state = deriveAsyncState({ failure });
|
|
render(<AsyncSurface state={state} onRetry={vi.fn()} />);
|
|
|
|
expect(screen.getByRole("alert")).toHaveTextContent(
|
|
"요청을 완료하지 못했습니다.",
|
|
);
|
|
expect(screen.getByRole("alert")).toHaveAttribute(
|
|
"data-message-key",
|
|
failure.userMessageKey,
|
|
);
|
|
expect(screen.getByRole("button")).toHaveTextContent("다시 시도");
|
|
expect(screen.getByRole("alert")).not.toHaveTextContent("stack");
|
|
});
|
|
|
|
it("routes terminal actions by failure semantics", async () => {
|
|
const user = userEvent.setup();
|
|
const retry = vi.fn();
|
|
const action = vi.fn();
|
|
const forbidden = deriveAsyncState({
|
|
failure: createFailure("FORBIDDEN", "LIST", 0),
|
|
});
|
|
const view = render(
|
|
<AsyncSurface
|
|
state={forbidden}
|
|
onAction={action}
|
|
onRetry={retry}
|
|
/>,
|
|
);
|
|
|
|
await user.click(
|
|
screen.getByRole("button", { name: "안전한 화면으로 이동" }),
|
|
);
|
|
expect(action).toHaveBeenCalledOnce();
|
|
expect(retry).not.toHaveBeenCalled();
|
|
|
|
const retryable = deriveAsyncState({
|
|
failure: createFailure("SERVER_FAILURE", "LIST", 0),
|
|
});
|
|
view.rerender(
|
|
<AsyncSurface
|
|
state={retryable}
|
|
onAction={action}
|
|
onRetry={retry}
|
|
/>,
|
|
);
|
|
await user.click(screen.getByRole("button", { name: "다시 시도" }));
|
|
expect(retry).toHaveBeenCalledOnce();
|
|
expect(action).toHaveBeenCalledOnce();
|
|
});
|
|
|
|
it("announces a loading surface politely while it is busy (08-09)", () => {
|
|
render(<LoadingSurface label="목록을 불러오는 중" />);
|
|
|
|
const surface = screen.getByRole("region", { name: "목록을 불러오는 중" });
|
|
expect(surface).toHaveAttribute("aria-busy", "true");
|
|
expect(surface).toHaveAttribute("aria-live", "polite");
|
|
});
|
|
|
|
it("renders an idle query as neither loading nor empty", () => {
|
|
const { container, rerender } = render(
|
|
<AsyncSurface state={deriveAsyncState({})}>content</AsyncSurface>,
|
|
);
|
|
expect(container).toBeEmptyDOMElement();
|
|
|
|
rerender(
|
|
<AsyncSurface
|
|
state={deriveAsyncState({})}
|
|
idle={<p>조건을 먼저 선택하세요.</p>}
|
|
>
|
|
content
|
|
</AsyncSurface>,
|
|
);
|
|
expect(screen.getByText("조건을 먼저 선택하세요.")).toBeVisible();
|
|
expect(container.querySelector("[aria-busy]")).toBeNull();
|
|
expect(screen.queryByText("표시할 항목이 없습니다.")).toBeNull();
|
|
expect(screen.queryByText("content")).toBeNull();
|
|
});
|
|
|
|
it("still renders loading for a first load and the empty copy for an empty result", () => {
|
|
const { container, rerender } = render(
|
|
<AsyncSurface state={deriveAsyncState({ isInitialLoading: true })} />,
|
|
);
|
|
expect(container.querySelector('[aria-busy="true"]')).not.toBeNull();
|
|
|
|
rerender(<AsyncSurface state={deriveAsyncState({ data: [] })} />);
|
|
expect(screen.getByText("표시할 항목이 없습니다.")).toBeVisible();
|
|
});
|
|
|
|
// 08-11. A query failure and the gallery draw one access set, not two.
|
|
it.each([
|
|
["AUTH_REQUIRED", "auth-required"],
|
|
["FORBIDDEN", "forbidden"],
|
|
["NOT_FOUND", "not-found"],
|
|
] as const)(
|
|
"renders a %s query failure with the gallery's access surface",
|
|
async (kind, accessKind) => {
|
|
const user = userEvent.setup();
|
|
const action = vi.fn();
|
|
const failure = createFailure(kind, "LIST", 0);
|
|
const gallery = render(
|
|
<AccessSurface kind={accessKind} onAction={() => {}} />,
|
|
);
|
|
const expected = gallery.container.querySelector(".state-surface");
|
|
expect(expected).not.toBeNull();
|
|
const expectedText = expected?.textContent;
|
|
gallery.unmount();
|
|
|
|
render(
|
|
<AsyncSurface
|
|
state={deriveAsyncState({ failure })}
|
|
onAction={action}
|
|
/>,
|
|
);
|
|
const alert = screen.getByRole("alert");
|
|
expect(alert).toHaveAttribute("data-message-key", failure.userMessageKey);
|
|
expect(alert.querySelector(".state-surface")?.textContent).toBe(
|
|
expectedText,
|
|
);
|
|
await user.click(screen.getByRole("button"));
|
|
expect(action).toHaveBeenCalledOnce();
|
|
},
|
|
);
|
|
|
|
it("does not retain a terminal error after usable data is restored", () => {
|
|
const failed = deriveAsyncState({
|
|
failure: createFailure("SERVER_FAILURE", "LIST", 0),
|
|
});
|
|
const recovered = deriveAsyncState({ data: ["value"] });
|
|
expect(failed.base).toBe("terminal-error");
|
|
expect(recovered.base).toBe("success");
|
|
expect(recovered.failure).toBeUndefined();
|
|
});
|
|
});
|
|
|
|
describe("state surface titles (08-05)", () => {
|
|
const forbidden = createFailure("FORBIDDEN", "LIST", 0);
|
|
const unreachable = createFailure("NETWORK_UNREACHABLE", "LIST", 0);
|
|
|
|
it.each([
|
|
["empty", (level?: 2 | 3 | 4) => <EmptySurface title="빈 목록" headingLevel={level} />],
|
|
[
|
|
"terminal error",
|
|
(level?: 2 | 3 | 4) => (
|
|
<TerminalErrorSurface
|
|
userMessageKey={unreachable.userMessageKey}
|
|
action="none"
|
|
headingLevel={level}
|
|
/>
|
|
),
|
|
],
|
|
[
|
|
"access",
|
|
(level?: 2 | 3 | 4) => (
|
|
<AccessSurface kind="forbidden" onAction={() => {}} headingLevel={level} />
|
|
),
|
|
],
|
|
[
|
|
"async empty",
|
|
(level?: 2 | 3 | 4) => (
|
|
<AsyncSurface state={deriveAsyncState({ data: [] })} headingLevel={level} />
|
|
),
|
|
],
|
|
[
|
|
"async access failure",
|
|
(level?: 2 | 3 | 4) => (
|
|
<AsyncSurface
|
|
state={deriveAsyncState({ failure: forbidden })}
|
|
headingLevel={level}
|
|
/>
|
|
),
|
|
],
|
|
[
|
|
"form error summary",
|
|
(level?: 2 | 3 | 4) => (
|
|
<ErrorSummary
|
|
fieldErrors={{ name: "이름을 입력해 주세요." }}
|
|
fieldLabels={{ name: "이름" }}
|
|
fieldId={(name) => name}
|
|
headingLevel={level}
|
|
/>
|
|
),
|
|
],
|
|
])("titles the %s surface as h2 unless placed deeper", (_, surface) => {
|
|
const { unmount } = render(surface());
|
|
expect(screen.getAllByRole("heading", { level: 2 })).toHaveLength(1);
|
|
unmount();
|
|
|
|
render(surface(4));
|
|
expect(screen.queryAllByRole("heading", { level: 2 })).toHaveLength(0);
|
|
expect(screen.getAllByRole("heading", { level: 4 })).toHaveLength(1);
|
|
});
|
|
|
|
it("nests the gallery's state titles under the card and section around them", () => {
|
|
render(<StateGalleryPage />);
|
|
|
|
expect(
|
|
screen.getByRole("heading", { name: "아직 표시할 항목이 없습니다.", level: 4 }),
|
|
).toBeVisible();
|
|
expect(screen.getAllByRole("heading", { level: 3 }).map((h) => h.textContent))
|
|
.toEqual(expect.arrayContaining(["빈 화면", "복구 가능한 오류"]));
|
|
// Access states sit directly under the section's h2.
|
|
expect(
|
|
screen.queryAllByRole("heading", { level: 2 }).map((h) => h.textContent),
|
|
).toEqual(["비동기 데이터 상태", "접근과 탐색 상태"]);
|
|
});
|
|
});
|