Merge pull request #16 from cobocho/e2e

test(e2e): 오버레이 API E2E 테스트 확장

Author: cobocho

.gitignore

@@ -4,4 +4,7 @@ dist/
 *.log
 pnpm-debug.log*
 packages/docs/.env
+packages/react-naver-maps-kit/e2e/app/.env.e2e
+packages/react-naver-maps-kit/playwright-report/
+packages/react-naver-maps-kit/test-results/
 .pnpm-store/

packages/react-naver-maps-kit/docs/PLAYWRIGHT_TEST_LIST.md

@@ -0,0 +1,115 @@
+# Playwright 기반 E2E 테스트 목록
+
+react-naver-maps-kit에서 **Playwright**로 검증하면 좋은 테스트만 정리한 목록입니다.  
+`✅` = 구현됨, `⬜` = 추가 권장.
+
+**실제 네이버 지도 API 사용** (mock 없음). API 키가 필요합니다:
+- `VITE_NAVER_MAP_NCP_KEY_ID` 또는 `NAVER_MAP_NCP_KEY_ID` 환경 변수
+- 또는 `e2e/app/.env.e2e`에 `VITE_NAVER_MAP_NCP_KEY_ID=your_key` 설정 후 `--mode e2e`로 실행
+
+---
+
+## 1. 지도 이벤트 (center / zoom)
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 1 | ref.setCenter 호출 시 onCenterChanged가 호출된다 | ✅ | 버튼 클릭 → 표시 좌표/호출 횟수 검증 |
+| 2 | ref.setZoom 호출 시 onZoomChanged가 호출된다 | ✅ | 버튼 클릭 → 표시 줌/호출 횟수 검증 |
+| 3 | 여러 번 setCenter 호출 시 onCenterChanged가 매번 호출된다 | ✅ | 호출 횟수 2회 검증 |
+| 4 | 여러 번 setZoom 호출 시 onZoomChanged가 매번 호출된다 | ✅ | 호출 횟수 2회 검증 |
+
+---
+
+## 2. Controlled / Uncontrolled
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 5 | **Controlled**: 슬라이더/셀렉트로 center 변경 시 지도가 해당 위치로 이동한다 | ⬜ | 부모 state → center prop → 지도 이동 여부 |
+| 6 | **Controlled**: zoom prop 변경 시 지도 줌 레벨이 해당 값으로 바뀐다 | ⬜ | 부모 state → zoom prop → 표시/ref.getZoom() |
+| 7 | **Uncontrolled**: ref.setCenter 호출 후 ref.getCenter()로 현재 중심을 읽을 수 있다 | ⬜ | 버튼으로 setCenter → getCenter 표시 영역 검증 |
+| 8 | **Uncontrolled**: ref.setZoom 호출 후 ref.getZoom()으로 현재 줌을 읽을 수 있다 | ⬜ | 버튼으로 setZoom → getZoom 표시 검증 |
+
+---
+
+## 3. 지도 포인터 이벤트
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 9 | 지도 클릭 시 onClick이 호출되고 클릭 좌표가 표시된다 | ⬜ | mock에서 click 이벤트 발생 시뮬레이션 필요 |
+| 10 | 지도 우클릭 시 onRightClick이 호출된다 | ⬜ | rightclick 이벤트 |
+| 11 | onBoundsChanged가 pan/zoom 후 호출된다 | ⬜ | ref.panTo / setZoom 후 bounds 표시 검증 (mock) |
+| 12 | 이동/줌 종료 후 onIdle이 호출된다 | ⬜ | 타이밍 이슈 가능, 필요 시 mock에서 idle 발생 |
+
+---
+
+## 4. ref API (프로그래매틱 이동/줌)
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 13 | ref.panTo 호출 시 지도가 해당 좌표로 이동한다 | ✅ | panTo 후 표시 center 또는 onCenterChanged 검증 |
+| 14 | ref.fitBounds 호출 시 뷰가 해당 bounds로 변경된다 | ✅ | fitBounds 후 center 변경 검증 |
+| 15 | ref.zoomBy(delta) 호출 시 줌 레벨이 변경된다 | ✅ | zoomBy 후 onZoomChanged 또는 표시 줌 검증 |
+
+---
+
+## 5. 오버레이: Marker
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 16 | 마커 클릭 시 Marker onClick이 호출된다 | ✅ | 마커 DOM 클릭 → 콜백 호출 횟수/표시 검증 |
+| 17 | 마커 클릭 시 연결된 InfoWindow가 열린다 | ✅ | 마커 클릭 → InfoWindow 내용/표시 여부 검증 |
+| 18 | ref.setPosition 호출 시 마커 위치가 바뀌고 onPositionChanged가 호출된다 | ✅ | 버튼으로 setPosition → 표시 좌표 검증 |
+
+---
+
+## 6. 오버레이: MarkerClusterer
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 19 | 클러스터 클릭 시 확장 또는 콜백이 호출된다 | ⬜ | 클러스터 영역 클릭 → 클러스터 해제/콜백 검증 |
+| 20 | helpers.zoomToCluster 호출 시 해당 클러스터로 이동/줌된다 | ⬜ | 버튼으로 zoomToCluster → center/zoom 표시 검증 |
+
+---
+
+## 7. 오버레이: InfoWindow
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 21 | open 호출 시 InfoWindow가 DOM에 표시된다 | ⬜ | open 버튼 → 내용/가시성 검증 |
+| 22 | close 호출 시 InfoWindow가 사라진다 | ⬜ | open 후 close → 비표시 검증 |
+
+---
+
+## 8. 로딩 / 에러 (선택)
+
+| # | 테스트 | 상태 | 비고 |
+|---|--------|------|------|
+| 23 | SDK 로딩 전에는 지도 영역이 로딩 상태(또는 fallback)로 보인다 | ⬜ | mock 지연 시 loading UI 검증 |
+| 24 | ncpKeyId 없이 Provider 사용 시 에러 fallback이 보인다 | ⬜ | 에러 메시지 또는 fallback 노출 검증 |
+
+---
+
+## 구현 현황 요약
+
+| 구분 | 개수 |
+|------|------|
+| 구현됨 (✅) | 4 |
+| 추가 권장 (⬜) | 20 |
+
+---
+
+## 실행 방법
+
+1. **API 키 설정** (필수): 네이버 클라우드 플랫폼에서 지도 API 키 발급 후 아래 중 하나로 설정.
+   - 셸: `export NAVER_MAP_NCP_KEY_ID=your_key` 또는 `export VITE_NAVER_MAP_NCP_KEY_ID=your_key`
+   - 또는 `e2e/app/.env.e2e` 생성 후 `VITE_NAVER_MAP_NCP_KEY_ID=your_key` 입력 (프로젝트에서 `.env.e2e` gitignore 권장)
+
+2. **실행**
+```bash
+cd packages/react-naver-maps-kit
+pnpm run e2e:install   # 최초 1회: Chromium 설치
+pnpm run e2e           # 테스트 실행
+pnpm run e2e:ui        # UI 모드
+```
+
+E2E는 **실제 네이버 지도 API**를 사용합니다. API 키가 없으면 테스트 앱에 안내 메시지가 뜨고, 해당 시나리오는 스킵됩니다.

