본문으로 건너뛰기

테스트

이 페이지는 주로 프론트엔드 테스트 스위트를 실행하는 how-to 문서입니다. 첫 섹션은 테스트 레이어를 정리하고, 나머지는 현재 구성에서 자주 나타나는 전제 조건, 명령, 통과 신호, 실패 양상에 집중합니다.

프론트엔드 리포지토리는 두 가지 테스트 레이어를 사용합니다.

  • src/ 아래의 단위 테스트와 작은 컴포넌트 중심 테스트용 Vitest
  • e2e/ 아래의 API, 플로우, UI, SSR 회귀 검사용 Playwright

소스 경로

경로역할
lumie-frontend/package.json테스트 진입점 스크립트
lumie-frontend/vitest.config.tsVitest 환경, setup 파일, include/exclude glob
lumie-frontend/vitest.setup.ts@testing-library/jest-dom/vitest 로드
lumie-frontend/playwright.config.tsPlaywright 프로젝트, 재시도, reporter, UI 전용 webServer
lumie-frontend/e2e/config/environments.tsTEST_ENV 해석과 monolith base URL 매핑
lumie-frontend/e2e/config/global-setup.tsCHECK_SERVICES=true일 때 선택적 백엔드 health probe
lumie-frontend/e2e/ssr/auth.setup.tsSSR 로그인 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는 서로 다른 책임을 가진 여러 프로젝트를 정의합니다.

프로젝트범위
apie2e/api 아래 API 수준 spec
flowse2e/flows 아래 엔드투엔드 비즈니스 플로우
chromiume2e/ui 아래 브라우저 UI 검사
ssr-setupSSR 검사용 1회성 인증 storage setup
ssre2e/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:apitest:e2e:flows선택된 monolith base URL에서 도달 가능한 백엔드
test:e2e:ui추가 준비 없음. 스크립트가 PW_UI=1을 설정하므로 playwright.config.tsnpm run dev를 자동 부팅합니다
test:e2e:ssrBASE_URL에서 실행 중인 프론트엔드, 도달 가능한 백엔드, 유효한 로그인 자격 증명

환경 변수

Playwright는 TEST_ENVe2e/config/environments.ts를 통해 백엔드 대상을 선택합니다.

  • 기본값은 local
  • k3smirrord는 클러스터 기반 실행을 지원
  • monolith base URL은 이전의 서비스별 URL과 별도로 해석

새로운 백엔드 연계 E2E 플로우에는 e2e/utils/monolith-client.ts가 현재 쿠키 기반 monolith 백엔드를 반영합니다. e2e/utils/api-client.ts는 이전 분리 서비스 가정을 대상으로 한 오래된 인증 spec을 위해 여전히 존재합니다.

스위트가 기본값 이상을 필요로 할 때는 다음 env var를 사용합니다.

변수사용 위치의미
TEST_ENVPlaywrightlocal, docker, k3s, mirrord, ci 중 선택하며 기본값은 local
LUMIE_API_URLPlaywright API 및 flow 스위트e2e/config/environments.ts의 monolith base URL을 재정의
CHECK_SERVICES=truePlaywright global setup테스트 시작 전 GET {baseUrl}/actuator/health probe를 최선 시도로 추가
BASE_URLssrssr-setup 프로젝트SSR 로그인과 라우트 검사용 프론트엔드 URL, 기본값은 http://localhost:3000
TEST_TENANT_SLUGe2e/ssr/auth.setup.tsSSR 로그인 요청에 보내는 tenant slug, 기본값은 demo
TEST_CREDS_LOGIN_IDTEST_CREDS_PASSWORDssr-setupe2e/ssr/.auth/owner.json 생성에 사용하는 owner 로그인
TEST_STUDENT_LOGIN_IDTEST_STUDENT_PASSWORDssr-setup대시보드 SSR 검사용 선택적 student 로그인

단위 테스트 실행

cd lumie-frontend
npm run test:unit

예상 통과 신호:

  • vitest run0으로 종료
  • 요약에 선택된 모든 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:uinext dev를 자동으로 시작하는 유일한 프론트엔드 테스트 스크립트입니다. playwright.config.ts는 현재 UI 프로젝트가 렌더 전용이므로 더미 NEXT_PUBLIC_API_URLNEXT_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-setupe2e/ssr/.auth/owner.json을 생성
  • 설정된 테넌트가 내장된 401 skip 경로로 학생 스위트를 의도적으로 건너뛰지 않는 한 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_PASSWORDTEST_TENANT_SLUG에 맞지 않음올바른 테넌트 직원 계정으로 다시 실행
Student SSR 테스트가 건너뛰어짐설정된 테넌트에 기본 student seed 계정이 없음TEST_STUDENT_LOGIN_IDTEST_STUDENT_PASSWORD를 명시적으로 설정
단위 테스트가 예상한 파일을 놓침spec이 src/**/*.{test,spec}.{ts,tsx} 밖에 있음테스트를 src/ 아래로 옮기거나 먼저 코드에서 리포지토리 설정을 조정

관련 페이지