문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.
고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.
위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).
검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
reference-page 3. 예: "Unable to find an element with the text: 지원
참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
59 files 336 tests 통과. e2e reference-save·reference-form·
reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
check-i18n, check-design-system 통과.
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
382 lines
13 KiB
TypeScript
382 lines
13 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();
|
|
});
|
|
|
|
// 0929/08-04. The unknown result is the case a user most wants to report.
|
|
it("shows the support reference of a save whose effect is unknown", () => {
|
|
render(
|
|
<AsyncSurface
|
|
state={deriveAsyncState({ data: ["value"], hasMutationEffectUnknown: true })}
|
|
supportReference="corr-save-500"
|
|
/>,
|
|
);
|
|
|
|
expect(screen.getByRole("status")).toHaveTextContent("지원 참조: corr-save-500");
|
|
});
|
|
|
|
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(["비동기 데이터 상태", "접근과 탐색 상태"]);
|
|
});
|
|
});
|