문제: 라우터·chunk 복구·render 경계·앱 셸·런타임 트리 테스트가 스타터
화면(`/`의 h1, 홈의 "플랫폼 구성 보기" 링크, /examples/ui·states)을
대상으로 쓴다. 문서는 스타터 화면을 "페이지 단위로 교체 가능"하다고 하는데,
제품이 화면을 바꾸면 스타터와 무관한 플랫폼 테스트가 깨지고 동기화 때마다
같은 파일이 충돌한다(두 제품 기록).
방법: tests/helpers/fixture-feature.tsx에 테스트 전용 public 페이지 4개를
더했다. 메뉴에 나오는 지연 로드 페이지 2개(제목 h1, 런타임 릴리스 표시),
chunk 로드 실패 페이지, render 결함 페이지다. 플랫폼 테스트는 이미 쓰던
방식대로 생성 인덱스를 mock해 이 기능을 설치하고 그 페이지를 쓴다.
스타터 화면 자체를 검사하던 것(홈 시작 링크, 홈·플랫폼 구성의 릴리스 로딩
실패, 인증 예제의 복귀 URL, 상태 갤러리 제목 구조, 플랫폼 구성 화면)은
starter-pages.test.tsx와 starter-platform-overview-page.test.tsx로
모았다. 제품은 스타터 화면과 함께 starter-* 파일을 지우면 된다.
fixture는 design-system 배럴 대신 page-header.tsx를 직접 import한다.
배럴이 설치 카탈로그를 거쳐 mock된 생성 인덱스를 다시 불러 mock 팩토리가
자기 자신을 기다린다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
화면을 바꾸면 검사는 여전히 깨지거나 사라진다.
위험: 플랫폼 경로(createRegisteredRoutes의 platformChildren)를 지나는
화면 이동 테스트가 줄고 context 라우트 경로로 옮겨 갔다. `/`와 not-found는
여전히 플랫폼 경로로 돈다. ui-gallery-page는 이제 component 테스트에서
렌더되지 않는다(e2e·visual이 본다). sibling chunk 초기화 테스트는
key={definition.routeId}를 지우면 여전히 실패한다(변이 확인).
검증: RED는 템플릿 복사본에서 home-page.tsx와 examples/*를 다른 화면으로
바꾸고 test:component를 돌렸다. 7파일 20개 실패(router 5, route-status 4,
platform-overview 7, app-shell·async-surface·chunk-recovery·
runtime-application 각 1). GREEN은 같은 조작에서 starter-* 2파일 12개만
실패하고, starter-*를 지우면 34파일 216개 전부 통과. worktree에서
tests/component 36파일 228개 통과, tsc -p tsconfig.test.json 통과, 바꾼
파일 eslint 통과.
문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로
썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서 <main>으로
튀고, POP이 아니면 맨 위로 스크롤하고, route.changed를 한 번 더 남겼다.
이미 보고 있는 화면의 링크를 눌러도(React Router가 REPLACE로 바꿈)
navigationType만 바뀌어 같은 일이 났다. 템플릿은 필터를 URL에 두라고
권하므로 첫 목록 화면에서 바로 드러난다(WCAG 3.2.2).
고른 방법: 이동 판단을 route ID 또는 pathname 변경으로 좁혔다(리뷰 5.1
(B)). 포커스·스크롤·진단은 useEffectEvent로 옮겨 navigationType을 읽기만
하고 트리거로 쓰지 않는다. 검색값 변경에 맨 위가 필요한 화면(페이지
번호)은 그 화면이 직접 스크롤한다. routing 문서 6.3절에 규칙을 적었다.
버린 대안: (C) 라우트 계약에 searchChangeIsNavigation 선언 — 그런
라우트가 템플릿에 없고 생성기·문서까지 바뀐다. 필요해지면 (B) 위에
더할 수 있다. navigationType을 ref로 들고 있기 — 렌더 중 ref 쓰기라
React 19의 useEffectEvent보다 의도가 덜 드러난다.
위험·한계: 지금 검색값 변경을 이동으로 세던 대시보드가 있다면 수치가
준다. 실제 브라우저의 스크롤 유지는 jsdom이 스크롤을 건너뛰어 정적
확인만 했다. 테스트용 fixture 페이지에 URL에 묶은 select를 더했다.
검증:
- RED: router.test.tsx 새 테스트 2건이 수정 전 실패. 포커스가
<main id="main-content">에 있었고 route.changed가 필터 테스트 1→3,
링크 테스트 1→2로 늘었다.
- GREEN: router.test.tsx 11/11, tests/component 34 files 213 tests 통과.
tsc(app, test) 통과, eslint(바꾼 파일) 통과,
verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm 실행을 요구해 이 worktree에서 미실행.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-02
문제
lazy route 화면을 findBy*·waitFor 기본값(1초)으로 기다리는 테스트가 1코어
부하에서 코드와 무관하게 떨어진다. 수정 전 재현에서
runtime-application.test.tsx:65 "Unable to find role=heading name=Clean
Architecture Frontend"와 reference-production-vertical.test.tsx:103
"Unable to find role=button name=로그인 시작"이 났다. 두 DOM 모두
route-loading(aria-busy) 상태였다. 지난 리뷰는 router.test.tsx:244-250도
같은 이유로 실패했다고 적었다. React 19는 Suspense를 풀 때마다 실제 300ms
타이머(FALLBACK_THROTTLE_MS)를 기다린다. context route 표와 lazy 페이지를
거치는 화면은 렌더링 전에 1초 중 600ms를 쓴다. 이 사정을 아는 파일만
호출마다 { timeout: 5000 }을 붙이거나(7개 파일 13곳) 파일 단위로
configure를 바꿨다(reference-page). 새 테스트 작성자는 이 규칙을 알 방법이
없다.
고른 방법
tests/setup.ts에서 configure({ asyncUtilTimeout: 5_000 })를 한 번 정하고,
같은 값을 반복하던 호출·파일 단위 override를 지웠다. findBy*·waitFor는
DOM 변화가 오면 바로 끝나므로 기한은 멈춤을 알리는 용도뿐이다. 10초 테스트
제한의 절반이라 진짜 멈춤은 여전히 Testing Library의 DOM 덤프와 함께
실패한다. 기한을 늘리는 방식이라 고른 이유를 setup에 주석으로 남겼다.
버린 대안
- 가짜 시계: Testing Library는 Jest의 가짜 타이머만 알아본다
(jestFakeTimersAreEnabled가 jest 전역을 본다). Vitest 가짜 타이머에서
waitFor는 자기 타이머가 멈춰 끝나지 않는다. MSW와 user-event도 실제
시계로 돈다.
- route chunk를 테스트에서 미리 import하기: chunk를 받아도 React의 300ms
reveal 타이머와 렌더링 비용은 그대로 기한 안에 남는다. 테스트가 route
모듈 목록을 따로 알아야 한다.
- 실패한 파일에만 timeout 붙이기: 지금 상태와 같다. 다음 lazy 화면
테스트에서 같은 실패가 반복된다.
위험·한계
- 기다리다 실패하는 테스트는 실패까지 1초가 아니라 5초 걸린다. 부재를
findBy·waitFor의 실패로 확인하는 테스트는 없다(grep으로 확인).
- 가짜 타이머를 쓰는 테스트의 waitFor는 이 값과 무관하다(가짜 시간).
검증
- RED(수정 전, taskset -c 0 + 같은 코어의 바쁜 이웃 1개, --maxWorkers=4,
component·features·integration·platform/cardinality): 3회 중 1회 위 두
테스트 실패.
- GREEN(같은 조건): 대상 6개 파일 6회, 넓은 묶음 5회 모두 통과. 바쁜
이웃 2개로 3회 돌렸을 때도 이 커밋이 다루는 테스트는 모두 통과했다.
넓은 묶음 한 번의 시간은 RED 91~111s(실패가 몰린 209s 회차 제외)
-> GREEN 86~88s다.
- 기본 코어: tests/unit·component·integration 212파일 2,734개, features·
platform·architecture·contract·runtime-schema 60파일 403개 통과.
tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과.
Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md
The bundle applied the selection at runtime while Node build scripts and the
context router ignored it, and a typo only failed in the browser. The generator
now imports only the selected features and rejects unknown ids (D-9); declared
ids stay in the index for NOT_INSTALLED reporting. Default build modules are
unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Six platform tests imported or named the removable reference feature, so
FE-GATE-020 failed on typecheck, unit, coverage, home smoke and residue.
Router surfaces now install tests/helpers/fixture-feature.tsx by mocking
the generated indexes; the rest use neutral names or read the installed
modules. test:sample-removal passes 13/13.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
D-16. The platform `none` codec strips unknown keys instead of rejecting
them, so `/?utm_source=x` or an OAuth callback parameter no longer renders
"invalid address". The canonical redirect keeps the query of a route whose
search codec is `none`, so the URL itself is not rewritten.
router.test.tsx used `/examples/ui?unexpected=1` as its invalid-address
case, which encoded the old behavior; it now uses the reference list with
`?limit=invalid`. New router case (RED before the change) checks the page
renders and the URL keeps `?utm_source=mail`; lane gates pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
LocaleProvider and ThemeProvider lived inside AppRouter, below the
server-state scope fence (and below QueryClientProvider keyed by
generation). A session change (FENCED -> READY) unmounted and remounted
them, so their live state was thrown away and re-read from storage. The
browser router was created in useMemo and never disposed, so every
remount (and StrictMode's double useMemo) left a popstate listener behind.
- New presentation/providers/preference-providers.tsx: persisted
LocaleProvider + ThemeProvider (the wiring T45 added to AppRouter).
- bootstrap/runtime-application.tsx: ApplicationProvider >
PreferenceProviders > ServerStateGenerationProvider > AppRouter, so the
fence only remounts session-scoped UI.
- AppRouter no longer mounts Locale/Theme. It creates the router in the
effect that disposes it: a disposed router never listens to history
again, so useMemo + cleanup would break back/forward under StrictMode's
replayed mount.
- Tests that mount AppRouter directly now wrap it in PreferenceProviders
(router, chunk-recovery-boundary, app-shell, product-feature-switch,
locale-platform, reference-feature reference-page).
Verified: RED "keeps locale state across a session scope fence and
disposes routers" (RuntimeApplication, demo sign-in, storage cleared after
choosing en-US) came back in Korean before and passes after; with the
providers hoisted but no dispose it fails on popstate listeners (4 added,
0 removed). check:architecture, check:types:app, check:types:test, lint,
test:component, test:reference-feature pass; test:unit passes except the
pre-existing removal-fixture test (needs generated artifacts/ files absent
from a fresh worktree).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RouteLifecycle lived inside the route content, which ProtectedRoute,
InvalidRouteSurface and DisabledFeatureSurface never render. On those
screens document.title kept the previous page's title, focus stayed on the
link the user left (screen readers got no page-change cue), and no
route.changed diagnostic was recorded.
RegisteredRoute is now a thin wrapper that renders RouteLifecycle first and
the former body (renamed RouteSurface) after it, so every branch gets title,
main focus and telemetry, and the lifecycle effect still runs before the
page heading's focus effect.
Verified: RED "runs the route lifecycle on the {authentication-required,
invalid-route, disabled-feature} surface" (focus left on a nav link, then a
history navigation) all failed before with the home title still set and
pass after. check:architecture, check:types:app, check:types:test, lint,
test:component, test:reference-feature pass; test:unit passes except the
pre-existing removal-fixture test (needs generated artifacts/ files absent
from a fresh worktree).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RouteLifecycle ran title, main focus, scroll-to-top and reportRouteChanged
in one effect that depended on message/resolve, which the LocaleProvider
recreates on every locale change. Changing the language therefore moved
focus off the language select (main, then the h1), scrolled to the top
and reported a route change, against the routing doc's "locale change
re-renders the title and copy only" contract.
The title now has its own effect (locale-dependent). Focus, scroll and
telemetry run on pathname/search only; location.key is dropped, so a
hash-only move (skip link, error summary #field) no longer re-runs them.
Verified: RED "changes only the title and copy when the locale changes"
failed before (focus moved off the locale select) and passes after; it
also checks document.title and the route.changed count. check:architecture,
check:types:app, check:types:test, lint, test:component pass; test:unit
passes except the pre-existing removal-fixture test (needs generated
artifacts/ files absent from a fresh worktree).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>