chore: Playwright E2E 테스트 환경 구축

[kanghaeun]

개요

E2E 테스트 도구로 Playwright를 도입하여 주요 사용자 플로우를 자동으로 검증할 수 있는 테스트 환경을 구축한다.

핵심 방침

• PR CI에서 도는 E2E는 결정적 이어야 한다 — 같은 코드면 항상 같은 결과
• 따라서 API는 실서버 대신 Playwright 내장 page.route()로 목킹한다 (추가 의존성 없음)
  • 실서버(dev API) 기반 테스트는 데이터 상태·서버 가용성에 따라 결과가 흔들려 CI 신뢰도를 해침
  • MSW 도입은 테스트가 늘어나 핸들러 중복이 부담될 때 별도 이슈로 재논의
• 실서버 연동 검증(스모크 테스트)은 본 이슈 범위에서 제외, 후속 이슈로 진행

작업 상세 내용

설치 및 기본 설정

• @playwright/test 설치 — pnpm --filter piki-web add -D @playwright/test
• 브라우저 바이너리 설치 — pnpm exec playwright install
• apps/web/playwright.config.ts 작성
  • baseURL: http://localhost:3000
  • webServer 로컬/CI 분리
    • 로컬: pnpm dev + reuseExistingServer: !process.env.CI (띄워둔 dev 서버 재사용)
    • CI: next build && next start (프로덕션 빌드 기준 — 빠르고 안정적)
  • 모바일 뷰포트 디바이스 에뮬레이션 (서비스가 모바일 중심 — 예: devices['iPhone 14'])
  • 테스트 디렉토리: apps/web/e2e

스크립트 및 환경 구성

• apps/web/package.json에 테스트 스크립트 추가
  • test:e2e — 전체 테스트 실행
  • test:e2e:ui — UI 모드 실행 (디버깅용)
• .gitignore에 산출물 추가 — test-results/, playwright-report/, playwright/.auth/
• 테스트용 환경 변수 구성 (NEXT_PUBLIC_API_URL 등 목킹 기준으로 정리, .env.test 필요 시 분리)

API 목킹

• page.route() 기반 목킹 패턴 정립 (팀 응답 규약 { status, data, detail, code } 형식 준수)
• 공통 목 응답 헬퍼/픽스처 작성 — 기존 src/mocks/ 목 데이터 재활용

인증 상태 처리

• 게스트 로그인 기준 storageState 생성 (global setup) 후 테스트 간 재사용
• 멤버(소셜 로그인) 시나리오는 후속 이슈로 분리

샘플 테스트 작성

• 환경 정상 동작 확인용 기본 테스트 작성
  • 홈 페이지 진입 및 렌더링 확인
  • 토너먼트 준비 페이지 진입 플로우

CI 연동

• E2E 전용 GitHub Actions 잡 추가 — 기존 lint/type/build 잡과 분리 (기존 필수 체크를 막지 않도록)
• CI 환경 브라우저 설치 — pnpm exec playwright install --with-deps
• Playwright 브라우저 바이너리 캐싱 (~/.cache/ms-playwright)
• 실패 시 trace / 스크린샷 아티팩트 업로드 설정
• 도입 초기에는 required check로 걸지 않고 안정화 관찰 기간을 둠

참고 사항

• SSE, WebBridge 등 실시간 기능은 목킹이 까다로워 초기 E2E 범위에서 제외
• 핵심 플로우 테스트 케이스 작성은 환경 구축 완료 후 후속 이슈로 진행
• 실서버(dev API) 대상 스모크 테스트(nightly 등)는 필요성 확인 후 후속 이슈로 진행