2026년 Playwright로 E2E 테스트 자동화 완벽 가이드

• 자동 대기 기능 - 요소가 나타날 때까지 알아서 기다려줘요
• 병렬 실행 - 테스트 속도가 진짜 빨라요
• 네트워크 제어 - API 응답을 모킹하거나 가로챌 수 있어요
• 스크린샷 & 비디오 - 실패한 테스트를 영상으로 볼 수 있죠
• 타입스크립트 완벽 지원 - 자동완성이 정말 좋아요

node --version
npm --version

npm init playwright@latest

# 또는 yarn 사용하시는 분들은
yarn create playwright

# pnpm 사용자라면
pnpm create playwright

• TypeScript 사용 - 타입 안정성 때문에 무조건 Yes예요
• 테스트 폴더명 - 기본값 'tests'로 그냥 두시면 돼요
• GitHub Actions - CI/CD 쓸 거면 Yes, 아니면 나중에 추가해도 괜찮아요
• 브라우저 설치 - Yes 눌러서 자동으로 다운받게 하세요

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30 * 1000,
  expect: {
    timeout: 5000
  },
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  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'] },
    },
  ],
});

처음 설치할 때 브라우저 다운로드 시간이 좀 걸려요. Chrome, Firefox, WebKit 세 개를 다 받으면 약 1GB 정도 되거든요. 와이파이 좋은 곳에서 설치하시는 게 정신건강에 이로워요!

# 모든 테스트 실행
npx playwright test

# UI 모드로 실행 (시각적으로 보면서 테스트)
npx playwright test --ui

# 특정 브라우저만 테스트
npx playwright test --project=chromium

# 헤드 모드로 실행 (브라우저 창 띄워서)
npx playwright test --headed

import { test, expect } from '@playwright/test';

test('홈페이지 타이틀 확인하기', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  
  // 페이지 타이틀이 'Playwright'를 포함하는지 확인
  await expect(page).toHaveTitle(/Playwright/);
});

test('Get started 링크 클릭 테스트', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  
  // 링크 클릭
  await page.getByRole('link', { name: 'Get started' }).click();
  
  // URL이 변경되었는지 확인
  await expect(page).toHaveURL(/.*intro/);
});

import { test, expect } from '@playwright/test';

test.describe('로그인 기능 테스트', () => {
  test.beforeEach(async ({ page }) => {
    // 모든 테스트 전에 로그인 페이지로 이동
    await page.goto('https://example.com/login');
  });

  test('정상적인 로그인이 성공하는지 확인', async ({ page }) => {
    // 이메일 입력
    await page.getByLabel('이메일').fill('user@example.com');
    
    // 비밀번호 입력
    await page.getByLabel('비밀번호').fill('password123');
    
    // 로그인 버튼 클릭
    await page.getByRole('button', { name: '로그인' }).click();
    
    // 대시보드로 리다이렉트 되었는지 확인
    await expect(page).toHaveURL(/.*dashboard/);
    
    // 환영 메시지가 보이는지 확인
    await expect(page.getByText('환영합니다')).toBeVisible();
  });

  test('잘못된 비밀번호로 로그인 실패 테스트', async ({ page }) => {
    await page.getByLabel('이메일').fill('user@example.com');
    await page.getByLabel('비밀번호').fill('wrongpassword');
    await page.getByRole('button', { name: '로그인' }).click();
    
    // 에러 메시지가 표시되는지 확인
    await expect(page.getByText('이메일 또는 비밀번호가 올바르지 않습니다')).toBeVisible();
    
    // 여전히 로그인 페이지에 있는지 확인
    await expect(page).toHaveURL(/.*login/);
  });

  test('필수 항목 미입력시 유효성 검사', async ({ page }) => {
    // 아무것도 입력하지 않고 로그인 버튼 클릭
    await page.getByRole('button', { name: '로그인' }).click();
    
    // 유효성 검사 메시지 확인
    await expect(page.getByText('이메일을 입력해주세요')).toBeVisible();
  });
});