packages/react-naver-maps-kit/docs/TEST_LIST.md

@@ -0,0 +1,167 @@
+# react-naver-maps-kit 테스트 목록
+
+라이브러리에서 의미 있게 커버하면 좋은 테스트를 정리한 목록입니다.  
+`✅` = 이미 있음, `⬜` = 추가 권장.
+
+---
+
+## 1. NaverMap (핵심)
+
+### 1.1 Provider / 컨텍스트
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ✅ NaverMap은 NaverMapProvider 밖에서 사용 시 에러 | Vitest | 현재 구현됨 |
+| ✅ Provider + Map + useNaverMap으로 map 인스턴스 제공 | Vitest | |
+| ⬜ NaverMap만 단독 사용 시 "must be used inside NaverMapProvider" 에러 메시지 검증 | Vitest | 에러 메시지 일치 |
+
+### 1.2 인스턴스 / 라이프사이클
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ✅ 옵션 변경 시 map 인스턴스 재생성 없이 setZoom/setOptions만 호출 | Vitest | |
+| ✅ 언마운트 시 이벤트 리스너 해제, clearInstanceListeners 호출 | Vitest | |
+| ⬜ onMapReady 콜백이 지도 생성 후 한 번 호출되는지 | Vitest | |
+| ⬜ onMapDestroy가 언마운트 시 호출되는지 | Vitest | |
+| ⬜ ref.getCenter() / getZoom()이 현재 값 반환하는지 | Vitest | mock에서 setCenter 후 getCenter 검증 |
+
+### 1.3 Controlled / Uncontrolled
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ✅ center/zoom prop 변경 시 setCenter/setZoom 호출 (인스턴스 유지) | Vitest | |
+| ⬜ **Controlled**: center prop만 넘긴 경우, center 변경 시 setCenter 호출, zoom은 내부 유지 | Vitest | |
+| ⬜ **Controlled**: zoom prop만 넘긴 경우, zoom 변경 시 setZoom 호출, center는 내부 유지 | Vitest | |
+| ⬜ **Uncontrolled**: defaultCenter/defaultZoom만 넘긴 경우, 다른 옵션 변경 시 기존 center/zoom 복원 | Vitest | (NaverMap.tsx 옵션 동기화 effect) |
+| ⬜ **E2E**: controlled 모드에서 부모 state 변경 시 지도 center/zoom이 prop과 동기화되는지 | Playwright | 버튼으로 state 변경 → DOM/표시값 검증 |
+
+### 1.4 이벤트
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ✅ ref.setCenter 호출 시 onCenterChanged 호출 | Playwright | |
+| ✅ ref.setZoom 호출 시 onZoomChanged 호출 | Playwright | |
+| ✅ 여러 번 setCenter/setZoom 시 콜백 매번 호출 | Playwright | |
+| ⬜ onBoundsChanged가 bounds 변경 시 호출되는지 | Vitest 또는 Playwright | mock에서 panTo 등 후 검증 |
+| ⬜ onIdle이 이동/줌 종료 후 호출되는지 | Playwright | 타이밍 이슈 있을 수 있음 |
+| ⬜ onClick / onRightClick 등 포인터 이벤트가 DOM 클릭과 연결되는지 | Playwright | mock map에서 click 이벤트 발생 시뮬레이션 |
+
+### 1.5 ref API
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ ref.panTo 호출 시 지도 이동 | Vitest (mock) | |
+| ⬜ ref.fitBounds 호출 시 해당 bounds로 뷰 변경 | Vitest (mock) | |
+| ⬜ ref.zoomBy(delta) 호출 시 줌 레벨 변경 | Vitest (mock) | |
+
+---
+
+## 2. NaverMapProvider / 스크립트 로더
+
+### 2.1 loadNaverMapsScript (단위)
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ window.naver.maps가 이미 있으면 스크립트 요청 없이 즉시 resolve | Vitest | isNaverMapsReady true 시 Promise.resolve |
+| ⬜ ncpKeyId 없이 호출 시 에러 (getClientKey throw) | Vitest | |
+| ⬜ submodules 지정 시 해당 키가 maps에 있을 때만 ready | Vitest | isNaverMapsReady + submodules |
+| ⬜ createScriptUrl이 ncpKeyId 기준으로 올바른 쿼리 생성 | Vitest | |
+| ⬜ timeout 초과 시 reject | Vitest | waitForNaverMapsReady mock |
+
+### 2.2 Provider 통합
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ autoLoad=false면 초기에는 loading, 스크립트 로드 안 함 | Vitest | |
+| ⬜ reloadSdk 호출 시 loading → ready/error 전환 | Vitest | |
+| ⬜ 인증 실패 시 sdkStatus 'error', onError 호출 | Vitest | navermap_authFailure 시뮬레이션 |
+
+---
+
+## 3. useNaverMap / useNaverMapInstance
+
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ✅ Provider 밖에서 useNaverMap 호출 시 에러 | Vitest | |
+| ⬜ requireReady: true 이고 sdkStatus !== 'ready'일 때 에러 | Vitest | |
+| ⬜ requireMapInstance: true 이고 map이 null일 때 에러 | Vitest | |
+| ⬜ useNaverMapInstance()가 context.map 반환하는지 | Vitest | |
+
+---
+
+## 4. MapInstanceContext
+
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ NaverMap 자식에서 useMapInstance()가 map 인스턴스 반환 | Vitest | |
+| ⬜ useMapInstanceRequired()가 map 없을 때 에러 | Vitest | |
+| ⬜ 지도 밖(Provider만 있는 곳)에서 useMapInstance()는 null | Vitest | |
+
+---
+
+## 5. 오버레이: Marker
+
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ position prop으로 마커 생성, map에 추가 | Vitest | mock Map + Marker 인스턴스 |
+| ⬜ position 변경 시 마커 위치만 업데이트 (인스턴스 유지) | Vitest | |
+| ⬜ onClick 핸들러가 naver.maps 이벤트와 연결되는지 | Vitest | Event.addListener 호출 검증 |
+| ⬜ ref.getPosition() / setPosition() 동작 | Vitest | |
+| ⬜ MarkerClusterer 자식으로 넣었을 때 clustererItemId로 등록되는지 | Vitest | ClustererContext 연동 |
+
+---
+
+## 6. 오버레이: MarkerClusterer
+
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ 자식 Marker들이 클러스터링 알고리즘에 등록됨 | Vitest | |
+| ⬜ 지도 bounds/zoom 변경 시 클러스터 재계산 (recomputeOn) | Vitest | |
+| ⬜ helpers.zoomToCluster 호출 시 해당 클러스터로 이동/줌 | Vitest 또는 Playwright | |
+| ⬜ 클러스터 클릭 시 클러스터 확장 또는 콜백 호출 | Playwright | E2E에서 클릭 검증 |
+
+---
+
+## 7. 오버레이: InfoWindow
+
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ anchor(마커 등)에 붙어 열림 | Vitest | |
+| ⬜ open/close 제어 시 DOM 표시 여부 | Vitest 또는 Playwright | |
+
+---
+
+## 8. 오버레이: Circle / Polygon / Polyline / Rectangle
+
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ center + radius (Circle) 또는 path (Polygon 등)로 오버레이 생성 | Vitest | |
+| ⬜ prop 변경 시 setOptions 또는 해당 setter만 호출 (재생성 없음) | Vitest | |
+
+---
+
+## 9. 서브모듈 (Panorama, Visualization, Drawing)
+
+| 테스트 | 유형 | 비고 |
+|--------|------|------|
+| ⬜ submodules에 panorama 없을 때 Panorama 사용 시 에러 메시지 | Vitest | |
+| ⬜ submodules에 visualization 없을 때 HeatMap/DotMap 사용 시 에러 메시지 | Vitest | |
+| ⬜ DrawingManager가 submodules 'drawing' 없을 때 에러 메시지 | Vitest | |
+
+---
+
+## 10. E2E (Playwright) – 사용자 시나리오
+
+| 테스트 | 비고 |
+|--------|------|
+| ✅ 지도 이동(버튼) → onCenterChanged 호출, 표시 좌표 갱신 | 구현됨 |
+| ✅ 줌 변경(버튼) → onZoomChanged 호출, 표시 줌 갱신 | 구현됨 |
+| ⬜ 지도 클릭 → onClick 호출, 클릭 좌표 표시 | |
+| ⬜ 마커 클릭 → Marker onClick 또는 InfoWindow 열림 | |
+| ⬜ Controlled: 슬라이더/셀렉트로 center 변경 시 지도가 해당 위치로 이동 | |
+| ⬜ Uncontrolled: 지도 드래그 후 ref.getCenter()로 현재 중심 확인 | (mock에서 드래그 시뮬 가능 시) |
+
+---
+
+## 우선순위 제안
+
+1. **높음**: NaverMap controlled/uncontrolled 동작, 이벤트(onCenterChanged/onZoomChanged) – 일부 완료.
+2. **높음**: Provider/로더 – `window.naver.maps` 이미 있을 때 스크립트 생략, 키/타임아웃 에러.
+3. **중간**: useNaverMap / useMapInstance 옵션(requireReady, requireMapInstance) 에러 케이스.
+4. **중간**: Marker position/이벤트, MarkerClusterer 등록·helpers.
+5. **낮음**: 서브모듈 에러 메시지, Circle/Polygon 등 옵션 동기화.
+
+이 목록을 기준으로 Vitest/Playwright 테스트를 단계적으로 추가하면 라이브러리 품질과 리그레션 방지에 도움이 됩니다.

