ITAM/docs/plans/PLAYWRIGHT_E2E_ADOPTION_PLAN.md

# Playwright E2E 도입 계획

## 1. 목적

이 문서는 현재 Dachs 시스템 구조를 기준으로 Playwright를 도입하여 배포 전후 품질 검증을 자동화하기 위한 실행 계획을 정리한다.

현재 시스템은 다음 특성을 가진다.

- Vite 프런트엔드 + Express 백엔드 구조
- Docker Compose 기반 테스트/운영 배포
- Baron SSO 연동 및 세션 기반 인증
- Gitea 워크플로를 통한 코드 체크, 이미지 빌드, 운영 배포

이 구조에서는 단순 컴포넌트 테스트보다 실제 브라우저 흐름을 검증하는 E2E/smoke 테스트가 더 큰 효과를 가진다.

---

## 2. 도입 원칙

### 2.1. Playwright 역할 정의

Playwright는 다음 역할에 집중한다.

- 배포 전 사용자 관점 smoke 테스트
- 핵심 화면 진입 가능 여부 검증
- 인증 이후 세션 유지 및 로그아웃 동작 검증
- 프런트/백엔드/프록시 통합 상태 검증

다음 항목은 초기 도입 범위에서 제외한다.

- Baron 실서비스 의존도가 높은 완전 자동 로그인 승인 테스트
- SMS 수신 자체 검증
- 운영 Baron 실제 전화번호 인증 전체 플로우의 상시 CI 자동화

### 2.2. 테스트 계층 원칙

Playwright 테스트는 3계층으로 나눈다.

1. 로컬/CI smoke 테스트
2. mock 기반 인증 UI 테스트
3. 수동 또는 반자동 실연동 검증

이렇게 나누는 이유는 Baron 외부 시스템 의존성을 CI 불안정성으로 끌고 오지 않기 위해서다.

---

## 3. 현재 구조에서의 권장 도입 방식

### 3.1. 기본 방향

현재 저장소 구조에서는 다음 흐름이 가장 적합하다.

1. `docker-compose.test.yaml`로 테스트 스택 기동
2. Playwright가 `http://127.0.0.1:8080` 기준으로 브라우저 테스트 수행
3. 실패 시 trace/screenshot/video 아티팩트 수집
4. 성공 시에만 이후 빌드/배포 단계 진행

### 3.2. 왜 이 방식이 적합한가

- 실제 nginx 프록시 경로를 포함한 상태를 검증할 수 있다.
- 세션 쿠키, API 라우팅, 정적 파일 서빙까지 함께 검증할 수 있다.
- 현재 시스템의 리스크는 단순 함수 로직보다 통합 동작에서 더 자주 발생한다.
- 운영과 유사한 경로를 테스트하면서도 Baron 실서비스 의존성은 줄일 수 있다.

---

## 4. 권장 테스트 범위

### 4.1. 1차 도입 범위

초기 도입은 아래 항목만 자동화한다.

1. 로그인 페이지 렌더링
2. 로고, 안내 문구, 전화번호 입력창, 인증 버튼 존재 확인
3. `/api/auth/session` 결과에 따른 로그인 화면/앱 화면 분기 확인
4. 로그인 후 헤더 렌더링 확인
5. 핵심 메뉴 노출 확인
6. 로그아웃 버튼 노출 및 클릭 후 로그인 화면 복귀 확인
7. 주요 정적 리소스 정상 로딩 확인

### 4.2. 2차 도입 범위

1. 전화번호 로그인 시작 버튼 클릭 후 pending UI 상태 전환
2. `/api/auth/headless/phone/poll`의 pending/authenticated/expired/error 상태별 UI 검증
3. 서버/PC/스토리지 등 핵심 탭 진입 smoke 테스트
4. 자주 깨지는 뷰 하나 이상에 대한 회귀 테스트

### 4.3. 3차 도입 범위

