Taehoon/ITAM

Fork 0

Files

SDI fd0bd126d1

ITAM Code Check / build-and-config-check (push) Successful in 12s

Details

ITAM Docker Build Check / docker-build-check (push) Successful in 23s

Details

BARON-SSO 로그인 API 요청경로 수정

2026-07-01 17:47:20 +09:00

9.6 KiB

Raw Blame History

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계층으로 나눈다.

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

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

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

3.1. 기본 방향

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

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

3.2. 왜 이 방식이 적합한가

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

4. 권장 테스트 범위

4.1. 1차 도입 범위

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

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

4.2. 2차 도입 범위

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

4.3. 3차 도입 범위

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

5. Baron SSO 연동 테스트 전략

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

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

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

5.2. 자동화 가능한 영역

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

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

5.3. 권장 방식

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

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

6. 구현 Task 목록

6.1. Phase 1: 기본 세팅

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

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

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

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

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

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

phone/init 성공 응답 mock 테스트
phone/poll pending 상태 mock 테스트
phone/poll authenticated 상태 mock 테스트
phone/poll expired 상태 mock 테스트
phone/poll 에러 메시지 표시 테스트

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

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

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

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

7. 워크플로 통합 권장안

7.1. 신규 워크플로

권장 워크플로 이름:

itam_playwright_check.yml

7.2. 실행 순서

권장 순서는 아래와 같다.

itam_code_check.yml
itam_docker_build_check.yml
itam_playwright_check.yml
itam_production_deploy.yml

7.3. 이유

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

8. 디렉터리 구조 제안

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차 도입 완료로 본다.

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

12. 권장 실행 순서

1차 구현 권장 순서

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

2차 확장 권장 순서

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

13. 결론

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

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

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

9.6 KiB Raw Blame History