diff --git a/docs/design/343-frontend-test-infra/README.md b/docs/design/343-frontend-test-infra/README.md new file mode 100644 index 0000000..b69bb5b --- /dev/null +++ b/docs/design/343-frontend-test-infra/README.md @@ -0,0 +1,117 @@ +# 설계서: RTL/Jest 인프라 + next/image + ARIA Tabs (#343) + +> **상태**: Approved +> **작성**: [AI] Architect · **최종수정**: 2026-06-15 +> **추적성** — Redmine: #343 · 부모: #281 (현행화 frontend-review-memo, 09-Done) +> · 구현 파일: `frontend/package.json`, `frontend/jest.config.ts` (신규), `frontend/jest.setup.ts` (신규), `frontend/next.config.ts`, `frontend/__tests__/*` (신규), `frontend/src/components/MyReviewsList.tsx`, `frontend/src/components/ReviewSection.tsx` +> · 테스트: 본 이슈가 테스트 인프라 자체를 도입 + +## 1. 목적 (Why) + +본 프로젝트는 지금까지 자동화된 단위 테스트가 0건. 누적된 "후속 테스트" 항목이 12+개(StatsService/CacheService/SearchService/Stars/HangulSimilarity 등)이며, 그동안 분리된 후속 이슈를 처리할 인프라가 없어 모두 보류 상태. 본 이슈에서 Jest + RTL 인프라 도입 + next/image 적용 + ARIA Tabs 보강. + +## 2. 범위 (Scope) + +- **포함** + - Jest 30 + `next/jest` 자동 설정 + `@testing-library/react` + `@testing-library/jest-dom`. + - `jest.config.ts`, `jest.setup.ts`, `package.json scripts: test, test:watch`. + - 샘플 테스트 3개 — 가장 안전한 순수 함수/단순 컴포넌트로 인프라 검증: + - `Stars` 컴포넌트 렌더 + 별점 표시 + - 기존 `HangulSimilarity` (#348) — 자모/유사도 + - `BotDetector` (#337) — 봇 UA 패턴 + - `next.config.ts` `images.remotePatterns`에 Google avatar 도메인(`lh3.googleusercontent.com`) + YouTube thumbnail(`i.ytimg.com`). + - `ReviewSection`/`MyReviewsList`의 `` 일부를 `next/image` 또는 명시적 eslint-disable로 정리. + - `MyReviewsList` 탭에 WAI-ARIA Tabs 패턴(role=tablist/tab/aria-selected/aria-controls). +- **제외 (후속)** + - 백엔드 JUnit 테스트 인프라 (별도 큰 작업). + - E2E (Playwright) 도입. + - CI 통합 (GitHub Actions 또는 OCI DevOps). + - 모든 컴포넌트 테스트 — 점진적으로 추가. + - 모든 `` → `next/image` 전수 교체 — 점진적. + +## 3. 인수조건 + +- [ ] `npm test`가 단일 명령으로 동작 (0건 → 샘플 3개 통과). +- [ ] `npm run build`가 회귀 없이 통과. +- [ ] `next.config.ts`에 `remotePatterns` 설정. +- [ ] `ReviewSection`의 user_avatar_url ``에 `next/image` 또는 eslint-disable 주석. +- [ ] `MyReviewsList` 탭이 `role="tablist"`/`role="tab"`/`aria-selected`/`aria-controls`/`tabIndex` 설정. + +## 4. 컨텍스트 & 제약 + +- Next.js 16.1.6 + Turbopack. +- `next/jest`는 SWC/Babel 자동 통합. Turbopack 빌드와는 분리(테스트만 Jest 별도). +- Pretendard/Geist 폰트는 `next/font/local` 사용 → 테스트에선 mock 불필요. +- 패널 분리(#329)로 admin 영역은 단위 테스트 도입 더 쉬워짐. + +## 5. 아키텍처 개요 + +``` +frontend/ +├── package.json +│ └── scripts: test, test:watch +├── jest.config.ts (next/jest createNextJestConfig 사용) +├── jest.setup.ts (@testing-library/jest-dom 확장 matchers) +├── __tests__/ +│ ├── Stars.test.tsx +│ ├── HangulSimilarity.test.ts (자체 구현은 backend Java, TS 포팅은 미적용 → 다른 순수 함수로 대체) +│ └── BotDetector.test.ts (마찬가지 — backend → TS 동등 포팅 불가) +└── (대안) 프론트 측 순수 함수: + ├── lib/cuisine-icons.ts 의 getPhosphorCuisineIcon + ├── components/Stars 의 0.5 단위 렌더 + └── i18n/config.ts 의 isLocale/detectBrowserLocale +``` + +→ 백엔드 Java 코드는 TS 테스트로 검증 불가. 프론트 측 순수 함수 3개로 대체: +- `Stars` 렌더 (RTL component test) +- `i18n/config.ts` `isLocale` (pure) +- `i18n/config.ts` `detectBrowserLocale` (navigator mock) + +## 6. 데이터 모델 + +`__tests__/*.test.{tsx,ts}` — Jest 표준 컨벤션. + +## 7. 함수 명세 + +| 단위 | 책임 | 비고 | +|------|------|------| +| `jest.config.ts` | `createJestConfig(customConfig)` + moduleNameMapper `@/*` | next/jest | +| `jest.setup.ts` | `import "@testing-library/jest-dom"` | 확장 matchers | +| `Stars.test.tsx` | 별점 0/2.5/5 렌더, aria-label 확인 | RTL | +| `i18n/config.test.ts` | isLocale/detectBrowserLocale | navigator mock | +| `MyReviewsList` Tabs 패치 | tablist/tab/aria-selected | role + aria | +| `ReviewSection` img → eslint-disable | 최소 변경 | next/image는 후속 | + +## 8. 흐름 + +1. `npm i -D jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event @types/jest`. +2. `jest.config.ts` + `jest.setup.ts` 작성. +3. `package.json`에 `"test": "jest"` + `"test:watch": "jest --watch"` 추가. +4. `__tests__/`에 3개 샘플 테스트. +5. `next.config.ts`에 `remotePatterns` 추가. +6. `MyReviewsList` Tabs ARIA 보강. +7. `ReviewSection`의 `` 라인에 `// eslint-disable-next-line @next/next/no-img-element` (next/image 전환은 후속). +8. `npm test` 통과 → `npm run build` 통과. + +## 9. 엣지케이스 + +- **Turbopack vs Jest**: 무관 (테스트는 별도 SWC 컴파일). +- **CSS modules / globals.css import**: jest.config.ts의 moduleNameMapper로 `\\.(css|scss)$` → `identity-obj-proxy` 대신 next/jest가 자동 처리. +- **Next.js Server Components**: 본 프로젝트는 모두 `"use client"` 컴포넌트라 RTL이 통상 동작. + +## 10. 테스트 + +자기 자신 — `npm test`가 통과해야 본 이슈 완료. + +## 11. 리스크 & 대안 + +- **선택**: `next/jest` + RTL. Next.js 공식 권장. +- **대안 A**: Vitest — 더 빠르지만 Next.js 공식 가이드 부재, 본 프로젝트 규모에서 차이 작음. +- **대안 B**: Playwright Component Testing — 더 무겁고 E2E 통합 안 됨. +- **트레이드오프**: Jest 30 + RTL은 React 19에 호환. 의존성 부담은 dev-only. + +## 12. 미해결 질문 + +- CI(테스트 자동 실행) — 본 이슈 범위 밖. OCI DevOps Build Pipeline은 ARM64 미지원 → GitHub Actions 또는 Gitea Actions 후속. +- 백엔드 JUnit 테스트 인프라 — 별도 큰 이슈. +- E2E (Playwright) — 별도.