Playwright E2E 테스트 자동화 실전 가이드 — 설치부터 CI/CD 통합까지

Playwright 설치 및 초기화
# 신규 프로젝트 초기화 (이미 있으면 스킵)
npm init -y

# Playwright 설치 — 브라우저 바이너리도 함께 다운로드
npm init playwright@latest

# 설치 중 선택지:
# ? Do you want to use TypeScript or JavaScript? → TypeScript
# ? Where to put your end-to-end tests? → tests
# ? Add a GitHub Actions workflow? → true
# ? Install Playwright browsers? → true

설치 후 디렉토리 구조
my-project/
├── playwright.config.ts    ← 브라우저·타임아웃·리포터 설정
├── tests/
│   └── example.spec.ts     ← 예제 테스트
├── tests-examples/
│   └── demo-todo-app.spec.ts
└── .github/
    └── workflows/
        └── playwright.yml  ← CI 워크플로우 (자동 생성)

playwright.config.ts — 실무 설정 예시
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  // 병렬 실행 — CI에서는 워커 수를 제한
  fullyParallel: true,
  workers: process.env.CI ? 2 : undefined,

  // 실패 시 재시도 (flaky 테스트 대응)
  retries: process.env.CI ? 2 : 0,

  // 리포터: CI에서는 HTML + JUnit, 로컬은 list
  reporter: process.env.CI
    ? [['html', { open: 'never' }], ['junit', { outputFile: 'results.xml' }]]
    : 'list',

  use: {
    // 개발 서버 주소
    baseURL: 'http://localhost:3000',
    // 실패 시 스크린샷·트레이스 자동 저장
    screenshot: 'only-on-failure',
    trace: 'on-first-retry',
  },

  // 테스트 전에 dev 서버 자동 실행
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
    // 모바일 뷰포트 테스트
    { name: 'mobile-chrome', use: { ...devices['Pixel 7'] } },
  ],
});

tests/login.spec.ts — 로그인 플로우 테스트
import { test, expect } from '@playwright/test';

test.describe('로그인 플로우', () => {
  test('올바른 자격증명으로 대시보드에 진입', async ({ page }) => {
    // 1. 로그인 페이지로 이동
    await page.goto('/login');

    // 2. 폼 입력 — getByLabel로 접근성 기반 셀렉터 사용
    await page.getByLabel('이메일').fill('user@example.com');
    await page.getByLabel('비밀번호').fill('securePassword123');

    // 3. 로그인 버튼 클릭
    await page.getByRole('button', { name: '로그인' }).click();

    // 4. 대시보드 도달 확인
    await expect(page).toHaveURL('/dashboard');
    await expect(page.getByRole('heading', { name: '대시보드' })).toBeVisible();
  });

  test('잘못된 비밀번호로 에러 메시지 표시', async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('이메일').fill('user@example.com');
    await page.getByLabel('비밀번호').fill('wrong');
    await page.getByRole('button', { name: '로그인' }).click();

    // 에러 메시지가 보이는지 확인
    await expect(page.getByText('이메일 또는 비밀번호가 올바르지 않습니다')).toBeVisible();
    // URL은 여전히 로그인 페이지
    await expect(page).toHaveURL('/login');
  });
});

테스트 실행 명령어
# 전체 테스트 실행
npx playwright test

# 특정 파일만 실행
npx playwright test tests/login.spec.ts

# 특정 브라우저만 실행
npx playwright test --project=chromium

# UI 모드로 실행 (브라우저 동작을 눈으로 확인)
npx playwright test --ui

# 디버그 모드 (한 줄씩 실행하며 확인)
npx playwright test --debug

tests/pages/login.page.ts — Page Object
import { type Page, type Locator, expect } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('이메일');
    this.passwordInput = page.getByLabel('비밀번호');
    this.submitButton = page.getByRole('button', { name: '로그인' });
    this.errorMessage = page.getByRole('alert');
  }

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

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }

  async expectError(message: string) {
    await expect(this.errorMessage).toContainText(message);
  }
}

Page Object를 사용한 테스트 리팩토링
import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/login.page';

test.describe('로그인 플로우', () => {
  let loginPage: LoginPage;

  test.beforeEach(async ({ page }) => {
    loginPage = new LoginPage(page);
    await loginPage.goto();
  });

  test('올바른 자격증명으로 대시보드 진입', async ({ page }) => {
    await loginPage.login('user@example.com', 'securePassword123');
    await expect(page).toHaveURL('/dashboard');
  });

  test('잘못된 비밀번호 에러', async () => {
    await loginPage.login('user@example.com', 'wrong');
    await loginPage.expectError('이메일 또는 비밀번호가 올바르지 않습니다');
  });
});

API 응답 모킹 예시
import { test, expect } from '@playwright/test';

test('상품 목록이 정상 렌더링된다', async ({ page }) => {
  // /api/products 요청을 가로채서 가짜 데이터 반환
  await page.route('**/api/products', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify([
        { id: 1, name: 'MacBook Pro 16', price: 3490000 },
        { id: 2, name: 'LG 울트라파인 32UN880', price: 890000 },
      ]),
    });
  });

  await page.goto('/products');

  // 모킹된 데이터가 렌더링되었는지 확인
  await expect(page.getByText('MacBook Pro 16')).toBeVisible();
  await expect(page.getByText('LG 울트라파인 32UN880')).toBeVisible();
});

test('API 에러 시 에러 화면이 표시된다', async ({ page }) => {
  await page.route('**/api/products', async (route) => {
    await route.fulfill({ status: 500 });
  });

  await page.goto('/products');
  await expect(page.getByText('잠시 후 다시 시도해주세요')).toBeVisible();
});

인증 상태 저장 및 재사용 (global setup)
// tests/auth.setup.ts
import { test as setup, expect } from '@playwright/test';

const authFile = 'playwright/.auth/user.json';

setup('로그인 후 인증 상태 저장', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('이메일').fill('user@example.com');
  await page.getByLabel('비밀번호').fill('securePassword123');
  await page.getByRole('button', { name: '로그인' }).click();

  // 대시보드 도달 확인 후 상태 저장
  await expect(page).toHaveURL('/dashboard');
  await page.context().storageState({ path: authFile });
});

// playwright.config.ts에 추가
// projects: [
//   { name: 'setup', testMatch: /.*\.setup\.ts/ },
//   {
//     name: 'chromium',
//     use: {
//       ...devices['Desktop Chrome'],
//       storageState: 'playwright/.auth/user.json',
//     },
//     dependencies: ['setup'],
//   },
// ]

.github/workflows/playwright.yml
name: Playwright E2E Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  e2e:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run E2E tests
        run: npx playwright test

      - name: Upload test report
        uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14

Trace Viewer 사용법
# 트레이스를 켜고 테스트 실행
npx playwright test --trace on

# CI에서 다운로드한 trace.zip 열기
npx playwright show-trace trace.zip

# 또는 온라인 뷰어 사용
# trace.playwright.dev에 zip 파일 드래그 앤 드롭

HTML 리포트 열기
# 테스트 실행 후 리포트 열기
npx playwright show-report