1. mock 기반 인증 완료 흐름
2. 관리자/실무자 모드 전환 검증
3. 주요 CRUD 진입 경로 검증
4. 배포 후 production smoke 테스트

---

## 5. Baron SSO 연동 테스트 전략

### 5.1. 자동화하지 말아야 할 영역

다음 항목은 초기 CI 자동화 대상에서 제외한다.

- 실제 SMS 수신 검증
- 실제 모바일 승인 검증
- Baron 외부 서비스 응답시간에 의존하는 full E2E 인증 테스트

### 5.2. 자동화 가능한 영역

다음 항목은 Playwright에서 자동화 가능하다.

- 전화번호 입력 UI 검증
- 인증 링크 요청 버튼 동작 검증
- `init` 성공/실패 메시지 렌더링 확인
- `poll` 상태별 화면 상태 전환 검증

### 5.3. 권장 방식

초기에는 다음 방식으로 구현한다.

1. 브라우저 레벨에서 API 응답 mock 사용
2. `pending`, `authenticated`, `expired`, `tenant_not_allowed` 응답 시나리오를 고정
3. Baron 실서비스 연동은 별도 수동 체크리스트로 유지

---

## 6. 구현 Task 목록

## 6.1. Phase 1: 기본 세팅

1. `@playwright/test` devDependency 추가
2. `playwright.config.ts` 생성
3. `tests/e2e` 디렉터리 생성
4. `package.json`에 아래 스크립트 추가
   - `test:e2e`
   - `test:e2e:headed`
   - `test:e2e:ui`
5. 브라우저 설치 명령 정리
6. `.gitignore`에 Playwright 산출물 경로 정리

## 6.2. Phase 2: CI 실행 환경 정비

1. CI용 `.env` 또는 `.env.e2e` 규칙 정의
2. test compose 스택 기동 명령 정리
3. readiness check 절차 추가
4. 테스트 종료 후 compose down 정리
5. trace/screenshot/video 저장 경로 정의

## 6.3. Phase 3: 1차 smoke 테스트 작성

1. 로그인 페이지 로드 테스트
2. 로고 이미지 노출 테스트
3. SMS 안내 문구 노출 테스트
4. 전화번호 입력창/인증 버튼 존재 테스트
5. 비로그인 상태 앱 화면 차단 확인
6. 로그인된 세션 상태에서 앱 레이아웃 표시 확인
7. 헤더 우측 로그아웃 버튼 노출 확인
8. 로그아웃 클릭 후 로그인 화면 복귀 확인

## 6.4. Phase 4: 인증 UI 상태 테스트

1. `phone/init` 성공 응답 mock 테스트
2. `phone/poll` pending 상태 mock 테스트
3. `phone/poll` authenticated 상태 mock 테스트
4. `phone/poll` expired 상태 mock 테스트
5. `phone/poll` 에러 메시지 표시 테스트

## 6.5. Phase 5: 화면 회귀 smoke 확대

1. 서버 탭 진입 테스트
2. PC 탭 진입 테스트
3. 스토리지 탭 진입 테스트
4. 대시보드 진입 테스트
5. 공통 헤더/메뉴 렌더링 회귀 테스트

## 6.6. Phase 6: 배포 파이프라인 통합

1. `itam_playwright_check.yml` 신규 추가
2. `main`, `Dockerizing`, `pull_request`에서 자동 실행
3. `docker compose -f docker-compose.test.yaml up -d --build` 후 Playwright 실행
4. 실패 시 아티팩트 업로드
5. 필요 시 production deploy 전 필수 게이트로 연결

---

## 7. 워크플로 통합 권장안

### 7.1. 신규 워크플로

권장 워크플로 이름:

- `itam_playwright_check.yml`

### 7.2. 실행 순서

권장 순서는 아래와 같다.

1. `itam_code_check.yml`
2. `itam_docker_build_check.yml`
3. `itam_playwright_check.yml`
4. `itam_production_deploy.yml`

### 7.3. 이유

