---
name: E2E Testing (Playwright)
description: A guide for writing E2E tests using Playwright
---

# E2E Testing with Playwright

이 스킬은 **Playwright**를 사용하여 End-to-End(E2E) 테스트를 작성하고 실행하는 방법을 안내합니다.

## 1. Playwright 특징
- **모든 브라우저 지원**: Chromium, Firefox, WebKit
- **자동 대기 (Auto-waiting)**: 엘리먼트가 준비될 때까지 자동으로 대기합니다.
- **강력한 셀렉터**: 텍스트, 접근성 레이블 등으로 쉽게 요소를 찾을 수 있습니다.

## 2. 테스트 파일 위치
- 보통 `e2e` 폴더 또는 `tests` 폴더에 위치합니다.
- 파일명 규칙: `[scenario].spec.ts`

## 3. 기본 테스트 구조
```typescript
import { test, expect } from '@playwright/test';

test('user login flow', async ({ page }) => {
  // 1. 페이지 이동
  await page.goto('/login');

  // 2. 상호작용 (Locators 활용)
  await page.getByLabel('Email').fill('user@example.com');
  await page.getByLabel('Password').fill('password123');
  await page.getByRole('button', { name: 'Sign in' }).click();

  // 3. 검증 (Assertions)
  await expect(page).toHaveURL('/dashboard');
  await expect(page.getByText('Welcome, User')).toBeVisible();
});
```

## 4. MCP Server 활용 (AI Agent 전용)
- 이 프로젝트는 **Playwright MCP Server**가 설정되어 있을 수 있습니다.
- AI 에이전트는 이를 통해 브라우저를 직접 제어하고 테스트를 수행할 수 있습니다.
- **주의**: 로컬 서버(`localhost:3000` 등)가 실행 중이어야 테스트가 가능합니다.

## 5. Best Practices
- **Locators 우선순위**:
  1. `getByRole` (접근성, 사용자 관점)
  2. `getByText` (텍스트 내용)
  3. `getByTestId` (불가피한 경우 `data-testid` 속성 사용)
  - **CSS/XPath 셀렉터는 가급적 지양**하세요. (깨지기 쉬움)
- **독립적인 테스트**: 각 테스트는 새로운 브라우저 컨텍스트(쿠키/스토리지 초기화됨)에서 실행됩니다.
- **인증 처리**: 반복적인 로그인은 `global-setup` 또는 `storageState`를 활용하여 재사용하세요.

> [!IMPORTANT]
> **요구사항 기반 E2E 시나리오**: E2E 테스트는 사용자의 실제 시나리오와 비즈니스 요구사항을 검증하는 도구입니다. 코드가 어떻게 작성되었는지보다, 사용자가 목표를 달성할 수 있는지(PRD 기준)를 중점적으로 테스트 시나리오를 설계하세요.

## 6. 실행 방법
- UI 모드 (디버깅용): `npx playwright test --ui`
- Headless 모드 (CI용): `npx playwright test`
- 특정 파일: `npx playwright test tests/login.spec.ts`