[common] playwright 테스트 사용법 추가함

2026-09-22 17:40:00 +09:00
parent 66bca69578
commit 454b9e474f
1 changed files with 102 additions and 1 deletions
@@ -52,7 +52,107 @@ cs 애플리케이션 내의 컴포넌트 로직 검증 및 렌더링 검사 기

 ---

-## 검증 결과
+## 5. Playwright E2E 테스트 개념 및 실전 사용법 가이드
+
+### 5.1 Playwright 핵심 개념 (What is Playwright?)
+
+Playwright는 Microsoft에서 개발한 차세대 **End-to-End(E2E) 브라우저 자동화 및 테스트 프레임워크**입니다. 사용자 관점에서 브라우저를 실제로 조작하며 전체 애플리케이션 플로우(인증, 페이지 이동, 폼 입력, 서버 연동)를 검증합니다.
+
+#### Vitest(단위 테스트) vs Playwright(E2E 테스트) 비교
+
+| 비교 항목 | Vitest + React Testing Library | Playwright (E2E) |
+|---|---|---|
+| **실행 환경** | Node.js + 가상 DOM (jsdom) | **실제 브라우저** (Chromium, Firefox, WebKit) |
+| **속도** | 초고속 (밀리초 단위) | 상대적으로 무거움 (수 초 ~ 수십 초) |
+| **검증 대상** | 개별 함수, 훅, 단일 컴포넌트 렌더링 로직 | 브라우저 렌더링, 실제 네트워크, 전체 사용자 시나리오 |
+| **주요 역할** | 회귀 방지, 비즈니스 계산/매퍼 검증 | 최종 배포 전 시스템 통합 동작 보증 |
+
+#### Playwright의 핵심 메커니즘
+1. **브라우저 컨텍스트 격리 (Browser Context Isolation)**:
+   - 새 브라우저 프로세스를 매번 띄우는 대신, 가벼운 브라우저 컨텍스트를 생성하여 테스트 간 쿠키/스토리지 오염 없이 100% 독립된 환경을 제공합니다.
+2. **자동 대기 (Auto-waiting)**:
+   - 요소를 클릭하거나 타이핑하기 전, 요소가 DOM에 부착(Attached), 표시(Visible), 활성화(Enabled), 애니메이션 정지 상태인지 자동으로 기다려 Flaky(불안정한) 테스트를 원천 차단합니다.
+3. **Web-first Assertions**:
+   - `expect(locator).toBeVisible()`과 같은 단언문은 조건이 충족될 때까지 지정된 시간(기본 5초) 동안 자동으로 재시도합니다.
+
+---
+
+### 5.2 Playwright 실행 명령어 치트시트
+
+`apps/cs` 폴더 또는 루트 디렉터리에서 실행합니다:
+
+```bash
+# 1. 헤드리스 모드로 전체 E2E 테스트 실행 (CLI 모드)
+pnpm --filter cs test:playwright
+
+# 2. 대화형 UI 모드 실행 (테스트 단계별 타임라인 탐색, 실시간 렌더링 시각화)
+pnpm --filter cs test:playwright:ui
+
+# 3. 브라우저 화면을 직접 보면서 실행 (--headed)
+pnpm --filter cs exec playwright test --headed
+
+# 4. 특정 테스트 파일만 지정 실행
+pnpm --filter cs exec playwright test tests/session-extend-confirm.spec.ts
+pnpm --filter cs exec playwright test tests/login.spec.ts
+
+# 5. 특정 브라우저(엔진)만 지정 실행
+pnpm --filter cs exec playwright test --project=chromium
+
+# 6. 코드젠 (Codegen): 브라우저 조작 시 테스트 코드를 자동 생성해주는 도구
+pnpm --filter cs exec playwright codegen http://localhost:3000
+
+# 7. 마지막 테스트 실행 결과 HTML 리포트 열기
+pnpm --filter cs exec playwright show-report
+```
+
+---
+
+### 5.3 테스트 작성 표준 패턴 및 베스트 프랙티스
+
+#### ① 권장 로케이터(Locator) 사용 순서
+Playwright는 사용자가 인지하는 방식을 반영하는 시맨틱 로케이터를 권장합니다:
+1. `page.getByRole('button', { name: '확인' })` (접근성 및 의미 기반 - 최우선 권장)
+2. `page.getByLabel('아이디')` (폼 레이블 기반)
+3. `page.getByPlaceholder('비밀번호를 입력하세요')`
+4. `page.getByText('저장되었습니다')`
+5. `page.locator('button.login_btn')` (CSS 선택자 - 최후의 수단)
+
+#### ② 표준 테스트 구조 예시
+```typescript
+import { test, expect } from "@playwright/test";
+
+test.describe("로그인 및 대시보드 플로우", () => {
+  test.beforeEach(async ({ page }) => {
+    // 1. 사전 진입
+    await page.goto("/auth/login");
+  });
+
+  test("아이디/비밀번호 입력 후 정상 대시보드로 이동해야 한다", async ({ page }) => {
+    // 2. 사용자 조작 (자동 대기 내장)
+    await page.getByPlaceholder("아이디").fill("admin");
+    await page.getByPlaceholder("비밀번호").fill("secret123!");
+    await page.getByRole("button", { name: "로그인" }).click();
+
+    // 3. Web-first 단언문
+    await expect(page).toHaveURL(/\/dashboard/);
+    await expect(page.getByText("관리자님 환영합니다")).toBeVisible();
+  });
+});
+```
+
+---
+
+### 5.4 프로젝트 설정 해설 (`playwright.config.ts`)
+
+`apps/cs/playwright.config.ts`의 주요 설정 포인트:
+- `testIgnore: "**/unit/**"`: Vitest로 실행되어야 할 jsdom 단위 테스트 파일이 중복 실행되지 않도록 격리.
+- `workers: 1` & `fullyParallel: false`: 공유 세션(Redis, DB)을 사용하는 통합 인증 테스트 간의 충돌 방지.
+- `webServer`: 테스트 실행 전 개발 서버(`http://localhost:3000`)가 구동되어 있지 않으면 자동으로 구동하여 테스트 완료 후 종료.
+- `trace: "retain-on-failure"`: 테스트가 실패한 경우에만 DOM 스냅샷, 콘솔 로그, 네트워크 요청이 담긴 Trace 파일을 저장하여 디버깅을 지원.
+
+---
+
+## 6. 검증 결과

 ### 1. Vitest 단위 테스트 결과
 터미널에서 `pnpm --filter cs run test:unit` 명령을 실행하여 모든 단위 테스트(총 13개)가 정상 통과함을 검증하였습니다:
@@ -88,3 +188,4 @@ Running 6 tests using 1 worker
 ```
 이로써 단위/통합 테스트 환경과 연장 처리 성공 후 중복 팝업 억제 시나리오가 포함된 E2E 테스트 환경 구축 임무가 성공적으로 완결되었습니다.

+