- 코드/빌드 오류를 먼저 빠르게 걸러낸다.
- Playwright는 상대적으로 무거우므로 빌드 검증 이후에 실행하는 것이 효율적이다.
- 배포 전에 실제 브라우저 smoke를 마지막 게이트로 둘 수 있다.

---

## 8. 디렉터리 구조 제안

```text
playwright.config.ts
tests/
  e2e/
    auth.login-page.spec.ts
    auth.logout.spec.ts
    auth.phone-flow.mock.spec.ts
    smoke.navigation.spec.ts
  fixtures/
  utils/
```

권장 파일 역할:

- `auth.login-page.spec.ts`: 로그인 화면 존재/문구/입력 요소 검증
- `auth.logout.spec.ts`: 로그인 후 로그아웃 버튼 동작 검증
- `auth.phone-flow.mock.spec.ts`: pending/authenticated/expired 상태 검증
- `smoke.navigation.spec.ts`: 주요 GNB 회귀 테스트

---

## 9. 운영/테스트 환경 변수 정책

### 9.1. Playwright 기본 대상

- 기본 대상: `http://127.0.0.1:8080`
- 실행 대상: `docker-compose.test.yaml`로 띄운 테스트 스택

### 9.2. 실연동 테스트 분리

운영 Baron 실연동 검증은 다음과 같이 분리한다.

- 기본 CI에는 포함하지 않음
- 수동 실행 workflow 또는 로컬 수동 검증으로 유지
- 필요 시 nightly/manual workflow로만 별도 실행

---

## 10. 위험 요소 및 대응

### 10.1. Baron 외부 의존성

위험:

- 응답 지연
- 인증 정책 변경
- SMS/모바일 승인 필요

대응:

- mock 기반 테스트 우선
- 실연동은 수동 체크 유지

### 10.2. 세션 스토어 한계

위험:

- 현재 기본 메모리 세션 사용
- 멀티 인스턴스/재시작 시 일관성 한계

대응:

- Playwright 도입 자체는 가능
- 장기적으로 Redis 세션 스토어 검토

### 10.3. 테스트 데이터 불안정

위험:

- DB 상태에 따라 화면 결과 달라짐

대응:

- 테스트용 fixture 데이터 도입
- 최소 seed 또는 고정 상태 준비

---

## 11. 도입 완료 기준

다음 조건을 만족하면 1차 도입 완료로 본다.

1. Playwright 설정 파일이 저장소에 추가됨
2. 테스트 스택 기준 smoke 테스트가 로컬에서 통과함
3. Gitea CI에서 Playwright 체크가 자동 실행됨
4. 실패 시 trace/screenshot 아티팩트 확인 가능함
5. 로그인 페이지/로그아웃/핵심 헤더 회귀 테스트가 동작함

---

## 12. 권장 실행 순서

### 1차 구현 권장 순서

1. Playwright 설치 및 설정 파일 추가
2. 로그인 페이지 smoke 테스트 작성
3. 로그아웃 smoke 테스트 작성
4. test compose 기반 CI 워크플로 연결
5. mock 기반 phone flow 테스트 추가

### 2차 확장 권장 순서

1. 핵심 탭 smoke 테스트 추가
2. 실무자/관리자 모드 전환 테스트 추가
3. 배포 전 필수 게이트 연결
4. 운영 smoke 또는 nightly 검사 검토

---

## 13. 결론

현재 Dachs 구조에서 Playwright는 다음 방식으로 도입하는 것이 가장 적합하다.

- Docker Compose test 스택 기반 E2E/smoke
- Baron 실서비스 전체 플로우는 초기 CI 자동화에서 제외
- 로그인 화면, 세션, 로그아웃, 핵심 내비게이션부터 단계적으로 확대
- Gitea 워크플로의 배포 전 게이트로 통합

즉, 도입 초점은 “완전한 외부 인증 자동화”가 아니라 “현재 시스템의 실제 사용자 흐름이 배포 전에 깨지지 않는지 검증하는 것”에 둔다.