테스트
이 페이지는 주로 프론트엔드 테스트 스위트를 실행하는 how-to 문서입니다. 첫 섹션은 테스트 레이어를 정리하고, 나머지는 현재 구성에서 자주 나타나는 전제 조건, 명령, 통과 신호, 실패 양상에 집중합니다.
프론트엔드 리포지토리는 두 가지 테스트 레이어를 사용합니다.
src/아래의 단위 테스트와 작은 컴포넌트 중심 테스트용 Viteste2e/아래의 API, 플로우, UI, SSR 회귀 검사용 Playwright
소스 경로
| 경로 | 역할 |
|---|---|
lumie-frontend/package.json | 테스트 진입점 스크립트 |
lumie-frontend/vitest.config.ts | Vitest 환경, setup 파일, include/exclude glob |
lumie-frontend/vitest.setup.ts | @testing-library/jest-dom/vitest 로드 |
lumie-frontend/playwright.config.ts | Playwright 프로젝트, 재시도, reporter, UI 전용 webServer |
lumie-frontend/e2e/config/environments.ts | TEST_ENV 해석과 monolith base URL 매핑 |
lumie-frontend/e2e/config/global-setup.ts | CHECK_SERVICES=true일 때 선택적 백엔드 health probe |
lumie-frontend/e2e/ssr/auth.setup.ts | SSR 로그인 bootstrap과 필요한 credential env var |
Vitest 단위 테스트
vitest.config.ts는 다음과 같이 설정되어 있습니다.
- 테스트 환경으로
jsdom @testing-library/jest-dom/vitest를 불러오는vitest.setup.ts- include 패턴으로
src/**/*.{test,spec}.{ts,tsx} - 단위 테스트 실행에서
e2e/**제외
현재 단위 테스트 스위트는 공유 유틸리티와 파싱 경계에 집중하며, 다음 영역의 테스트를 포함합니다.
- 커스텀 도메인 해석 헬퍼
- API 프록시 라우트 로직
- search param 및 list param 헬퍼
- 세션 캐시 동작
Testing Library 패키지도 설치되어 있으므로, src/ 아래에 추가되는 컴포넌트 테스트도 같은 설정을 사용할 수 있습니다.
Playwright 엔드투엔드 테스트
playwright.config.ts는 서로 다른 책임을 가진 여러 프로젝트를 정의합니다.
| 프로젝트 | 범위 |
|---|---|
api | e2e/api 아래 API 수준 spec |
flows | e2e/flows 아래 엔드투엔드 비즈니스 플로우 |
chromium | e2e/ui 아래 브라우저 UI 검사 |
ssr-setup | SSR 검사용 1회성 인증 storage setup |
ssr | e2e/ssr 아래 SSR 회귀 spec |
현재 설정의 주목할 만한 동작:
- 브라우저 UI 프로젝트만
npm run dev를 부팅하며, 그것도PW_UI=1일 때만 그렇습니다 - API와 flow 프로젝트는 Next.js dev server를 자동으로 시작하지 않습니다
- trace는 첫 재시도 시 수집됩니다
- CI는 재시도를 켜고 단일 worker로 실행됩니다
테스트 디렉터리
| 경로 | 목적 |
|---|---|
e2e/api/ | 요청 수준 인증 및 exam API 검사 |
e2e/flows/ | 기능을 가로지르는 제품 플로우 |
e2e/ui/ | 브라우저 렌더링 및 라우트 수준 상호작용 검사 |
e2e/ssr/ | SSR 및 hydration 회귀 검사 |
e2e/utils/ | 재사용 가능한 API 클라이언트와 헬퍼 |
e2e/config/ | 환경 선택과 global setup/teardown |
테스트 실행 전 준비
프론트엔드 리포지토리 루트에서 시작합니다.
cd lumie-frontend
npm install
전제 조건은 스위트마다 약간 다릅니다.
| 스위트 | 미리 실행 중이어야 하는 것 |
|---|---|
test:unit | 로컬 의존성 외에는 없음 |
test:e2e:api 및 test:e2e:flows | 선택된 monolith base URL에서 도달 가능한 백엔드 |
test:e2e:ui | 추가 준비 없음. 스크립트가 PW_UI=1을 설정하므로 playwright.config.ts가 npm run dev를 자동 부팅합니다 |
test:e2e:ssr | BASE_URL에서 실행 중인 프론트엔드, 도달 가능한 백엔드, 유효한 로그인 자격 증명 |
환경 변수
Playwright는 TEST_ENV와 e2e/config/environments.ts를 통해 백엔드 대상을 선택합니다.
- 기본값은
local k3s와mirrord는 클러스터 기반 실행을 지원- monolith base URL은 이전의 서비스별 URL과 별도로 해석
새로운 백엔드 연계 E2E 플로우에는 e2e/utils/monolith-client.ts가 현재 쿠키 기반 monolith 백엔드를 반영합니다. e2e/utils/api-client.ts는 이전 분리 서비스 가정을 대상으로 한 오래된 인증 spec을 위해 여전히 존재합니다.
스위트가 기본값 이상을 필요로 할 때는 다음 env var를 사용합니다.
| 변수 | 사용 위치 | 의미 |
|---|---|---|
TEST_ENV | Playwright | local, docker, k3s, mirrord, ci 중 선택하며 기본값은 local |
LUMIE_API_URL | Playwright API 및 flow 스위트 | e2e/config/environments.ts의 monolith base URL을 재정의 |
CHECK_SERVICES=true | Playwright global setup | 테스트 시작 전 GET {baseUrl}/actuator/health probe를 최선 시도로 추가 |
BASE_URL | ssr 및 ssr-setup 프로젝트 | SSR 로그인과 라우트 검사용 프론트엔드 URL, 기본값은 http://localhost:3000 |
TEST_TENANT_SLUG | e2e/ssr/auth.setup.ts | SSR 로그인 요청에 보내는 tenant slug, 기본값은 demo |
TEST_CREDS_LOGIN_ID 및 TEST_CREDS_PASSWORD | ssr-setup | e2e/ssr/.auth/owner.json 생성에 사용하는 owner 로그인 |
TEST_STUDENT_LOGIN_ID 및 TEST_STUDENT_PASSWORD | ssr-setup | 대시보드 SSR 검사용 선택적 student 로그인 |
단위 테스트 실행
cd lumie-frontend
npm run test:unit
예상 통과 신호:
vitest run이0으로 종료- 요약에 선택된 모든
src/**/*.{test,spec}.{ts,tsx}파일이 통과했다고 표시 e2e/**는 실행 대상에 포함되지 않음
빠른 반복용 명령:
cd lumie-frontend
npm run test:unit:watch
API 및 플로우 E2E 스위트 실행
TEST_ENV 또는 LUMIE_API_URL이 선택한 monolith base URL을 사용합니다.
cd lumie-frontend
TEST_ENV=local npm run test:e2e:api
TEST_ENV=local npm run test:e2e:flows
예상 통과 신호:
- Playwright가
0으로 종료 - list reporter가 선택된 모든 spec 통과로 마무리
CHECK_SERVICES=true이면 global setup이 테스트 시작 전에 해석된 monolith URL을 로그로 남김
브라우저 UI E2E 검사 실행
test:e2e:ui는 next dev를 자동으로 시작하는 유일한 프론트엔드 테스트 스크립트입니다. playwright.config.ts는 현재 UI 프로젝트가 렌더 전용이므로 더미 NEXT_PUBLIC_API_URL과 NEXT_PUBLIC_API_BASE 값을 주입합니다.
cd lumie-frontend
npm run test:e2e:ui
예상 통과 신호:
- 스크립트가
PW_UI=1을 export하므로 Playwright가npm run dev를 자동 시작 chromium프로젝트가0으로 종료- 이후
npm run test:e2e:report로 HTML 리포트를 볼 수 있음
SSR 회귀 검사 실행
ssr 프로젝트는 프론트엔드를 대신 시작해주지 않습니다. 이 프로젝트는 /api/v1/login으로 로그인하고 e2e/ssr/.auth/ 아래에 storage state 파일을 쓰는 ssr-setup 프로젝트에 의존합니다.
cd lumie-frontend
npm run dev
두 번째 셸에서:
cd lumie-frontend
BASE_URL=http://localhost:3000 \
TEST_TENANT_SLUG=demo \
TEST_CREDS_LOGIN_ID=<owner-login-id> \
TEST_CREDS_PASSWORD=<owner-password> \
TEST_STUDENT_LOGIN_ID=<student-login-id> \
TEST_STUDENT_PASSWORD=<student-password> \
npm run test:e2e:ssr
예상 통과 신호:
ssr-setup이e2e/ssr/.auth/owner.json을 생성- 설정된 테넌트가 내장된
401skip 경로로 학생 스위트를 의도적으로 건너뛰지 않는 한 student storage도 생성 - Playwright 요약이
ssr프로젝트 통과와 종료 코드0으로 끝남
자주 발생하는 실패
| 증상 | 가능성 높은 원인 | 확인할 것 |
|---|---|---|
| API 또는 flow 스위트가 멈추거나 즉시 연결 오류로 실패 | 해석된 base URL에서 백엔드 monolith에 도달할 수 없음 | TEST_ENV, LUMIE_API_URL을 확인하고 필요하면 CHECK_SERVICES=true로 재실행 |
test:e2e:ui가 포트 3000을 기다림 | 다른 프론트엔드 dev server가 이미 포트를 사용 중이거나 next dev 부팅 실패 | 다른 프로세스를 중지하거나 Playwright의 webServer 시작 로그 확인 |
ssr-setup이 owner에 대해 401로 실패 | TEST_CREDS_LOGIN_ID 또는 TEST_CREDS_PASSWORD가 TEST_TENANT_SLUG에 맞지 않음 | 올바른 테넌트 직원 계정으로 다시 실행 |
| Student SSR 테스트가 건너뛰어짐 | 설정된 테넌트에 기본 student seed 계정이 없음 | TEST_STUDENT_LOGIN_ID와 TEST_STUDENT_PASSWORD를 명시적으로 설정 |
| 단위 테스트가 예상한 파일을 놓침 | spec이 src/**/*.{test,spec}.{ts,tsx} 밖에 있음 | 테스트를 src/ 아래로 옮기거나 먼저 코드에서 리포지토리 설정을 조정 |