테스트 환경 구축: apps/blog에 Jest 단위 테스트 + Playwright E2E 도입

[Malloc72P]

배경

현재 apps/blog(Next.js 16 + MDX)에는 단위 테스트도, E2E 테스트도 전혀 없습니다. 테스트 설정 파일·의존성도 없는 상태라, 리팩터링이나 기능 추가 시 회귀(regression)를 잡아줄 안전망이 없습니다.

단위 테스트는 Jest, E2E는 Playwright로 구성하는 것을 목표로 합니다. (이 이슈는 작업 등록용이며, 당장 구현하지는 않습니다.)

목표

• Jest 단위 테스트 환경 구축
• Playwright E2E 테스트 환경 구축
• 핵심 로직/주요 페이지에 대한 초기 테스트 작성
• (선택) CI에서 PR마다 자동 실행

---

1. 단위 테스트 (Jest)

• Next.js 공식 권장 방식인 next/jest로 설정(SWC 변환 활용). tsconfig의 path alias(@libs/* 등)를 moduleNameMapper에 반영
• @testing-library/react, @testing-library/jest-dom, jest-environment-jsdom 도입
• 스크립트 추가: test, test:watch, test:coverage
• 우선순위 테스트 대상
  • 순수 로직(가치 가장 높음): src/libs/frontmatter.ts, src/libs/mapper.ts, src/libs/param-util.ts, src/libs/page-link-map.ts, src/libs/date-util/*
  • 컴포넌트 렌더링: post-card, tag-badge/series-badge/badge, divider, mdx-wrapper 등
• MDX/mdx-components 관련 렌더 테스트 전략 결정(필요 시 일부 mock)

2. E2E 테스트 (Playwright)

• @playwright/test 설치 + playwright.config.ts(webServer로 next dev/next start 자동 기동, baseURL 설정)
• 스크립트 추가: test:e2e, test:e2e:ui
• 시나리오(초기)
  • 메인 진입 시 헤더/푸터 렌더
  • 포스트 목록 → 상세 진입, 제목·작성일 노출 확인
  • 시리즈 페이지 / 태그 페이지 탐색
  • 모바일 사이드바·반응형 동작(최근 모바일 반응형 개선과 연계)
  • 존재하지 않는 경로(404)
• 실패 시 스크린샷/trace 아티팩트 저장 설정

3. 모노레포 / CI

• turbo.json에 test 태스크 등록(필요 시 test:e2e 분리)
• (선택) GitHub Actions에서 PR마다 unit + e2e 실행, Playwright 브라우저 캐시 적용

---

완료 기준 (AC)

• pnpm --filter blog test로 단위 테스트가 실행되고 통과
• pnpm --filter blog test:e2e로 E2E가 로컬에서 통과
• 핵심 libs 함수 단위 테스트 + 주요 사용자 흐름 1~2개 E2E가 존재
• README/문서에 테스트 실행 방법 안내 추가

참고

• 단위 테스트 작성 패턴은 최근 추가한 playground/jest-testing 예제와 frontend/jest-testing 포스트를 참고할 수 있습니다. 다만 그쪽은 순수 모듈용 babel 설정이고, 블로그는 Next.js + React + MDX 환경이라 next/jest(SWC) 기반으로 구성하는 것이 적합합니다.

🤖 Generated with Claude Code

[Malloc72P]

🧭 E2E 작업 재개용 핸드오프 (다른 머신에서 이어받기)

현재 상태

• ✅ 1단계 단위테스트 완료 — PR test(pipeline): Jest 도입 + 빌드 파이프라인 단위테스트 (#30 1단계) #80 머지(main 포함). next/jest(SWC) 환경 + 빌드 파이프라인 단위테스트 10 스위트 / 38건. getAllMdxFiles(fs)를 mock하고 파싱 로직을 순수 함수로 분리해 글 추가에 안 깨지는 구조.
• ⬜ 2단계 E2E(Playwright) — 이 코멘트의 계획대로 진행. 기준 브랜치는 main.

합의된 E2E 설계 (핵심: 콘텐츠가 바뀌어도 안 깨지게)

1. 풀페이지 스냅샷 금지. data-testid/역할(role) 기반 로케이터로 구조·동작을 단언(클래스 의존 X — 리스타일에 취약). 콘텐츠는 정확값이 아니라 패턴으로(/\d+개의 포스트/, 날짜 /\d{4}\. \d{2}\. \d{2}/, 카드 ≥ 1).
2. 2층 구조:
   • (a) 구조·동작 테스트(실제 페이지, 콘텐츠 불문) — 글이 추가돼도 안 깨짐.
   • (b) 읽기경험 정밀 테스트(전용 픽스처 포스트) — 테스트가 콘텐츠를 소유.
3. 픽스처 포스트는 draft 플래그로 목록/사이트맵/검색에서 숨기고, 라우트는 렌더되게 → E2E가 경로로 직접 방문. 프로덕션 오염 없음. (draft는 초안 관리에도 유용)
4. 결정성: playwright.config.ts의 webServer로 TZ="Atlantic/Reykjavik" next build && next start(권장) 자동 기동, baseURL 설정, 실패 시 trace/스크린샷 저장.
5. giscus 댓글: 외부 iframe이라 E2E에선 "위젯 컨테이너(giscus-widget) 존재"만 확인(네트워크/앱 설치 의존 X).

구현 체크리스트

• pnpm --filter blog add -D @playwright/test + pnpm --filter blog exec playwright install --with-deps chromium
• 스크립트: test:e2e(playwright test), test:e2e:ui(playwright test --ui)
• apps/blog/playwright.config.ts: webServer(위 명령, url: http://localhost:3000, reuseExistingServer: !process.env.CI), use.baseURL, trace: 'on-first-retry', screenshot: 'only-on-failure', projects = chromium + 모바일(예: Pixel 5 뷰포트)
• draft 플래그 구현:
  • src/libs/frontmatter.ts: FrontmatterInput/FrontmatterOutput에 draft?: boolean 추가, extractMetadata/parseFrontmatterMetadata(src/libs/api/mdx-utils.ts)에서 draft 파싱(/draft:\s*true/)
  • src/libs/api/find-posts.ts: draft 글 제외 (→ sitemap·검색인덱스는 findPosts 기반이라 자동 반영). 단, 직접 라우트 접근은 렌더되어야 함(페이지 컴포넌트는 그대로)
  • 단위테스트 추가: find-posts.test.ts에 draft 제외 케이스, mdx-utils.test.ts에 draft 파싱 케이스
• 픽스처 포스트: src/app/(main)/posts/frontend/__e2e-fixture/page.mdx (draft: true) — 고정 제목 + 코드블록(복사 버튼) + 이미지(alt) + 여러 ##/### 헤딩(TOC) + 본문. (postId는 폴더명과 일치)
• data-testid 부여(셀렉터 안정화): post-card, 시리즈 칩, toc, 댓글 래퍼, 복사 버튼, 모바일 사이드바 트리거 등
• E2E 시나리오:
  • 구조·동작: 랜딩 헤더/푸터 렌더, 카드 클릭→상세 이동, 시리즈 active 표시·칩 전환, 태그 페이지 진입, 존재하지 않는 경로 404, 모바일 사이드바 열림, 댓글 위젯 컨테이너 존재
  • 픽스처 정밀: /posts/frontend/__e2e-fixture에서 제목 1개·코드블록 복사 버튼 동작·TOC 항목·이미지·이전/다음 네비
• turbo.json에 test 태스크(필요 시 test:e2e 분리, cache/outputs 설정)
• (선택) GitHub Actions: PR마다 unit + e2e, Playwright 브라우저 캐시
• README/문서에 테스트 실행법 추가

다른 머신에서 셋업

git clone https://github.com/Malloc72P/Blog.git && cd Blog
git checkout main && git pull
pnpm install
pnpm --filter blog test          # 1단계 단위테스트 동작 확인(기준점)
# 이후 위 체크리스트대로 E2E 추가 → pnpm --filter blog test:e2e

• 새 브랜치 예: malloc72p/issue-30-e2e (base: main)
• PR 제목 예: test(e2e): Playwright E2E + draft 픽스처 (#30 2단계) / 본문에 Closes #30

주의

• 날짜는 패턴 매칭(정확값 X). 셀렉터는 data-testid 우선(CSS 클래스 의존 금지).
• 픽스처 draft가 단위테스트(find-posts 제외)와 빌드(사이트맵/검색 제외)에 함께 반영되는지 확인.
• webServer는 next build && next start 권장(정적 prerender 상태로 검증). 빠른 반복은 next dev도 가능.

[Malloc72P]

✅ 완료

• Jest 단위 테스트 환경 구축 + libs 테스트 다수 (test(e2e): Playwright E2E 환경 도입 및 시나리오 5종 추가 (#30 2단계) #114)
• Playwright E2E 환경 구축 + 시나리오 8종(홈/포스트/시리즈-태그/404/반응형/검색/테마) (test(e2e): Playwright E2E 환경 도입 및 시나리오 5종 추가 (#30 2단계) #114, feat(blog): 다크모드 도입 — 토큰 기반 테마 전환 (#90) #123)
• GitHub Actions CI로 PR마다 lint·타입체크·단위·E2E 자동 실행 (ci: PR마다 lint·타입체크·단위·E2E 자동 실행 (#30) + E2E 셀렉터 하드닝 #115)

pnpm --filter blog test, pnpm --filter blog test:e2e로 실행 가능. README에 실행 방법 문서화됨.