Playwright 브라우저 설치와 관리

Playwright는 매 버전마다 특정 버전의 브라우저 바이너리가 필요해요. 브라우저를 설치하고, 원하는 엔진을 골라 테스트를 돌리고, 프록시나 회사 내부 아티팩트 저장소 같은 환경까지 다루다 보면 자연스럽게 "브라우저는 어떻게 관리되는 거지?"라는 질문이 떠오르죠. 여기서는 설치부터 환경 변수로 위치를 바꾸는 방법까지, 브라우저 관리의 전체 흐름을 하나씩 짚어 볼게요.

출처: Playwright 공식 문서 — Browsers

본문

브라우저 설치하기

Playwright는 자체 지원 브라우저를 설치해 줘요. 아무 인자 없이 명령을 실행하면 기본 브라우저들이 설치돼요.

npx playwright install

특정 브라우저만 골라서 설치할 수도 있어요.

npx playwright install webkit

지원하는 브라우저 전체 목록을 보려면 --help를 붙이면 돼요.

npx playwright install --help

시스템 의존성 설치

브라우저가 쓰는 시스템 라이브러리는 install-deps로 자동 설치할 수 있어요. CI 환경에서 특히 유용하죠.

npx playwright install-deps

단일 브라우저만 골라 의존성을 설치할 수도 있고,

npx playwright install-deps chromium

브라우저와 OS 의존성을 한 번에 설치하려면 --with-deps를 쓰면 돼요.

npx playwright install --with-deps chromium

Playwright를 정기적으로 업데이트하기

Playwright 버전을 최신으로 유지하면 새 기능도 쓰고, 애플리케이션을 최신 브라우저 버전에서 테스트해서 공개 릴리스 전에 실패를 잡을 수 있어요.

# Update playwright
npm install -D @playwright/test@latest

# Install new browsers
npx playwright install

현재 버전은 --version으로 확인할 수 있어요.

npx playwright --version

브라우저 구성하기

Playwright는 Chromium·WebKit·Firefox뿐 아니라 Google Chrome, Microsoft Edge 같은 상표 브라우저에서도 테스트할 수 있어요. 태블릿·모바일 에뮬레이션도 지원하고요. config에 projects를 잡으면 하나의 테스트를 여러 브라우저와 구성으로 돌릴 수 있어요.

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

export default defineConfig({
  projects: [
    /* Test against desktop browsers */
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    /* Test against mobile viewports. */
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
    /* Test against branded browsers. */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // or 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // or 'msedge-dev'
    },
  ],
});

기본적으로 모든 project가 실행돼요. 특정 project만 돌리려면 --project 옵션을 쓰면 됩니다.

npx playwright test --project=firefox

Chromium

Google Chrome·Microsoft Edge 같은 Chromium 계열에서는 기본적으로 오픈소스 Chromium 빌드를 써요. Chromium 프로젝트가 상표 브라우저보다 앞서 있기 때문에, 세상이 Google Chrome N일 때 Playwright는 몇 주 뒤에 릴리스될 Chromium N+1을 이미 지원하고 있어요.

헤드리스로만 테스트한다면(channel 미지정) 설치 시 --only-shell을 넘겨 전체 Chromium을 내려받지 않을 수도 있어요.

npx playwright install --with-deps --only-shell

새 헤드리스 모드를 쓰려면 channel: 'chromium'을 지정하면 돼요. 공식 문서에 따르면 이 새 헤드리스는 진짜 Chrome 브라우저라 더 정확하고 신뢰도가 높고 기능도 많아서, 정밀한 엔드투엔드 테스트나 브라우저 확장 테스트에 더 적합해요.

Google Chrome & Microsoft Edge

브랜디드 브라우저는 기본 설치되지 않지만, 설치되어 있다면 그 위에서 동작할 수 있어요. 사용 가능한 채널로는 chrome, msedge, chrome-beta, msedge-beta, chrome-dev, msedge-dev, chrome-canary, msedge-canary가 있어요.

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

export default defineConfig({
  projects: [
    /* Test against branded browsers. */
    {
      name: 'Google Chrome',
      use: { ...devices['Desktop Chrome'], channel: 'chrome' }, // or 'chrome-beta'
    },
    {
      name: 'Microsoft Edge',
      use: { ...devices['Desktop Edge'], channel: 'msedge' }, // or "msedge-beta" or 'msedge-dev'
    },
  ],
});

언제 공식 브라우저를 써야 할까