1. 모든 테스트 실행: npx playwright test
2. 특정 파일만 실행: npx playwright test login.spec.ts
3. UI 모드로 실행 (2026년 완전 추천!): npx playwright test --ui
4. 헤드 모드로 실행 (브라우저 보면서): npx playwright test --headed
5. 디버그 모드: npx playwright test --debug
6. 특정 브라우저만: npx playwright test --project=chromium

처음 테스트를 작성할 때 흔히 하는 실수가 있어요. 너무 빠르게 다음 액션으로 넘어가는 거예요. 예를 들어, 버튼을 클릭했는데 API 응답이 오기도 전에 다음 검증을 하려고 하면 테스트가 실패할 수 있어요. Playwright는 자동으로 기다려주긴 하지만, 복잡한 상황에서는 명시적으로 waitForLoadState() 같은 걸 써주는 게 안전해요.

가끔 API 응답이 느리거나, 애니메이션이 있는 경우 기본 타임아웃으로는 부족할 수 있어요. 이럴 때는 이렇게 해보세요:

// 특정 assertion에만 타임아웃 설정
await expect(page.getByText('로딩 완료')).toBeVisible({ timeout: 10000 });

// 테스트 전체에 타임아웃 설정
test('느린 테스트', async ({ page }) => {
  test.setTimeout(60000); // 60초
  // ... 테스트 코드
});

test('API 에러 상황 테스트', async ({ page }) => {
  // API 요청을 가로채서 커스텀 응답 반환
  await page.route('**/api/users', route => {
    route.fulfill({
      status: 500,
      contentType: 'application/json',
      body: JSON.stringify({ error: 'Server Error' })
    });
  });

  await page.goto('/users');
  
  // 에러 메시지가 제대로 표시되는지 확인
  await expect(page.locator('.error-message')).toBeVisible();
});

test('메인 페이지 시각적 테스트', async ({ page }) => {
  await page.goto('/');
  
  // 전체 페이지 스크린샷 비교
  await expect(page).toHaveScreenshot('homepage.png');
  
  // 특정 요소만 비교
  await expect(page.locator('.header')).toHaveScreenshot('header.png', {
    maxDiffPixels: 100  // 100픽셀 이하 차이는 허용
  });
});

import { test } from '@playwright/test';

test('커버리지와 함께 테스트', async ({ page }) => {
  // 커버리지 수집 시작
  await page.coverage.startJSCoverage();
  
  await page.goto('/');
  await page.click('button');
  
  // 커버리지 데이터 수집
  const coverage = await page.coverage.stopJSCoverage();
  
  // 커버리지 퍼센트 계산
  let totalBytes = 0;
  let usedBytes = 0;
  
  for (const entry of coverage) {
    totalBytes += entry.text.length;
    for (const range of entry.ranges) {
      usedBytes += range.end - range.start - 1;
    }
  }
  
  console.log(`커버리지: ${(usedBytes / totalBytes * 100).toFixed(2)}%`);
});

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry', // 재시도 시에만 trace 수집
    // 또는
    trace: 'retain-on-failure', // 실패한 테스트만 trace 유지
  },
});

import { test, devices } from '@playwright/test';

test.use({
  ...devices['iPhone 14 Pro'],
});

test('모바일 메뉴 테스트', async ({ page }) => {
  await page.goto('/');
  
  // 햄버거 메뉴가 보이는지 확인
  await expect(page.locator('.mobile-menu-icon')).toBeVisible();
  
  // 터치 제스처 테스트
  await page.locator('.mobile-menu-icon').tap();
  await expect(page.locator('.menu-drawer')).toBeVisible();
});

test('위치 기반 기능 테스트', async ({ page, context }) => {
  // 위치 권한 부여
  await context.grantPermissions(['geolocation']);
  
  // 서울 좌표로 설정
  await context.setGeolocation({ 
    latitude: 37.5665, 
    longitude: 126.9780 
  });
  
  await page.goto('/nearby-stores');
  
  // 서울 근처 매장이 표시되는지 확인
  await expect(page.locator('.store-name')).toContainText('강남점');
});

