Files
clean-architecture-frontend…/tests/e2e/generated-feature.spec.ts
T

399 lines
16 KiB
TypeScript

import AxeBuilder from "@axe-core/playwright";
import type { Page, Route } from "@playwright/test";
import { WCAG_AXE_TAGS } from "../support/browser/axe-tags.ts";
import { KO_MESSAGES } from "../../src/presentation/i18n/catalog.ts";
import { expect, test } from "../support/browser/strict-browser-test.ts";
import {
prepareFixtureBuilds,
removeFixtureBuilds,
type FixtureBuilds,
} from "./support/fixture-builds.ts";
import {
addGeneratedFeature,
generatedFeature,
generatedMessageKey,
routePath,
type GeneratedFeature,
} from "../../scripts/lib/generated-feature.ts";
import { startBuildServer } from "./support/service-worker-builds.ts";
/**
* 2026-11-07. One feature in a real browser: its protected route through the
* local demo sign-in, its list read through the production codec, mapper and
* query cache, its form, and its save through the production command path
* with the idempotency key. These ran on the template's reference sample
* until it was deleted; now they run on the feature `create:feature` writes
* (`--with-create --keyed`), built into a copy of the repository
* (scripts/lib/generated-feature.ts). The API answers are the paired backend's
* Envelope, written out as in the generated feature's own tests.
*/
const META = Object.freeze({ requestId: "req-e2e", traceId: "0af7651916cd43dd8448eb211c80319c" });
const ITEM = Object.freeze({ id: "browser-order", name: "Browser order" });
const WCAG_TAGS = [...WCAG_AXE_TAGS];
let builds: FixtureBuilds<"a"> | undefined;
let server: Awaited<ReturnType<typeof startBuildServer>> | undefined;
let feature: GeneratedFeature;
test.beforeAll(async () => {
test.setTimeout(300_000);
builds = await prepareFixtureBuilds("generated-feature", [
{ name: "a", edit: addGeneratedFeature },
]);
feature = generatedFeature(builds.root);
server = await startBuildServer({ a: builds.dist.a, b: builds.dist.a });
});
test.afterAll(async () => {
await server?.close();
await removeFixtureBuilds(builds);
});
const words = () => feature.messages["ko-KR"];
const word = (key: string) => {
const value = words()[key];
if (value === undefined) throw new Error(`the generated catalog has no ${key}`);
return value;
};
function envelope(data: unknown) {
return { success: true, data, meta: META };
}
/**
* 1112/03-09. The paired backend's failure Envelope: code, category and
* retryable as its OperationalError row gives them
* (clean-architecture-backend-template src/shared-contract/.../OperationalError.java:
* RATE_LIMIT_EXCEEDED is RATE_LIMIT, 429, retryable; INTERNAL_ERROR is
* INTERNAL, 500, not retryable).
*/
function failure(code: string, category: string, retryable: boolean) {
return {
success: false,
error: { code, category, message: "backend message", retryable },
meta: META,
};
}
/** Answers the list read and, by id, the item read. */
async function answerReads(page: Page, list: readonly unknown[] = [ITEM]) {
const collection = new URL(feature.api).pathname;
await page.route(
(url) => url.origin === new URL(feature.api).origin && url.pathname.startsWith(collection),
async (route) => {
const request = route.request();
if (request.method() !== "GET") return route.fallback();
const { pathname } = new URL(request.url());
return pathname === collection
? route.fulfill({ json: envelope(list) })
: route.fulfill({ json: envelope({ ...ITEM, id: pathname.slice(collection.length + 1) }) });
},
);
}
type CreateCall = Readonly<{ name: unknown; idempotencyKey: string | null }>;
/** Answers each create with the next responder and records what was sent. */
async function answerCreates(
page: Page,
responders: readonly ((route: Route) => Promise<void>)[],
): Promise<CreateCall[]> {
const calls: CreateCall[] = [];
await page.route(feature.api, async (route) => {
const request = route.request();
if (request.method() !== "POST") return route.fallback();
calls.push({
name: (request.postDataJSON() as { name?: unknown }).name,
idempotencyKey: await request.headerValue("idempotency-key"),
});
const respond = responders[calls.length - 1];
if (!respond) throw new Error(`unexpected create call ${calls.length}`);
await respond(route);
});
return calls;
}
const created = (route: Route) =>
route.fulfill({
status: 201,
headers: { Location: `${feature.api}/${ITEM.id}` },
json: envelope(ITEM),
});
async function signInAt(page: Page, path: string, heading: string) {
if (!server) throw new Error("The generated feature's build is not served.");
await page.goto(`${server.origin}${path}`);
await expect(page.getByRole("heading", { level: 1 })).toHaveText(
KO_MESSAGES["route.auth.required.title"],
);
await page.getByRole("button", { name: KO_MESSAGES["action.signIn"] }).click();
await expect(page.getByRole("heading", { level: 1 })).toHaveText(heading);
}
const openForm = (page: Page) => signInAt(page, routePath(feature.create), word(generatedMessageKey("form.title")));
const nameField = (page: Page) =>
page.getByRole("textbox", { name: new RegExp(word(generatedMessageKey("form.name")), "u") });
const saveButton = (page: Page) => page.getByRole("button", { name: word(generatedMessageKey("form.save")) });
async function expectNoBlockingViolations(page: Page) {
const results = await new AxeBuilder({ page }).withTags(WCAG_TAGS).analyze();
expect(
results.violations.filter((violation) =>
["critical", "serious"].includes(violation.impact ?? ""),
),
).toEqual([]);
}
/**
* 1103/08-02. Saves from the keyboard and checks where focus lands: in the
* status above the form, one Tab away from its first action, not on the body
* after the page turned the save button busy.
*/
async function saveFromKeyboard(page: Page, firstAction: string) {
await nameField(page).fill(ITEM.name);
await saveButton(page).focus();
await page.keyboard.press("Enter");
await expect(page.locator(".page-template__feedback")).toBeFocused();
await page.keyboard.press("Tab");
await expect(page.getByRole("button", { name: firstAction })).toBeFocused();
}
test.describe("the route", () => {
test("opens the protected list through the local demo sign-in", async ({ page }) => {
await answerReads(page);
await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title")));
// The closed menu drawer holds a second copy of the status (08-01).
await expect(
page.getByRole("banner").getByText(KO_MESSAGES["shell.session.authenticated"]),
).toBeVisible();
// The answered row went through the production codec, mapper and query cache.
await expect(page.getByRole("link", { name: ITEM.name })).toBeVisible();
});
// 08-04. Feature screens take their words from the catalog.
test("draws its screens without Korean copy in en-US", async ({ page }) => {
await answerReads(page);
await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title")));
await page.getByRole("combobox", { name: "언어" }).first().selectOption("en-US");
const main = page.getByRole("main");
const english = feature.messages["en-US"];
await expect(main.getByRole("heading", { level: 1 })).toHaveText(english[generatedMessageKey("list.title")]!);
await expect(main).not.toContainText(/[가-힣]/u);
await main.getByRole("link", { name: english[generatedMessageKey("list.create")]! }).click();
await expect(main.getByRole("button", { name: english[generatedMessageKey("form.save")]! })).toBeVisible();
await expect(main).not.toContainText(/[가-힣]/u);
});
});
test.describe("the form", () => {
test("focuses the first invalid field when a save fails validation", async ({ page }) => {
await openForm(page);
await saveButton(page).click();
await expect(nameField(page)).toBeFocused();
await expect(nameField(page)).toHaveAttribute("aria-invalid", "true");
await expect(page.getByRole("alert")).toContainText(KO_MESSAGES["form.errorSummary"]);
});
test("asks before leaving unsaved input and stays when writing continues", async ({ page }) => {
await openForm(page);
await nameField(page).fill("Unsaved order");
await page
.getByRole("navigation", { name: KO_MESSAGES["template.breadcrumb"] })
.getByRole("link", { name: word(generatedMessageKey("list.title")) })
.click();
const dialog = page.getByRole("dialog", { name: KO_MESSAGES["form.unsaved.title"] });
await expect(dialog).toBeVisible();
await dialog.getByRole("button", { name: KO_MESSAGES["action.continueEditing"] }).click();
await expect(dialog).toBeHidden();
await expect(nameField(page)).toHaveValue("Unsaved order");
expect(new URL(page.url()).pathname).toBe(routePath(feature.create));
});
test("keeps the form template within a 320px viewport", async ({ page }) => {
await page.setViewportSize({ width: 320, height: 720 });
await openForm(page);
const viewport = await page.evaluate(() => ({
clientWidth: document.documentElement.clientWidth,
scrollWidth: document.documentElement.scrollWidth,
}));
expect(viewport.scrollWidth).toBeLessThanOrEqual(viewport.clientWidth);
});
// round9 confirm review. The page always hands FormSaveFeedback to the
// template's feedback area; with nothing to say it takes no row, so the
// heading and the fields stay one gap apart.
test("leaves no room for a save feedback area with nothing to say", async ({ page }) => {
await openForm(page);
const spacing = await page.evaluate(() => {
const box = (selector: string) => document.querySelector(selector)?.getBoundingClientRect();
const heading = box(".page-template__heading");
const layout = box(".page-template__layout");
const template = document.querySelector(".page-template");
return heading && layout && template
? { between: layout.top - heading.bottom, rowGap: parseFloat(getComputedStyle(template).rowGap) }
: null;
});
expect(spacing).not.toBeNull();
expect(spacing?.between).toBeCloseTo(spacing?.rowGap ?? 0, 0);
});
});
test.describe("the save", () => {
test("saves through the production command path with an idempotency key", async ({ page }) => {
await answerReads(page);
await openForm(page);
const calls = await answerCreates(page, [created]);
await nameField(page).fill(` ${ITEM.name} `);
await saveButton(page).click();
await expect(page.getByRole("heading", { level: 1 })).toHaveText(ITEM.name);
expect(calls).toEqual([{ name: ITEM.name, idempotencyKey: expect.any(String) }]);
});
test.describe("after a rate-limited save", () => {
// Chromium and WebKit log a 4xx fetch response to the console, and the
// client cancels the 429 body unread, which Chromium reports as aborted.
test.use({
allowedBrowserFailure:
/^console:error:.*status of 429|^requestfailed:POST:\/[^:]*:net::ERR_ABORTED$/u,
});
const rateLimited = (route: Route) =>
route.fulfill({
status: 429,
headers: { "retry-after": "1" },
json: failure("RATE_LIMIT_EXCEEDED", "RATE_LIMIT", true),
});
test("keeps the input and saves on retry", async ({ page }) => {
await answerReads(page);
await openForm(page);
const calls = await answerCreates(page, [rateLimited, created]);
await nameField(page).fill(ITEM.name);
await saveButton(page).click();
await expect(page.getByText(KO_MESSAGES["error.rate_limited"])).toBeVisible();
await expect(nameField(page)).toHaveValue(ITEM.name);
await page.getByRole("button", { name: KO_MESSAGES["action.retry"] }).click();
await expect(page.getByRole("heading", { level: 1 })).toHaveText(ITEM.name);
expect(calls.map((call) => call.name)).toEqual([ITEM.name, ITEM.name]);
});
test("keeps keyboard focus in the failure status", async ({ page }) => {
await openForm(page);
await answerCreates(page, [rateLimited]);
await saveFromKeyboard(page, KO_MESSAGES["action.retry"]);
});
});
test.describe("after a save whose result is unknown", () => {
// The browsers log the 500 response to the console.
test.use({ allowedBrowserFailure: /^console:error:.*status of 500/u });
const lost = (route: Route) =>
route.fulfill({
status: 500,
headers: {
"x-correlation-id": "corr-save-500",
"access-control-expose-headers": "x-correlation-id",
},
json: failure("INTERNAL_ERROR", "INTERNAL", false),
});
// 0929/08-04. The case a user most wants to report shows the id support
// can find in the server logs.
test("shows the result as unknown with the request id support can find", async ({ page }) => {
await openForm(page);
await answerCreates(page, [lost]);
await nameField(page).fill(ITEM.name);
await saveButton(page).click();
await expect(page.getByText(KO_MESSAGES["async.mutationEffectUnknown"])).toBeVisible();
await expect(page.getByText(/^지원 참조: /u)).toBeVisible();
});
test("keeps keyboard focus in the unknown-result status", async ({ page }) => {
await openForm(page);
await answerCreates(page, [lost]);
await saveFromKeyboard(page, KO_MESSAGES["action.confirmMutationApplied"]);
});
test("resends with the same key from the keyboard and opens the item", async ({ page }) => {
await answerReads(page);
await openForm(page);
const calls = await answerCreates(page, [lost, created]);
await saveFromKeyboard(page, KO_MESSAGES["action.confirmMutationApplied"]);
await page.keyboard.press("Tab");
await expect(
page.getByRole("button", { name: KO_MESSAGES["action.resendMutation"] }),
).toBeFocused();
await page.keyboard.press("Enter");
await expect(page.getByRole("heading", { level: 1 })).toHaveText(ITEM.name);
expect(calls).toHaveLength(2);
expect(calls[1]?.idempotencyKey).toBe(calls[0]?.idempotencyKey);
});
// 1105/08-02. Confirming an unknown create opens the list, which shows
// whether the item was saved.
test("opens the list after the user confirms the save from the keyboard", async ({ page }) => {
await answerReads(page);
await openForm(page);
const calls = await answerCreates(page, [lost]);
await saveFromKeyboard(page, KO_MESSAGES["action.confirmMutationApplied"]);
await page.keyboard.press("Enter");
await expect(page.getByRole("heading", { level: 1 })).toHaveText(word(generatedMessageKey("list.title")));
await expect(page.getByRole("link", { name: ITEM.name })).toBeVisible();
expect(calls).toHaveLength(1);
});
});
});
// 08-05. The protected screens are scanned signed in and in each state they
// can show. The state must be on screen before axe runs.
test.describe("accessibility", () => {
for (const [state, list, visible] of [
["success", [ITEM], ITEM.name],
["empty", [], KO_MESSAGES["async.empty"]],
// A 200 that breaks the response schema: a 5xx would also log a console
// error, which the strict fixture rejects on its own.
["error", [{ wrong: true }], KO_MESSAGES["error.schema_mismatch"]],
] as const) {
test(`@a11y list ${state} state has no blocking violations`, async ({ page }) => {
await answerReads(page, list);
await signInAt(page, routePath(feature.list), word(generatedMessageKey("list.title")));
await expect(page.getByRole("main")).toContainText(visible);
await expectNoBlockingViolations(page);
});
}
test("@a11y detail has no blocking violations", async ({ page }) => {
await answerReads(page);
await signInAt(page, routePath(feature.detail, ITEM.id), ITEM.name);
await expectNoBlockingViolations(page);
});
test("@a11y form with submit errors has no blocking violations", async ({ page }) => {
await openForm(page);
await saveButton(page).click();
await expect(page.getByRole("alert")).toContainText(KO_MESSAGES["form.errorSummary"]);
await expectNoBlockingViolations(page);
});
});