기본 설정: 대부분은 최신 Chromium이 기본 구성으로 충분해요. Playwright가 Stable 채널보다 앞서 있어서 곧 릴리스될 Chrome·Edge가 내 사이트를 깨뜨리지 않을지 미리 잡아 주거든요.
회귀 테스트: 정책상 현재 공개 브라우저를 대상으로 회귀 테스트를 요구한다면 "chrome"이나 "msedge" 같은 stable 채널을 쓰면 돼요.
미디어 코덱: Chromium은 라이선스 문제로 Google Chrome이나 Edge가 번들하는 일부 코덱을 포함하지 않아요. 사이트가 그런 코덱에 의존한다면 공식 채널이 필요할 수 있어요.
엔터프라이즈 정책: Chrome·Edge는 기업 정책(능력 제한, 네트워크 프록시, 필수 확장 등)을 따르는데, 이것이 테스트를 방해할 수 있어요. 조직이 그런 정책을 쓴다면 로컬 테스트는 번들 Chromium이 편하고, 봇 쪽은 정책이 없는 사정이 보통이라 stable 채널을 선택할 수 있어요.

Firefox와 WebKit

Playwright의 Firefox는 최근 Firefox Stable 빌드와 맞추고, WebKit은 최신 WebKit main 브랜치에서 파생돼요. 둘 다 패치에 의존하기 때문에 브랜디드 버전(Safari나 Firefox 정식판)에서는 동작하지 않는다는 점을 알아 두세요. Linux에서는 Linux, macOS, Windows 간에 미디어 코덱 같은 기능 가용성이 달라질 수 있어요. WebKit을 Safari에 가장 가깝게 테스트하려면 macOS에서 돌리는 게 좋아요.

방화벽이나 프록시 뒤에서 설치하기

기본적으로 브라우저는 Microsoft CDN에서 받아요. 내부 프록시가 공용 리소스를 막는 환경이라면 HTTPS_PROXY 변수로 프록시를 지정해 설치할 수 있어요.

HTTPS_PROXY=https://192.0.2.1 npx playwright install

프록시의 인증서가 자체 서명이라 self signed certificate in certificate chain 오류가 난다면, 설치 전에 NODE_EXTRA_CA_CERTS로 커스텀 루트 인증서를 지정해야 해요.

다운로드가 느리거나 멈추면 PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT(기본 30초, 밀리초 단위)으로 유휴 타임아웃을 늘릴 수 있어요. 이름은 connection timeout이지만 실제로는 데이터가 오지 않아도 되는 최대 대기 시간이에요.

PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install

아티팩트 저장소에서 내려받기

회사 내부 아티팩트 저장소에 브라우저를 호스팅한다면 PLAYWRIGHT_DOWNLOAD_HOST로 다운로드 위치를 바꿀 수 있어요. 브라우저별로 다르게 지정하려면 PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST, PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST, PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST를 쓰고, 이 값이 PLAYWRIGHT_DOWNLOAD_HOST보다 우선해요.

PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=http://203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=http://192.0.2.1 npx playwright install

미리 설치된 Node.js 사용하기

Playwright는 기본적으로 번들된 Node.js로 브라우저 설치·스크립트 실행을 처리해요. 특정 Node.js 버전이 필요하거나 번들 런타임이 맞지 않는 환경이라면 PLAYWRIGHT_NODEJS_PATH로 미리 설치된 바이너리를 지정할 수 있어요.

PLAYWRIGHT_NODEJS_PATH="/usr/local/bin/node" npx playwright install

브라우저 바이너리 관리

설치되는 브라우저는 OS별 캐시 폴더에 저장돼요.

Windows: %USERPROFILE%\AppData\Local\ms-playwright
macOS: ~/Library/Caches/ms-playwright
Linux: ~/.cache/ms-playwright

설치하면 수백 메가바이트의 디스크를 차지합니다.

du -hs ~/Library/Caches/ms-playwright/*
281M  chromium-XXXXXX
187M  firefox-XXXX
180M  webkit-XXXX

위치를 바꾸고 싶다면 PLAYWRIGHT_BROWSERS_PATH로 설치·검색 경로를 지정할 수 있어요.

PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install

함께 쓰면 브라우저가 필요 없는 패키지 보고 오래된 버전은 자동으로 가비지 컬렉션됩니다. 더 이상 클라이언트가 요구하지 않는 브라우저 버전은 시스템에서 삭제돼요. 이 제거를 끄려면 PLAYWRIGHT_SKIP_BROWSER_GC=1을 설정하거나 --no-remove 옵션을 쓰면 됩니다.

npx playwright install --no-remove

헤르메틱 설치 (hermetic install)

PLAYWRIGHT_BROWSERS_PATH=0으로 두면 바이너리를 로컬 폴더에 설치해요.

# Places binaries to node_modules/playwright-core/.local-browsers
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install

설치 목록 보기와 제거

설치된 브라우저 목록은 install --list로, 제거는 uninstall로 해요.

npx playwright install --list
npx playwright uninstall

다른 Playwright 설치의 브라우저까지 모두 제거하려면 --all 플래그를 붙이면 됩니다.

npx playwright uninstall --all

Playwright 브라우저 설치와 관리