test('드래그 앤 드롭 파일 업로드', async ({ page }) => {
  await page.goto('/upload');
  
  // 파일 드롭 시뮬레이션
  const buffer = Buffer.from('테스트 파일 내용');
  const dataTransfer = await page.evaluateHandle(() => {
    const dt = new DataTransfer();
    const file = new File(['테스트 파일 내용'], 'test.txt', { 
      type: 'text/plain' 
    });
    dt.items.add(file);
    return dt;
  });
  
  await page.dispatchEvent('.dropzone', 'drop', { dataTransfer });
  
  // 파일 다운로드 대기 및 검증
  const downloadPromise = page.waitForEvent('download');
  await page.click('#download-button');
  const download = await downloadPromise;
  
  // 다운로드된 파일명 확인
  expect(download.suggestedFilename()).toBe('test.txt');
});

test('실시간 채팅 메시지 수신', async ({ page }) => {
  await page.goto('/chat');
  
  // WebSocket 연결 대기
  const wsPromise = page.waitForEvent('websocket', ws => {
    return ws.url().includes('chat-server');
  });
  
  await page.click('#connect-button');
  const ws = await wsPromise;
  
  // WebSocket 메시지 모니터링
  const messagePromise = new Promise(resolve => {
    ws.on('framereceived', event => {
      const data = JSON.parse(event.payload);
      if (data.type === 'message') {
        resolve(data.content);
      }
    });
  });
  
  // 메시지 전송
  await page.fill('#message-input', '안녕하세요');
  await page.click('#send-button');
  
  // 응답 메시지 확인
  const response = await messagePromise;
  expect(response).toBeTruthy();
});

// pages/LoginPage.ts
export class LoginPage {
  constructor(private page: Page) {}

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.page.getByLabel('이메일').fill(email);
    await this.page.getByLabel('비밀번호').fill(password);
    await this.page.getByRole('button', { name: '로그인' }).click();
  }

  async getErrorMessage() {
    return await this.page.locator('.error-message').textContent();
  }
}

// tests/login.spec.ts
import { LoginPage } from '../pages/LoginPage';

test('로그인 실패 테스트', async ({ page }) => {
  const loginPage = new LoginPage(page);
  await loginPage.goto();
  await loginPage.login('wrong@email.com', 'wrongpass');
  
  const error = await loginPage.getErrorMessage();
  expect(error).toContain('이메일 또는 비밀번호가 올바르지 않습니다');
});

CSS 클래스나 XPath는 진짜 최후의 수단으로만 쓰세요. 디자인이 바뀌면 테스트가 바로 깨지거든요. 제가 처음에 이거 몰라서 테스트 100개가 한번에 깨진 적 있어요. 정말 끔찍했죠...

import { test } from '@playwright/test';

test.beforeEach(async ({ page }) => {
  // 각 테스트마다 새로운 사용자로 로그인
  await page.goto('/login');
  await page.getByLabel('이메일').fill(`test-${Date.now()}@example.com`);
  await page.getByLabel('비밀번호').fill('password123');
  await page.getByRole('button', { name: '로그인' }).click();
  await page.waitForURL('/dashboard');
});

test.afterEach(async ({ page, request }) => {
  // 테스트에서 생성한 데이터 정리
  await request.delete('/api/test-cleanup');
});

test('게시글 작성 테스트', async ({ page }) => {
  // 이 테스트는 다른 테스트와 완전히 독립적이에요
  await page.getByRole('button', { name: '새 게시글' }).click();
  // ...
});

// playwright.config.ts
export default defineConfig({
  use: {
    // 실패 시 스크린샷 자동 저장
    screenshot: 'only-on-failure',
    
    // 실패한 테스트만 비디오 녹화
    video: 'retain-on-failure',
    
    // 추적 파일도 실패 시에만
    trace: 'retain-on-failure',
  },
  
  // 테스트에서 수동으로 찍기
  test('중요한 단계 캡처', async ({ page }) => {
    await page.goto('/checkout');
    
    // 결제 전 상태 캡처
    await page.screenshot({ 
      path: 'screenshots/before-payment.png',
      fullPage: true 
    });
    
    await page.getByRole('button', { name: '결제하기' }).click();
    
    // 결제 후 상태 캡처
    await page.screenshot({ 
      path: 'screenshots/after-payment.png' 
    });
  })
});

