// @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"; 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( existing content , ); 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/03-03. The coordinator says when the unknown request has no key; // the surface then draws no resend, whatever callback the page passes. it("draws no resend for an unknown request that cannot be resent", () => { render( , ); expect( screen.queryByRole("button", { name: "같은 요청으로 다시 보내기" }), ).not.toBeInTheDocument(); expect(screen.getByRole("button", { name: "변경됨으로 확인" })).toBeInTheDocument(); }); it("keeps the resend state to an unknown mutation only", () => { expect( deriveAsyncState({ data: ["value"], isUnknownEffectResendable: false }), ).not.toHaveProperty("unknownEffectResendable"); expect( deriveAsyncState({ data: ["value"], hasMutationEffectUnknown: true, isUnknownEffectResendable: true, }).unknownEffectResendable, ).toBe(true); }); // 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( , ); 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(existing content); 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( existing content , ); await user.click(screen.getByRole("button", { name: "다시 시도" })); expect(retry).toHaveBeenCalledOnce(); const conflict = deriveAsyncState({ data: ["value"], hasMutationConflict: true, }); view.rerender( existing content , ); 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(); 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(); 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( , ); 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( , ); 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(); 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( content, ); expect(container).toBeEmptyDOMElement(); rerender( 조건을 먼저 선택하세요.

} > content
, ); 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( , ); expect(container.querySelector('[aria-busy="true"]')).not.toBeNull(); rerender(); 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( {}} />, ); const expected = gallery.container.querySelector(".state-surface"); expect(expected).not.toBeNull(); const expectedText = expected?.textContent; gallery.unmount(); render( , ); 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) => ], [ "terminal error", (level?: 2 | 3 | 4) => ( ), ], [ "access", (level?: 2 | 3 | 4) => ( {}} headingLevel={level} /> ), ], [ "async empty", (level?: 2 | 3 | 4) => ( ), ], [ "async access failure", (level?: 2 | 3 | 4) => ( ), ], [ "form error summary", (level?: 2 | 3 | 4) => ( 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); }); });