test(layouts): 모든 레이아웃의 skip link와 main 하나를 실행으로 검사한다 (1101/14.4)

문제: 라우터는 경로가 바뀔 때마다 `#main-content`로 focus를 옮긴다.
그래서 라우터가 붙이는 모든 레이아웃은 skip link와 `<main id="main-content">`
하나를 그려야 한다. ca16187이 context 레이아웃을 열면서 이 규칙을 타입 주석과
starter-experience.md, fixture로만 지켰다. 레이아웃에서 `<main>`을 빼도
실패하는 테스트가 없다(리뷰 README 14.4 09-03 첫 줄).

고른 방법: 등록된 레이아웃을 읽어 도는 component 테스트
`tests/component/layout-landmarks.test.tsx`.
- 대상: `AppShell`, 설치된 제품(`TEMPLATE_APP_MODULE.contexts`)의 각
  `loadLayout`, fixture 제품(`LAYOUT_PRODUCT_CONTEXT_MODULES`)의 각
  `loadLayout`. 제품이 `context-layout.tsx`를 추가하면 이 파일을 고치지 않아도
  검사 대상이 된다.
- 각 레이아웃을 메모리 라우터에 붙이고 자식 페이지(probe h1)를 그린다.
  확인: `main`/`role="main"`이 정확히 하나, 그 id가 `main-content`, 자식
  페이지가 그 안에 있음, `href="#main-content"` 링크가 있음.
- fixture의 offline 레이아웃은 청크가 오지 않도록 만든 것이라 id로 뺐다.

버린 대안:
- context-layouts.test.tsx에 넣기: 그 파일은 생성 인덱스를 fixture로 mock한다.
  설치된 제품의 레이아웃은 그 안에서 읽을 수 없고, 읽더라도 fixture 레지스트리
  아래라 제품 라우트를 가리키는 레이아웃(`routePath`)이 다른 이유로 깨진다.
- `AppRouter`로 레이아웃마다 URL을 열기: 레이아웃마다 파라미터 없는 경로를
  골라야 하고 설치된 제품과 fixture를 한 파일에서 돌릴 수 없다.

위험·한계:
- 레이아웃 단독 렌더라 페이지가 자기 `<main>`을 하나 더 그리는 경우는 이
  테스트가 못 잡는다. 라우터를 거친 확인은 context-layouts.test.tsx가 fixture로
  한다.
- skip link가 첫 focus 대상인지는 보지 않는다.
- 템플릿 자체에는 레이아웃을 선언한 context가 없어, 설치된 제품 쪽은 지금
  `AppShell`만 돈다.

검증:
- RED(변이): fixture 레이아웃의 `<main>`을 `<div>`로 바꾸면 4건 중 3건 실패
  ("expected to have a length of 1 but got +0"). AppShell skip link href를
  `#content`로 바꾸면 1건 실패("expected null not to be null"). 둘 다 되돌렸다.
- GREEN: 4건 통과(AppShell, context site, topics, studio).
- tsc test 통과. 새 파일 eslint 통과. verify-documentation-readiness
  PASS_SCOPED.
This commit is contained in:
DongHyeonka
2026-11-03 20:30:35 +09:00
parent d0414c85f9
commit 27f45233f9
2 changed files with 64 additions and 0 deletions
+2
View File
@@ -235,6 +235,8 @@ than `AppShell`, declares it. The router and the catalogs do not change.
exactly one `<main id="main-content" tabIndex={-1}>` around `<Outlet />`.
The router moves focus there on every route change. Layout routes are
siblings of `AppShell`, never inside it.
`tests/component/layout-landmarks.test.tsx` renders `AppShell` and the
layout of every installed context and fails one without them.
- **Failures.** A layout chunk a deploy removed gets the reload-once recovery
of a route chunk. Route and feature boundaries work as they do in
`AppShell`.
+62
View File
@@ -0,0 +1,62 @@
// @vitest-environment jsdom
import { render, screen } from "@testing-library/react";
import type { ComponentType } from "react";
import { createMemoryRouter, RouterProvider } from "react-router-dom";
import { describe, expect, it } from "vitest";
import { TEMPLATE_APP_MODULE } from "../../src/apps/template-app.ts";
import { AppShell } from "../../src/presentation/layouts/app-shell.tsx";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { SessionProvider } from "../../src/presentation/providers/session-provider.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
import { LAYOUT_PRODUCT_CONTEXT_MODULES } from "../helpers/fixture-layout-product.tsx";
/**
* 09-03 (1101/14.4). The router moves focus to `#main-content` on every route
* change, so every layout it mounts has to render a skip link to it and make
* it the one main landmark around the page. The layouts are read from the
* contexts of the installed product and of the fixture product, so a new
* `context-layout.tsx` is checked without being named here.
*/
const contexts = [
...TEMPLATE_APP_MODULE.contexts,
// The fixture's offline layout chunk never arrives, by design.
...LAYOUT_PRODUCT_CONTEXT_MODULES.filter((context) => context.id !== "offline"),
];
const LAYOUTS: readonly (readonly [string, ComponentType])[] = [
["AppShell", AppShell],
...(await Promise.all(
contexts.flatMap((context) => {
const loadLayout = context.route?.loadLayout;
return loadLayout
? [loadLayout().then((Layout) => [`context ${context.id}`, Layout] as const)]
: [];
}),
)),
];
describe("every layout the router mounts", () => {
it.each(LAYOUTS)("%s links its skip link to its one main landmark", async (_name, Layout) => {
const router = createMemoryRouter([
{ path: "/", element: <Layout />, children: [{ index: true, element: <h1>Probe page</h1> }] },
]);
render(
<ApplicationProvider application={createTestApplication()}>
<PreferenceProviders>
<SessionProvider>
<RouterProvider router={router} />
</SessionProvider>
</PreferenceProviders>
</ApplicationProvider>,
);
const page = await screen.findByRole("heading", { name: "Probe page", level: 1 });
const mains = document.querySelectorAll('main, [role="main"]');
expect(mains).toHaveLength(1);
expect(mains[0]).toHaveAttribute("id", "main-content");
expect(mains[0]).toContainElement(page);
expect(document.querySelector('a[href="#main-content"]')).not.toBeNull();
});
});