Files
clean-architecture-frontend…/tests/component/form-foundation.test.tsx
T
DongHyeonka 48c1ab7ab6 fix(server-state)!: 손으로 적은 뮤테이션 operation ID를 타입 검사에서 막는다
문제: 1103/16-05 수정으로 commandMutationIdentity가 생겼지만
BoundMutation.operationId는 여전히 string이다. 정책에 operation ID를
문자열로 직접 적으면 오타가 check:types와 check:registries를 통과하고,
저장할 때마다 실행기가 보내기 전에 MISSING_IDEMPOTENCY_KEY 위반으로
거부한다. 매뉴얼 01은 이것을 "못 잡음"으로 적고 있었다.

고른 방법: BoundMutation.operationId를 brand 타입 MutationOperationId로
바꾼다. 이 값을 돌려주는 것은 commandMutationIdentity뿐이라, 문자열을
직접 적으면 check:types가 실패한다. 런타임 값은 descriptor의 문자열
그대로이고 실행기·intent factory는 바뀌지 않는다. 참조 기능과 쓰기 slice
생성기는 이미 commandMutationIdentity를 spread하므로 고칠 것이 없다.
템플릿 테스트의 손글씨 ID 20곳은 tests/helpers/mutation-operation-id.ts
(commandMutationIdentity를 거치는 test helper)나 그 파일의 descriptor로
바꿨다. 매뉴얼 01·patterns 표·state 설계 예시를 맞췄다.
버린 대안: (1) 위반 이름을 INTENT_OPERATION_MISMATCH로 나누는 것. 실행
때만 드러나는 것은 같고, 공개 위반 어휘에 값이 하나 늘어 다운스트림
분기가 바뀐다. (2) 설치된 operation ID의 union 타입. 기능마다 늦게
적재되는 계약 전체를 타입으로 모을 곳이 없다.

위험·한계: 공개 타입(src/contracts/server-state.ts)이 좁아진다. 정책에
operation ID를 문자열로 적은 다운스트림 코드는 동기화 뒤 check:types가
실패한다. commandMutationIdentity에 descriptor 상수 대신 손으로 만든
객체를 넘기면 여전히 오타가 통과한다(매뉴얼 "못 잡음"). HTTP가 아닌
뮤테이션은 descriptor 모양 객체를 넘겨야 한다. 이 repo에는 그런 소비자가
없다.

검증: desktop batch에서 확인.
corepack pnpm check:types:test
tests/unit/command-mutation-identity.test.ts의 @ts-expect-error가 부모
커밋에서는 쓰이지 않아(TS2578) 실패하고 이 커밋에서 통과한다.
node scripts/run-vitest.ts run tests/unit/command-mutation-identity.test.ts tests/component/application-mutation-admission.test.tsx tests/component/application-mutation-scope-fence.test.tsx tests/component/application-query.test.tsx tests/component/form-foundation.test.tsx

BREAKING CHANGE: BoundMutation.operationId는 string이 아니라
MutationOperationId다. 뮤테이션 정책의 `operationId: "<ID>"`와
`requiresIdempotencyKey`를 `...commandMutationIdentity(<OPERATION>_CONTRACT)`
로 바꾼다(src/contracts/server-state.ts). commandMutationIdentity의 반환
타입도 operationId가 MutationOperationId다.

Refs: 1103/16-05
2026-11-05 22:26:27 +09:00

1032 lines
36 KiB
TypeScript