// .env 파일 (절대 Git에 커밋하지 마세요!)
TEST_USER_EMAIL=test@example.com
TEST_USER_PASSWORD=secure_password_123
API_BASE_URL=https://api.example.com
API_TOKEN=your_api_token_here

// tests/utils/config.ts
export const config = {
  testUser: {
    email: process.env.TEST_USER_EMAIL!,
    password: process.env.TEST_USER_PASSWORD!,
  },
  api: {
    baseUrl: process.env.API_BASE_URL!,
    token: process.env.API_TOKEN!,
  }
};

// tests/login.spec.ts
import { config } from './utils/config';

test('로그인 테스트', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('이메일').fill(config.testUser.email);
  await page.getByLabel('비밀번호').fill(config.testUser.password);
  await page.getByRole('button', { name: '로그인' }).click();
});

스토리지 상태 재사용이 진짜 효과 좋아요. 매번 로그인 플로우를 거치는 대신, 한 번 로그인한 상태를 저장해서 다른 테스트에서 재사용하는 거예요. 저희 팀은 이거 적용하고 테스트 실행 시간이 15분에서 5분으로 줄었어요. 완전 게임체인저였죠!

// global-setup.ts
async function globalSetup() {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  
  // 로그인 수행
  await page.goto('/login');
  await page.getByLabel('이메일').fill('test@example.com');
  await page.getByLabel('비밀번호').fill('password123');
  await page.getByRole('button', { name: '로그인' }).click();
  
  // 로그인 상태 저장
  await page.context().storageState({ 
    path: 'auth.json' 
  });
  
  await browser.close();
}

// playwright.config.ts
export default defineConfig({
  globalSetup: './global-setup.ts',
  use: {
    // 저장된 로그인 상태 사용
    storageState: 'auth.json',
  },
});

name: Playwright Tests
on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 20
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v4
      if: always()
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 30

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shardIndex: [1, 2, 3, 4]
        shardTotal: [4]
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 20
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
    - uses: actions/upload-artifact@v4
      if: always()
      with:
        name: playwright-report-${{ matrix.shardIndex }}
        path: playwright-report/
        retention-days: 30

e2e-tests:
  image: mcr.microsoft.com/playwright:v1.42.0-jammy
  stage: test
  script:
    - npm ci
    - npx playwright test
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 1 week
  only:
    - main
    - merge_requests

    - name: Deploy to GitHub Pages
      if: failure()
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./playwright-report
        destination_dir: reports/${{ github.run_id }}

    - name: Run Playwright tests
      run: npx playwright test
      env:
        BASE_URL: ${{ secrets.STAGING_URL }}
        API_KEY: ${{ secrets.API_KEY }}
        TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
        TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}

GitHub Actions에서 PR이 fork된 저장소에서 온 경우, 시크릿에 접근할 수 없어요. 보안 때문이죠. 이럴 땐 pull_request_target 이벤트를 쓰거나, 오픈소스 프로젝트라면 테스트 데이터를 public하게 만들어야 해요.

// playwright.config.ts
export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  reporter: [
    ['html'],
    ['junit', { outputFile: 'results.xml' }],
    ['github'], // GitHub Actions 전용
  ],
});

• ✅ 브라우저와 의존성 자동 설치 설정
• ✅ 테스트 실패 시 스크린샷/비디오 저장
• ✅ HTML 리포트 artifact 업로드
• ✅ 병렬 실행으로 속도 최적화
• ✅ 환경 변수와 시크릿 안전하게 관리
• ✅ 불안정한 테스트에 대한 재시도 설정
• ✅ PR에 테스트 결과 자동 코멘트

on:
  push:
    paths:
      - 'src/**'
      - 'tests/**'
      - 'package.json'
      - 'playwright.config.ts'