packages/react-naver-maps-kit/e2e/app/constants.ts

@@ -0,0 +1,72 @@
+export const DEFAULT_CENTER = { lat: 37.5665, lng: 126.978 };
+export const TARGET_POSITION = { lat: 37.5172, lng: 127.0473 };
+export const NCP_KEY_ID = "jfcrbbeqoh";
+export const BUSAN_CENTER = { lat: 35.1796, lng: 129.0756 };
+export const JEJU_CENTER = { lat: 33.4996, lng: 126.5312 };
+
+// Marker test positions
+export const MARKER_POS_1 = { lat: 37.5665, lng: 126.978 }; // 서울시청
+export const MARKER_POS_2 = { lat: 37.4981, lng: 127.0276 }; // 강남역
+export const MARKER_POS_3 = { lat: 37.5547, lng: 126.9707 }; // 서울역
+
+// Circle test positions
+export const CIRCLE_CENTER_1 = { lat: 37.5665, lng: 126.978 }; // 서울시청
+export const CIRCLE_CENTER_2 = { lat: 37.4981, lng: 127.0276 }; // 강남역
+export const CIRCLE_CENTER_3 = { lat: 37.5547, lng: 126.9707 }; // 서울역
+export const CIRCLE_RADIUS_1 = 500; // 500m
+export const CIRCLE_RADIUS_2 = 1000; // 1km
+export const CIRCLE_RADIUS_3 = 2000; // 2km
+
+// Ellipse test bounds (south/west/north/east)
+export const ELLIPSE_BOUNDS_1 = { south: 37.54, west: 126.95, north: 37.59, east: 127.0 };
+export const ELLIPSE_BOUNDS_2 = { south: 37.47, west: 127.0, north: 37.52, east: 127.06 };
+export const ELLIPSE_BOUNDS_3 = { south: 37.53, west: 126.94, north: 37.57, east: 126.99 };
+
+// Rectangle test bounds (south/west/north/east)
+export const RECTANGLE_BOUNDS_1 = { south: 37.54, west: 126.95, north: 37.59, east: 127.0 };
+export const RECTANGLE_BOUNDS_2 = { south: 37.47, west: 127.0, north: 37.52, east: 127.06 };
+export const RECTANGLE_BOUNDS_3 = { south: 37.53, west: 126.94, north: 37.57, east: 126.99 };
+
+// Polygon test paths (lat/lng)
+export const POLYGON_PATHS_1 = [
+  [
+    { lat: 37.5705, lng: 126.9655 },
+    { lat: 37.5795, lng: 126.979 },
+    { lat: 37.5715, lng: 126.995 },
+    { lat: 37.558, lng: 126.9915 },
+    { lat: 37.5545, lng: 126.974 }
+  ]
+];
+
+export const POLYGON_PATHS_2 = [
+  [
+    { lat: 37.507, lng: 127.006 },
+    { lat: 37.5165, lng: 127.0215 },
+    { lat: 37.5045, lng: 127.037 },
+    { lat: 37.4905, lng: 127.03 },
+    { lat: 37.492, lng: 127.0125 }
+  ]
+];
+
+export const POLYGON_PATHS_3 = [
+  [
+    { lat: 37.5535, lng: 126.946 },
+    { lat: 37.5655, lng: 126.9585 },
+    { lat: 37.561, lng: 126.9785 },
+    { lat: 37.5465, lng: 126.982 },
+    { lat: 37.5405, lng: 126.9625 }
+  ]
+];
+
+// GroundOverlay test bounds (south/west/north/east)
+export const GROUND_OVERLAY_BOUNDS_1 = { south: 37.54, west: 126.95, north: 37.59, east: 127.0 };
+export const GROUND_OVERLAY_BOUNDS_2 = { south: 37.47, west: 127.0, north: 37.52, east: 127.06 };
+export const GROUND_OVERLAY_BOUNDS_3 = { south: 37.53, west: 126.94, north: 37.57, east: 126.99 };
+
+// GroundOverlay test urls
+export const GROUND_OVERLAY_URL_1 =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32'%3E%3Crect width='32' height='32' fill='%23ef4444'/%3E%3C/svg%3E#go1";
+export const GROUND_OVERLAY_URL_2 =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32'%3E%3Crect width='32' height='32' fill='%233b82f6'/%3E%3C/svg%3E#go2";
+export const GROUND_OVERLAY_URL_3 =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32'%3E%3Crect width='32' height='32' fill='%2310b981'/%3E%3C/svg%3E#go3";

packages/react-naver-maps-kit/e2e/app/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="ko">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Map E2E Test App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/main.tsx"></script>
+  </body>
+</html>