// @vitest-environment jsdom
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { useState } from "react";
import { createMemoryRouter, RouterProvider, useNavigate } from "react-router-dom";
import { z } from "zod";
import { describe, expect, it, vi } from "vitest";
import {
createContractHttpExecutor,
createFeatureHttpBinding,
defineFeatureHttpOperation,
} from "../../src/adapters/http/index.ts";
import { mappingSuccess } from "../../src/contracts/boundary-mapper.ts";
import { createFailure } from "../../src/contracts/errors.ts";
import { createRuntimeIdentityRegistry } from "../../src/contracts/query-keys.ts";
import { commandMutationIdentity } from "../../src/contracts/server-state.ts";
import { zodValidator } from "../../src/contracts/zod-validator.ts";
import { useApplicationMutation } from "../../src/presentation/adapters/query/application-query.ts";
import { queryClient, scopeSnapshot, wrapper } from "./application-query-fixture.tsx";
import { Button } from "../../src/presentation/components/ui/button.ts";
import {
DirtyNavigationDialog,
ErrorSummary,
Form,
FormFailureStatus,
FormField,
useAppForm,
useDirtyNavigationGuard,
validationMessage,
} from "../../src/presentation/forms/index.ts";
import {
formatMessage,
type ParameterlessMessageKey,
} from "../../src/presentation/i18n/index.ts";
/**
* A keyed create that reads the paired backend's Envelope, the shape
* `create:feature` generates for a command.
*/
const FORM_CREATE_CONTRACT = Object.freeze({
contract: Object.freeze({
operationId: "FORM_CREATE_ENTITY",
method: "POST" as const,
pathTemplate: "/api/form-entities",
inputValidator: zodValidator(
"FormCreateEntityCommand",
z.object({ name: z.string().min(1) }).strict(),
),
outputValidator: zodValidator(
"FormEntity",
z.object({ id: z.string(), name: z.string() }).strip(),
),
problemValidator: zodValidator(
"FormProblem",
z
.object({
code: z.string().regex(/^[A-Z0-9_]{1,64}$/u),
details: z.unknown().optional(),
})
.strip(),
),
acceptedStatuses: Object.freeze([200]),
emptyBodyStatuses: Object.freeze([]),
retrySemantics: "KEYED" as const,
requestBody: "JSON" as const,
responseBody: "REQUIRED_JSON" as const,
responseEnvelope: "ENVELOPE_V1" as const,
commandRecovery: Object.freeze({
mode: "IDEMPOTENCY_REPLAY" as const,
operationIdentityField: "idempotencyKey",
}),
commandEffect: Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem: () => "MAYBE_APPLIED" as const,
}),
projectRequest: (input: Readonly<{ name: string }>) =>
Object.freeze({
pathValues: Object.freeze({}),
queryEntries: Object.freeze([]),
body: Object.freeze({ ...input }),
}),
}),
frontend: Object.freeze({
policyId: "FORM_CREATE_V1",
requestByteLimit: 1_024,
responseByteLimit: 4_096,
totalDeadlineMs: 5_000,
retryBudget: 0 as const,
authProfileId: "ANONYMOUS",
diagnosticsOperation: "form.create",
}),
});
const FORM_OPERATIONS = Object.freeze({
FORM_CREATE_ENTITY: defineFeatureHttpOperation({
contract: FORM_CREATE_CONTRACT,
routeId: "FORM_ROUTE",
mapSuccess: (value) => mappingSuccess(value),
}),
});
/**
* 1103/03-01. The same create, declaring the paired backend scaffold's
* `<FEATURE>_INVALID` as refused before the write.
*/
const FORM_DECLARING_OPERATIONS = Object.freeze({
FORM_CREATE_ENTITY: defineFeatureHttpOperation({
contract: Object.freeze({
...FORM_CREATE_CONTRACT,
contract: Object.freeze({
...FORM_CREATE_CONTRACT.contract,
commandEffect: Object.freeze({
...FORM_CREATE_CONTRACT.contract.commandEffect,
refusedBeforeWrite: Object.freeze(["WORKLOG_INVALID"]),
}),
}),
}),
routeId: "FORM_ROUTE",
mapSuccess: (value) => mappingSuccess(value),
}),
});
function formBinding(
fetcher: typeof fetch,
operations:
| typeof FORM_OPERATIONS
| typeof FORM_DECLARING_OPERATIONS = FORM_OPERATIONS,
) {
const executor = createContractHttpExecutor({
baseUrl: "https://api.test",
maxRetryAttempts: 0,
attachCredentials: () => ({ kind: "READY" as const, headers: {} }),
fetcher,
});
return createFeatureHttpBinding(
Object.freeze({
execute: (contract, input, context) =>
executor.execute(contract, input, {
routeId: context.routeId,
scope: scopeSnapshot(),
...(context.intent === undefined ? {} : { intent: context.intent }),
}),
}),
operations,
);
}
type Values = Readonly<Record<"name" | "note", string>>;
const schema = z
.object({
name: z.string().trim().min(2),
note: z.string().trim().default(""),
})
.strict();
const defaults: Values = { name: "", note: "" };
function FormHarness(props: Readonly<{
submit(command: Readonly<{ name: string; note?: string }>): Promise<
| Readonly<{ ok: true; value: string }>
| Readonly<{ ok: false; error: ReturnType<typeof createFailure> }>
>;
resetOnSuccess?: boolean;
onFailureAction?(): void;
}>) {
const form = useAppForm({
schema,
defaultValues: defaults,
allowedServerFields: ["name", "note"],
mapToCommand(values) {
return {
name: values.name,
...(values.note ? { note: values.note } : {}),
};
},
submit: props.submit,
resetOnSuccess: props.resetOnSuccess,
});
return (
<Form pending={form.pending} onSubmit={(event) => void form.submitForm(event)}>
<ErrorSummary
fieldErrors={form.fieldErrors}
formErrors={form.formErrors}
fieldLabels={{ name: "Name", note: "Note" }}
fieldId={form.fieldId}
onFocusField={form.focusField}
/>
<FormFailureStatus
failure={form.failure}
onAction={
form.result === "retry-later"
? () => void form.submitForm()
: props.onFailureAction
}
/>
<FormField {...form.field("name")} label="Name" required />
<FormField {...form.field("note")} label="Note" />
<Button type="submit" disabled={form.pending}>
{form.pending ? "Pending" : "Submit"}
</Button>
<Button onClick={() => form.reset()} disabled={!form.dirty}>
Reset
</Button>
<Button onClick={() => form.settleApplied()}>Confirm applied</Button>
<Button onClick={() => form.settleNotApplied()}>
Confirm not applied
</Button>
<output data-testid="dirty">{String(form.dirty)}</output>
<output data-testid="result">{form.result}</output>
<output data-testid="support">{form.supportReference ?? ""}</output>
</Form>
);
}
describe("local form facade", () => {
it("focuses the first invalid field and performs no command", async () => {
const user = userEvent.setup();
const submit = vi.fn();
render(<FormHarness submit={submit} />);
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(submit).not.toHaveBeenCalled();
expect(screen.getByRole("textbox", { name: /Name/ })).toHaveFocus();
expect(screen.getByRole("alert")).toHaveTextContent("Name");
});
it("submits transformed data once and clears dirty state after success", async () => {
const user = userEvent.setup();
let finish: ((value: { ok: true; value: string }) => void) | undefined;
const submit = vi.fn(
() =>
new Promise<{ ok: true; value: string }>((resolve) => {
finish = resolve;
}),
);
render(<FormHarness submit={submit} />);
await user.type(screen.getByRole("textbox", { name: /Name/ }), " Ready ");
await user.type(screen.getByRole("textbox", { name: "Note" }), " Safe ");
await user.dblClick(screen.getByRole("button", { name: "Submit" }));
await waitFor(() => expect(submit).toHaveBeenCalledOnce());
expect(submit).toHaveBeenCalledWith({ name: "Ready", note: "Safe" });
expect(screen.getByRole("button", { name: "Pending" })).toBeDisabled();
finish?.({ ok: true, value: "saved" });
await waitFor(() => expect(screen.getByTestId("dirty")).toHaveTextContent("false"));
expect(screen.getByTestId("result")).toHaveTextContent("success");
});
it("maps only approved 422 fields and never renders backend copy", async () => {
const user = userEvent.setup();
const failure = createFailure(
"VALIDATION_REJECTED",
"CREATE_ENTITY",
0,
{
validationIssues: [
{ path: "name", code: "REQUIRED" },
{ path: "serverOnly", code: "raw-secret-message" },
],
},
);
render(
<FormHarness submit={async () => ({ ok: false, error: failure })} />,
);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByRole("alert")).toHaveTextContent("필수 입력값입니다.");
expect(screen.getByRole("alert")).toHaveTextContent(
"서버가 확인하지 못한 입력 항목",
);
expect(document.body).not.toHaveTextContent("raw-secret-message");
});
// 백엔드 1101/02-01 후속. The paired backend answers a field validation
// failure with 400 VALIDATION_FAILED and details [{field, code, message}]
// (its docs/web/http-contract.md §4). It reaches the form through the HTTP
// executor and lands on the same allowed fields a 422 does.
it("maps a paired backend 400 VALIDATION_FAILED onto the form fields", async () => {
const user = userEvent.setup();
const http = formBinding(async () =>
Response.json(
{
success: false,
error: {
code: "VALIDATION_FAILED",
category: "VALIDATION",
message: "요청 값이 올바르지 않습니다.",
retryable: false,
details: [
{ field: "name", code: "NOT_BLANK", message: "raw backend copy" },
{ field: "request", code: "INVALID", message: "raw backend copy" },
],
},
meta: { requestId: "request-1", traceId: "trace-1" },
},
{ status: 400 },
),
);
render(
<FormHarness
submit={async (command) => {
const result = await http.execute(
"FORM_CREATE_ENTITY",
{ name: command.name },
{
intent: Object.freeze({
intentId: "intent-1",
operationId: "FORM_CREATE_ENTITY",
canonicalInputIdentity: "{}",
idempotencyKey: "key-1",
createdAtMonotonicMs: 0,
}),
},
);
if (result.ok) throw new Error("expected a validation failure");
return result;
}}
/>,
);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid");
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() =>
expect(screen.getByTestId("result")).toHaveTextContent("validation-error"),
);
expect(screen.getByRole("textbox", { name: /Name/ })).toHaveAttribute(
"aria-invalid",
"true",
);
expect(screen.getByRole("textbox", { name: /Note/ })).not.toHaveAttribute(
"aria-invalid",
);
// NOT_BLANK has its own copy, not the "check the value" default.
expect(screen.getByRole("alert")).toHaveTextContent("필수 입력값입니다.");
// A class-level error names no form field.
expect(screen.getByRole("alert")).toHaveTextContent(
"서버가 확인하지 못한 입력 항목",
);
expect(document.body).not.toHaveTextContent("raw backend copy");
});
// 1103/08-05. The same key went out with another body. The user has
// nothing to correct, so the form shows a status with a support reference.
it("shows a paired backend 422 IDEMPOTENT_REQUEST_MISMATCH as a status, not an input error", async () => {
const user = userEvent.setup();
const http = formBinding(async () =>
Response.json(
{
success: false,
error: {
code: "IDEMPOTENT_REQUEST_MISMATCH",
category: "VALIDATION",
message: "요청 값이 올바르지 않습니다.",
retryable: false,
},
meta: { requestId: "request-1", traceId: "trace-1" },
},
{ status: 422, headers: { "x-correlation-id": "corr-422" } },
),
);
render(
<FormHarness
submit={async (command) => {
const result = await http.execute(
"FORM_CREATE_ENTITY",
{ name: command.name },
{
intent: Object.freeze({
intentId: "intent-1",
operationId: "FORM_CREATE_ENTITY",
canonicalInputIdentity: "{}",
idempotencyKey: "key-1",
createdAtMonotonicMs: 0,
}),
},
);
if (result.ok) throw new Error("expected a mismatch refusal");
return result;
}}
/>,
);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByTestId("result")).toHaveTextContent("unavailable");
expect(document.body).not.toHaveTextContent("입력값을 다시 확인해 주세요.");
expect(screen.getByRole("textbox", { name: /Name/ })).not.toHaveAttribute(
"aria-invalid",
);
expect(screen.getByRole("alert")).toHaveTextContent("지원 참조: corr-422");
expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();
});
it.each([
[
"AUTH_REQUIRED",
"reauth-required",
"계속하려면 로그인이 필요합니다.",
"로그인",
],
[
"FORBIDDEN",
"forbidden",
"이 작업을 수행할 권한이 없습니다.",
"안전한 화면으로 이동",
],
[
"RATE_LIMITED",
"retry-later",
"요청이 많습니다. 잠시 후 다시 시도해 주세요.",
"다시 시도",
],
] as const)(
"shows %s as its own save state, not an input error",
async (kind, result, copy, action) => {
const user = userEvent.setup();
const onFailureAction = vi.fn();
const submit = vi.fn(async () => ({
ok: false as const,
error: createFailure(kind, "CREATE_ENTITY", 0, {
effect: "NOT_APPLIED",
}),
}));
render(
<FormHarness submit={submit} onFailureAction={onFailureAction} />,
);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByTestId("result")).toHaveTextContent(result);
expect(screen.getByRole("alert")).toHaveTextContent(copy);
expect(document.body).not.toHaveTextContent("입력 내용을 확인해 주세요.");
expect(document.body).not.toHaveTextContent("저장하지 못했습니다.");
expect(
document.body.textContent?.includes("입력한 내용은 사라집니다"),
).toBe(kind === "AUTH_REQUIRED");
expect(screen.getByRole("textbox", { name: /Name/ })).toHaveValue("Valid");
await user.click(screen.getByRole("button", { name: action }));
if (kind === "RATE_LIMITED") {
expect(submit).toHaveBeenCalledTimes(2);
expect(onFailureAction).not.toHaveBeenCalled();
} else {
expect(onFailureAction).toHaveBeenCalledOnce();
}
},
);
// F-10 (08-01). A save that failed for a reason the user cannot fix in the
// input is a status with its own action, never an input error summary.
it.each([
["NOT_FOUND", "요청한 항목을 찾을 수 없습니다.", "안전한 화면으로 이동"],
["UNKNOWN_CLIENT_FAILURE", "요청을 처리할 수 없습니다.", "지원 정보 확인"],
] as const)(
"shows an unavailable %s save as a status, not an input error",
async (kind, copy, action) => {
const user = userEvent.setup();
const onFailureAction = vi.fn();
render(
<FormHarness
submit={async () => ({
ok: false,
error: createFailure(kind, "CREATE_ENTITY", 0, {
effect: "NOT_APPLIED",
}),
})}
onFailureAction={onFailureAction}
/>,
);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByTestId("result")).toHaveTextContent(
"unavailable",
);
expect(screen.getByRole("alert")).toHaveTextContent(copy);
expect(document.body).not.toHaveTextContent("입력 내용을 확인해 주세요.");
await user.click(screen.getByRole("button", { name: action }));
expect(onFailureAction).toHaveBeenCalledOnce();
},
);
// 0929/08-04. A failed or unknown save carries the id a user quotes to
// support, the same as a failed query.
it("shows the save failure's request id as its support reference", async () => {
const user = userEvent.setup();
render(
<FormHarness
submit={async () => ({
ok: false,
error: createFailure("UNKNOWN_CLIENT_FAILURE", "CREATE_ENTITY", 0, {
effect: "NOT_APPLIED",
requestId: "corr-save-400",
}),
})}
/>,
);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByRole("alert")).toHaveTextContent(
"지원 참조: corr-save-400",
);
expect(screen.getByTestId("support")).toHaveTextContent("corr-save-400");
});
it("keeps the request id of a save whose effect is unknown", async () => {
const user = userEvent.setup();
render(
<FormHarness
submit={async () => ({
ok: false,
error: createFailure("SERVER_FAILURE", "CREATE_ENTITY", 0, {
effect: "MAYBE_APPLIED",
requestId: "corr-save-500",
}),
})}
resetOnSuccess={false}
/>,
);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Valid");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByTestId("result")).toHaveTextContent("effect-unknown");
expect(screen.getByTestId("support")).toHaveTextContent("corr-save-500");
await user.click(screen.getByRole("button", { name: "Confirm applied" }));
expect(screen.getByTestId("support")).toHaveTextContent("");
});
it("keeps conflict input out of URL and storage", async () => {
const user = userEvent.setup();
localStorage.clear();
window.history.replaceState({}, "", "/form-test");
render(
<FormHarness
submit={async () => ({
ok: false,
error: createFailure("CONFLICT", "CREATE_ENTITY", 0),
})}
/>,
);
const secretLike = "token-like-do-not-copy";
await user.type(screen.getByRole("textbox", { name: /Name/ }), secretLike);
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByText(/다른 변경과 충돌했습니다/)).toBeVisible();
expect(screen.getByRole("textbox", { name: /Name/ })).toHaveValue(secretLike);
expect(window.location.href).not.toContain(secretLike);
expect(JSON.stringify(localStorage)).not.toContain(secretLike);
});
it("blocks a second submit while the prior effect remains unknown", async () => {
const user = userEvent.setup();
const submit = vi.fn(async () => ({
ok: false as const,
error: createFailure("SERVER_FAILURE", "CREATE_ENTITY", 0, {
effect: "MAYBE_APPLIED",
}),
}));
render(<FormHarness submit={submit} resetOnSuccess={false} />);
const name = screen.getByRole("textbox", { name: /Name/ });
await user.type(name, "Alpha");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(await screen.findByTestId("result")).toHaveTextContent(
"effect-unknown",
);
await user.clear(name);
await user.type(name, "Beta");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(submit).toHaveBeenCalledOnce();
expect(screen.getByTestId("result")).toHaveTextContent("effect-unknown");
});
it("settles the submitted unknown snapshot without accepting later edits", async () => {
const user = userEvent.setup();
const submit = vi.fn(async () => ({
ok: false as const,
error: createFailure("SERVER_FAILURE", "CREATE_ENTITY", 0, {
effect: "MAYBE_APPLIED",
}),
}));
render(<FormHarness submit={submit} resetOnSuccess={false} />);
const name = screen.getByRole("textbox", { name: /Name/ });
await user.type(name, "Alpha");
await user.click(screen.getByRole("button", { name: "Submit" }));
await screen.findByText("effect-unknown");
await user.clear(name);
await user.type(name, "Beta");
await user.click(screen.getByRole("button", { name: "Confirm applied" }));
expect(name).toHaveValue("Beta");
expect(screen.getByTestId("result")).toHaveTextContent("success");
expect(screen.getByTestId("dirty")).toHaveTextContent("true");
await user.clear(name);
await user.type(name, "Alpha");
expect(screen.getByTestId("dirty")).toHaveTextContent("false");
});
it("releases an unknown submission only after explicit not-applied settlement", async () => {
const user = userEvent.setup();
const submit = vi
.fn()
.mockResolvedValueOnce({
ok: false as const,
error: createFailure("SERVER_FAILURE", "CREATE_ENTITY", 0, {
effect: "MAYBE_APPLIED",
}),
})
.mockResolvedValueOnce({ ok: true as const, value: "saved" });
render(<FormHarness submit={submit} resetOnSuccess={false} />);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Alpha");
await user.click(screen.getByRole("button", { name: "Submit" }));
await screen.findByText("effect-unknown");
await user.click(
screen.getByRole("button", { name: "Confirm not applied" }),
);
expect(screen.getByTestId("result")).toHaveTextContent("idle");
await user.click(screen.getByRole("button", { name: "Submit" }));
expect(submit).toHaveBeenCalledTimes(2);
});
});
// 1101/14.4. Every code the paired backend can put in a field error's
// details[].code: clean-architecture-backend-template 5786126c,
// ClientSafeValidationDetails.java RULES (18-42) and its INVALID fallback.
// http-contract.md §4 names the shape, not the list. A code missing from the
// form copy table shows the "check the value" default instead.
const BACKEND_FIELD_CODES = [
"NOT_NULL",
"NOT_BLANK",
"NOT_EMPTY",
"SIZE",
"MIN",
"MAX",
"POSITIVE",
"POSITIVE_OR_ZERO",
"NEGATIVE",
"NEGATIVE_OR_ZERO",
"PATTERN",
"EMAIL",
"PAST",
"PAST_OR_PRESENT",
"FUTURE",
"FUTURE_OR_PRESENT",
"ASSERT_TRUE",
"ASSERT_FALSE",
"TYPE_MISMATCH",
"INVALID",
] as const;
describe("paired backend field codes", () => {
it.each(["ko-KR", "en-US"] as const)(
"gives every backend field code its own %s copy",
(locale) => {
const message = (key: ParameterlessMessageKey) =>
formatMessage(locale, key);
const fallback = message("form.validation.unknown");
expect(
BACKEND_FIELD_CODES.filter(
(code) => validationMessage(code, message) === fallback,
),
).toEqual([]);
},
);
it.each(["SOME_FUTURE_CODE", "constructor", "toString", "__proto__", "hasOwnProperty"])(
"keeps the default copy for a code it does not know (%s)",
(code) => {
// 1103/08-03. Names inherited from Object.prototype are unknown codes too.
expect(validationMessage(code)).toBe(
formatMessage("ko-KR", "form.validation.unknown"),
);
},
);
});
describe("dirty navigation guard", () => {
it("blocks navigation, restores focus on stay and proceeds explicitly", async () => {
const user = userEvent.setup();
function GuardedPage() {
const navigate = useNavigate();
const [dirty, setDirty] = useState(false);
const guard = useDirtyNavigationGuard(dirty);
return (
<>
<label htmlFor="guard-field">Guard field</label>
<input
id="guard-field"
onChange={() => setDirty(true)}
/>
<Button onClick={() => navigate("/target")}>Leave</Button>
<DirtyNavigationDialog guard={guard} />
</>
);
}
const router = createMemoryRouter(
[
{ path: "/", element: <GuardedPage /> },
{ path: "/target", element: <h1>Target</h1> },
],
{ initialEntries: ["/"] },
);
render(<RouterProvider router={router} />);
await user.type(screen.getByRole("textbox", { name: "Guard field" }), "x");
const leave = screen.getByRole("button", { name: "Leave" });
await user.click(leave);
expect(
screen.getByRole("dialog", { name: "저장하지 않은 변경이 있습니다." }),
).toHaveAttribute("open");
await user.click(screen.getByRole("button", { name: "계속 작성" }));
await waitFor(() => expect(leave).toHaveFocus());
await user.click(leave);
await user.click(screen.getByRole("button", { name: "변경 버리고 이동" }));
expect(await screen.findByRole("heading", { name: "Target" })).toBeVisible();
});
});
describe("submission timing", () => {
it("submits once when a second submit arrives during async validation", async () => {
const user = userEvent.setup();
let releaseValidation: () => void = () => {};
const validationGate = new Promise<void>((resolve) => {
releaseValidation = resolve;
});
const asyncSchema = schema.refine(async () => {
await validationGate;
return true;
});
const submit = vi.fn(async () => ({ ok: true as const, value: "saved" }));
function AsyncForm() {
const form = useAppForm({
schema: asyncSchema,
defaultValues: defaults,
allowedServerFields: ["name", "note"],
mapToCommand: (values) => ({ name: values.name }),
submit,
});
return (
<Form pending={form.pending} onSubmit={(event) => void form.submitForm(event)}>
<FormField {...form.field("name")} label="Name" required />
<Button type="submit">Submit</Button>
<output data-testid="result">{form.result}</output>
<output data-testid="support">{form.supportReference ?? ""}</output>
</Form>
);
}
render(<AsyncForm />);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Ready");
await user.click(screen.getByRole("button", { name: "Submit" }));
await user.click(screen.getByRole("button", { name: "Submit" }));
releaseValidation();
await waitFor(() =>
expect(screen.getByTestId("result")).toHaveTextContent("success"),
);
expect(submit).toHaveBeenCalledOnce();
});
it("does not ask to discard changes when navigating right after a save", async () => {
const user = userEvent.setup();
function SaveThenLeave() {
const navigate = useNavigate();
const form = useAppForm({
schema,
defaultValues: defaults,
allowedServerFields: ["name", "note"],
mapToCommand: (values) => ({ name: values.name }),
submit: async () => ({ ok: true as const, value: "saved" }),
});
const guard = useDirtyNavigationGuard(form.dirty);
return (
<Form
onSubmit={(event) => {
void form.submitForm(event).then((outcome) => {
if (outcome?.ok) void navigate("/done");
});
}}
pending={form.pending}
>
<FormField {...form.field("name")} label="Name" required />
<Button type="submit">Save</Button>
<DirtyNavigationDialog guard={guard} />
</Form>
);
}
const router = createMemoryRouter(
[
{ path: "/", element: <SaveThenLeave /> },
{ path: "/done", element: <h1>Done</h1> },
],
{ initialEntries: ["/"] },
);
render(<RouterProvider router={router} />);
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Ready");
await user.click(screen.getByRole("button", { name: "Save" }));
expect(await screen.findByRole("heading", { name: "Done" })).toBeVisible();
expect(
screen.queryByRole("dialog", { name: "저장하지 않은 변경이 있습니다." }),
).not.toBeInTheDocument();
});
});
/**
* A server validation refusal through the HTTP executor and the mutation
* coordinator, with the reference form page's gate: the save button is off
* while the coordinator holds an unknown effect.
*/
describe("correcting a field after a server validation refusal", () => {
let token = 0;
const scope = {
...scopeSnapshot(),
identities: createRuntimeIdentityRegistry({
tokenFactory: () => `form-identity-token-${String(++token).padStart(4, "0")}`,
}),
};
function CoordinatedForm(
props: Readonly<{
fetcher: typeof fetch;
operations?: typeof FORM_DECLARING_OPERATIONS;
}>,
) {
const [http] = useState(() => formBinding(props.fetcher, props.operations));
const mutation = useApplicationMutation<
Readonly<{ name: string; note?: string }>,
unknown
>({
definitionId: "form-create-v1",
definitionVersion: 1,
operationId: commandMutationIdentity(FORM_CREATE_CONTRACT).operationId,
requiresIdempotencyKey: true,
owner: "platform-test",
duplicatePolicy: "REJECT_WHILE_ACTIVE",
scope,
invalidate: [],
execute: (command, { intent }) =>
http.execute("FORM_CREATE_ENTITY", { name: command.name }, { intent }),
});
const form = useAppForm({
schema,
defaultValues: defaults,
allowedServerFields: ["name", "note"],
mapToCommand: (values) => ({ name: values.name }),
submit: mutation.submit,
});
const blocked =
mutation.state.indicator === "mutation-effect-unknown" ||
mutation.state.indicator === "mutation-pending";
return (
<Form pending={form.pending} onSubmit={(event) => void form.submitForm(event)}>
<FormField {...form.field("name")} label="Name" required />
<Button type="submit" disabled={form.pending || blocked}>
Submit
</Button>
<output data-testid="result">{form.result}</output>
</Form>
);
}
const meta = { requestId: "request-1", traceId: "trace-1" };
function answerFirst(status: number, error: unknown) {
return vi
.fn<typeof fetch>()
.mockResolvedValueOnce(
Response.json({ success: false, error, meta }, { status }),
)
.mockImplementation(async () =>
Response.json({
success: true,
data: { id: "entity-1", name: "Fixed" },
meta,
}),
);
}
// 백엔드 1101/02-01 후속. The paired backend's 400 VALIDATION_FAILED with
// the field list (its docs/web/http-contract.md §4).
it("saves the corrected value after a 400 field error", async () => {
const user = userEvent.setup();
const fetcher = answerFirst(400, {
code: "VALIDATION_FAILED",
details: [{ field: "name", code: "NOT_BLANK", message: "필수 값이 없습니다." }],
});
render(<CoordinatedForm fetcher={fetcher} />, {
wrapper: wrapper(queryClient()),
});
const name = screen.getByRole("textbox", { name: /Name/ });
await user.type(name, "Rejected");
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() => expect(name).toHaveAttribute("aria-invalid", "true"));
await user.clear(name);
await user.type(name, "Fixed");
expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() =>
expect(screen.getByTestId("result")).toHaveTextContent("success"),
);
expect(fetcher).toHaveBeenCalledTimes(2);
});
// 1101/14.4. A body the backend could not read is refused while binding,
// before any write (frontend contract 6.1), so the save is not held.
it("saves again after a 400 VALIDATION_FAILED whose body did not parse", async () => {
const user = userEvent.setup();
const fetcher = answerFirst(400, {
code: "VALIDATION_FAILED",
details: { cause: "JsonParseException" },
});
render(<CoordinatedForm fetcher={fetcher} />, {
wrapper: wrapper(queryClient()),
});
await user.type(screen.getByRole("textbox", { name: /Name/ }), "Fixed");
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() => expect(fetcher).toHaveBeenCalledTimes(1));
await waitFor(() =>
expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled(),
);
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() =>
expect(screen.getByTestId("result")).toHaveTextContent("success"),
);
expect(fetcher).toHaveBeenCalledTimes(2);
});
function sentKeys(fetcher: ReturnType<typeof answerFirst>) {
return fetcher.mock.calls.map(
([, init]) => (init?.headers as Readonly<Record<string, string>>)["Idempotency-Key"],
);
}
// 1103/03-01 (= 08-01). The paired backend scaffold's create refuses a bad
// name with 400 <FEATURE>_INVALID before its transaction. Declared on the
// operation, the refusal is not an unknown result: the user corrects the
// value and saves again, and the second request is a new one.
it("saves the corrected value after a declared pre-write refusal, with a new key", async () => {
const user = userEvent.setup();
const fetcher = answerFirst(400, { code: "WORKLOG_INVALID" });
render(
<CoordinatedForm fetcher={fetcher} operations={FORM_DECLARING_OPERATIONS} />,
{ wrapper: wrapper(queryClient()) },
);
const name = screen.getByRole("textbox", { name: /Name/ });
await user.type(name, "Rejected");
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() =>
expect(screen.getByTestId("result")).toHaveTextContent("unavailable"),
);
expect(screen.getByRole("button", { name: "Submit" })).toBeEnabled();
await user.clear(name);
await user.type(name, "Fixed");
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() =>
expect(screen.getByTestId("result")).toHaveTextContent("success"),
);
expect(fetcher).toHaveBeenCalledTimes(2);
expect(sentKeys(fetcher)).toEqual(["key-1", "key-2"]);
});
// 1103/03-01. A code the operation did not declare may have been raised
// after a write, so the coordinator keeps holding it.
it("keeps the save off after a business refusal the operation did not declare", async () => {
const user = userEvent.setup();
const fetcher = answerFirst(400, { code: "WORKLOG_INVALID" });
render(<CoordinatedForm fetcher={fetcher} />, {
wrapper: wrapper(queryClient()),
});
const name = screen.getByRole("textbox", { name: /Name/ });
await user.type(name, "Rejected");
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() =>
expect(screen.getByTestId("result")).toHaveTextContent("effect-unknown"),
);
await user.clear(name);
await user.type(name, "Fixed");
expect(screen.getByRole("button", { name: "Submit" })).toBeDisabled();
expect(fetcher).toHaveBeenCalledTimes(1);
});
// 1101/14.4. Outside IDEMPOTENT_REQUEST_MISMATCH a 422 may come after a
// write (fileserver INTEGRITY_MISMATCH), so the coordinator holds it as an
// unknown result even though the form shows the field.
it("keeps the save off after a 422 the backend may have applied", async () => {
const user = userEvent.setup();
const fetcher = answerFirst(422, {
code: "INVALID_INPUT",
details: { issues: [{ path: "name", code: "REQUIRED" }] },
});
render(<CoordinatedForm fetcher={fetcher} />, {
wrapper: wrapper(queryClient()),
});
const name = screen.getByRole("textbox", { name: /Name/ });
await user.type(name, "Rejected");
await user.click(screen.getByRole("button", { name: "Submit" }));
await waitFor(() => expect(name).toHaveAttribute("aria-invalid", "true"));
expect(screen.getByRole("button", { name: "Submit" })).toBeDisabled();
expect(fetcher).toHaveBeenCalledTimes(1);
});
});