From 454b9e474fcf5da2ec44314a7a944432335b44db Mon Sep 17 00:00:00 2001 From: jangwoong Date: Tue, 22 Sep 2026 17:40:00 +0900 Subject: [PATCH] =?UTF-8?q?[common]=20playwright=20=ED=85=8C=EC=8A=A4?= =?UTF-8?q?=ED=8A=B8=20=EC=82=AC=EC=9A=A9=EB=B2=95=20=EC=B6=94=EA=B0=80?= =?UTF-8?q?=ED=95=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/cs/tests/unit/walkthrough.md | 103 +++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/apps/cs/tests/unit/walkthrough.md b/apps/cs/tests/unit/walkthrough.md index 12cb1c01b..3a0429acd 100644 --- a/apps/cs/tests/unit/walkthrough.md +++ b/apps/cs/tests/unit/walkthrough.md @@ -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 테스트 환경 구축 임무가 성공적으로 완결되었습니다. +