💻 오늘의 코드 팁 — Playwright로 절대 깨지지 않는 E2E 테스트 작성하기

문제

E2E 테스트의 가장 큰 적은 flaky test(불안정한 테스트)다.
```javascript
// ❌ 전통적인 방식 — sleep으로 기도하기
await page.goto('/dashboard');
await page.waitForTimeout(3000); // 🙏 3초면 되겠지...
await page.click('#submit-btn');
await page.waitForTimeout(2000);
const text = await page.$eval('.result', el => el.textContent);
assert(text === 'Success');
```
`waitForTimeout`은 느린 환경에서 실패하고, 빠른 환경에서 시간 낭비다. CI에서 랜덤으로 깨지는 주범.
---

해결 — Playwright Auto-Wait + 시맨틱 Locator

Playwright는 모든 액션에 auto-wait가 내장되어 있다. 요소가 visible, stable, enabled 상태가 될 때까지 자동으로 기다린다.

1. 설치 & 설정

```bash
# 프로젝트 초기화
npm init playwright@latest
# 브라우저 설치
npx playwright install
```
`playwright.config.ts`:
```typescript
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
retries: process.env.CI ? 2 : 0,
use: {
baseURL: 'http://localhost:3000',
trace: 'on-first-retry', // 실패 시 트레이스 자동 저장
screenshot: 'only-on-failure',
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'mobile', use: { ...devices['iPhone 14'] } },
],
webServer: {
command: 'npm run dev',
port: 3000,
reuseExistingServer: !process.env.CI,
},
});
```

2. 시맨틱 Locator로 테스트 작성

```typescript
import { test, expect } from '@playwright/test';
test('회원가입 → 대시보드 진입', async ({ page }) => {
await page.goto('/signup');
// ✅ role 기반 locator — DOM 구조 변경에도 안정적
await page.getByRole('textbox', { name: '이메일' }).fill('test@example.com');
await page.getByRole('textbox', { name: '비밀번호' }).fill('SecureP@ss123');
await page.getByRole('button', { name: '가입하기' }).click();
// ↑ click() 호출 시 버튼이 visible + enabled 될 때까지 자동 대기
// ✅ 페이지 전환 후 요소 확인 — 자동으로 navigation 대기
await expect(page.getByRole('heading', { name: '대시보드' })).toBeVisible();
// ✅ 비동기 데이터 로딩 대기 — polling 기반 자동 재시도
await expect(page.getByTestId('user-stats')).toContainText('가입 완료');
});
```

3. API Mocking으로 외부 의존성 제거

```typescript
test('결제 실패 시 에러 메시지 표시', async ({ page }) => {
// API 응답을 가로채서 실패 시나리오 테스트
await page.route('**/api/payment', route =>
route.fulfill({
status: 402,
contentType: 'application/json',
body: JSON.stringify({ error: '카드 한도 초과' }),
})
);
await page.goto('/checkout');
await page.getByRole('button', { name: '결제하기' }).click();
// 에러 토스트가 나타날 때까지 자동 대기 (기본 5초)
await expect(page.getByRole('alert')).toContainText('카드 한도 초과');
});
```

4. 디버깅 — Trace Viewer

```bash
# 테스트 실행 + 트레이스 수집
npx playwright test --trace on
# 실패한 테스트의 트레이스 열기
npx playwright show-trace test-results/trace.zip
```
Trace Viewer에서 각 액션의 스크린샷, 네트워크 요청, 콘솔 로그를 타임라인으로 확인할 수 있다.
---

핵심 정리

| 안티패턴 ❌ | Playwright 방식 ✅ |
|---|---|
| `waitForTimeout(3000)` | auto-wait (액션마다 자동 대기) |
| `page.$('#btn')` CSS 셀렉터 | `getByRole('button')` 시맨틱 locator |
| 외부 API 직접 호출 | `page.route()` 로 mock |
| `console.log` 디버깅 | `--trace on` + Trace Viewer |
| 단일 브라우저 테스트 | `projects`로 멀티 브라우저/디바이스 |

왜 Playwright인가?

Auto-wait: `sleep` 없이도 flaky test 거의 0

시맨틱 Locator: `getByRole`, `getByText`, `getByTestId` — CSS 셀렉터보다 리팩토링에 강함

멀티 브라우저: Chromium, Firefox, WebKit 동시 테스트

Trace Viewer: 실패 원인을 영상처럼 리플레이

API Mocking: 외부 서비스 없이 모든 시나리오 테스트

📎 [Playwright 공식 문서](https://playwright.dev/docs/intro) | [Best Practices](https://playwright.dev/docs/best-practices) | [Auto-waiting 원리](https://playwright.dev/docs/actionability) | [GitHub](https://github.com/microsoft/playwright)