Playwright로 스크린샷 테스트를 하는 방법

Playwright 스크린샷 테스트는 배포 전에 잡아야 하는 UI 변화를 확인합니다. 테스트가 페이지를 열고 안정적인 상태까지 기다린 뒤 이미지를 캡처해 승인된 기준 이미지와 비교합니다. 이것이 일반 스크린샷 자동화와 시각 회귀 테스트의 차이입니다.

예제에서는 공개 대상인 Shotomatic 기능 페이지 https://www.shotomatic.com/features를 사용합니다. 데이터, 로그인 상태, 애니메이션, 테스트 선택자를 직접 제어할 수 있는 자체 앱에서는 같은 방식이 더 유용합니다.

URL 목록에서 이미지 파일만 필요하다면 일반 Playwright 스크린샷 자동화부터 확인하세요. 이 글은 기준 이미지, 스크린샷 비교, 브라우저 프로젝트, 검토를 다루는 테스트용 가이드입니다.

스크린샷 테스트를 쓸 가치가 있는 경우

일반 검증으로 놓치기 쉬운 시각 오류에 스크린샷 테스트가 유용합니다.

적합한 대상은 다음과 같습니다.

• 중요한 히어로, 가격, 가입 구간이 있는 마케팅 페이지
• 상태가 많은 디자인 시스템 컴포넌트
• 배치가 중요한 결제, 온보딩, 대시보드 화면
• 모바일 너비에서 자주 깨지는 반응형 페이지
• CSS 변경으로 콘텐츠가 조용히 이동하거나 숨을 수 있는 페이지

적합하지 않은 대상은 다음과 같습니다.

• 피드, 광고, 타임스탬프, 사용자 콘텐츠가 계속 바뀌는 페이지
• 시각적 완성도가 중요하지 않은 페이지
• 더 강력한 글, 역할, 동작 검증으로 이미 확인하는 절차
• 검토 절차 없이 불안정한 페이지가 수백 개 있는 사이트 전체

중요한 화면 몇 개부터 시작하세요. 모든 화면을 감시하도록 만들면 스크린샷 테스트에 불필요한 실패가 많아집니다.

Playwright Test를 설치합니다

새 Node 프로젝트나 기존 프로젝트에서 공식 Playwright 설치 프로그램으로 테스트 실행기, 구성 파일, 예제 테스트, 브라우저 설치 단계를 만들 수 있습니다.

$ npm init playwright@latest

설치 프로그램은 TypeScript 또는 JavaScript 사용 여부, 테스트 위치, GitHub Actions 자동화 추가 여부, 브라우저 설치 여부를 묻습니다. 설정 후 테스트를 실행하세요.

$ npx playwright test

이 글의 예제는 tests/ 아래 TypeScript 파일을 사용합니다.

첫 스크린샷 테스트를 만듭니다

tests/features-page.spec.ts를 만드세요.

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

test("features page has a stable desktop layout", async ({ page }) => {
  await page.goto("https://www.shotomatic.com/features");

  await expect(
    page.getByRole("heading", {
      name: /Shotomatic Features/i,
    }),
  ).toBeVisible();

  await expect(page).toHaveScreenshot("features-page-desktop.png", {
    fullPage: true,
  });
});

page.screenshot()과 가장 큰 차이는 검증입니다. Playwright Test의 toHaveScreenshot()은 기준 이미지를 만들거나 현재 이미지와 비교합니다. 첫 실행에서는 없는 기준 이미지를 만들고, 이후 실행에서는 현재 스크린샷과 저장된 이미지를 비교합니다.

테스트를 실행하세요.

$ npx playwright test tests/features-page.spec.ts

첫 실행에는 기준 이미지가 없으므로 Playwright가 새 예상 이미지를 만듭니다. 커밋하기 전에 검토하세요. 기준 이미지는 임의의 결과물이 아니라 테스트의 예상값입니다.

페이지의 작은 구간을 테스트합니다

전체 페이지 스크린샷은 큰 배치 변화를 잡지만 페이지 아래쪽의 관련 없는 변화 때문에 실패하기 쉽습니다. 많은 팀에서는 구간 또는 컴포넌트 기준 이미지가 관리하기 쉽습니다.

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

test("features comparison cards stay aligned", async ({ page }) => {
  await page.goto("https://www.shotomatic.com/features");

  const comparisonHeading = page.getByRole("heading", {
    name: /Choose a workflow/i,
  });
  const comparisonSection = page.locator("section").filter({
    has: comparisonHeading,
  });

  await expect(comparisonHeading).toBeVisible();
  await expect(comparisonSection).toHaveScreenshot("features-comparison-section.png");
});

검토 질문이 '이 구간이 여전히 제대로 보이나?'처럼 한 부분에 관한 것이라면 locator 스크린샷을 사용하세요. 페이지 전체 배치가 중요하다면 페이지 스크린샷을 사용합니다.

브라우저와 기기 프로젝트를 추가합니다

Playwright 테스트 실행기는 이름이 있는 여러 프로젝트에서 같은 테스트를 실행할 수 있습니다. 이때 스크린샷 테스트는 단순 캡처 스크립트와 달라집니다. 브라우저, 기기, 뷰포트, 스냅샷 이름이 모두 테스트 조합의 일부가 됩니다.

playwright.config.ts 예제입니다.

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

export default defineConfig({
  testDir: "./tests",
  use: {
    baseURL: "https://www.shotomatic.com",
    trace: "on-first-retry",
  },
  projects: [
    {
      name: "desktop-chromium",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 1440, height: 1000 },
      },
    },
    {
      name: "mobile-safari",
      use: {
        ...devices["iPhone 13"],
      },
    },
  ],
});

그런 다음 테스트에서 상대 URL을 사용합니다.

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

test("features page visual baseline", async ({ page }) => {
  await page.goto("/features");
  await expect(page.getByRole("main")).toBeVisible();

  await expect(page).toHaveScreenshot("features-page.png", {
    fullPage: true,
  });
});

Playwright는 프로젝트마다 다른 스냅샷을 저장합니다. 데스크톱과 모바일 기준 이미지를 억지로 같다고 가정하지 않고 나란히 둘 수 있습니다. 여러 기기 크기에서 UI가 작동하는지 확인할 때 뷰포트 스크린샷 하나보다 알맞습니다.

페이지 상태를 안정화합니다

불안정한 페이지 상태가 불필요한 스크린샷 실패를 많이 만듭니다. Playwright는 스크린샷 검증 중 CSS 애니메이션과 전환을 기본으로 비활성화하지만, 바뀌는 데이터, 지연 콘텐츠, 광고, 사용자별 요소는 여전히 픽셀을 움직일 수 있습니다.

스크린샷 전에 구체적인 조건을 기다리세요.

await page.goto("/features");
await expect(page.getByRole("main")).toBeVisible();
await expect(page.getByText("Hands-Free Capture")).toBeVisible();

고정 대기 시간을 주된 규칙으로 사용하지 마세요. 카드, 제목, 표 또는 로드된 이미지가 있어야 준비되는 페이지라면 그 조건을 직접 기다립니다.

화면 아래 콘텐츠를 지연 로딩한다면 전체 페이지 스크린샷 전에 스크롤하세요.

await page.evaluate(async () => {
  const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
  const viewportHeight = window.innerHeight;

  for (let y = 0; y < document.body.scrollHeight; y += viewportHeight) {
    window.scrollTo(0, y);
    await delay(100);
  }

  window.scrollTo(0, 0);
});

페이지에 필요하다면 이런 도우미를 써도 좋습니다. 나중에 관리하는 사람이 스크롤이 필요한 이유를 알 수 있도록 테스트 가까이에 두세요.

바뀌는 요소를 숨기거나 마스킹합니다

타임스탬프, 아바타, 광고, 사용자별 이름, 로딩 표시, 동영상 썸네일처럼 시각 비교에 참여하지 않아야 할 요소도 있습니다.

흔히 두 가지 방법을 사용합니다.

특정 locator를 마스킹합니다.

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  mask: [page.locator("[data-testid='release-date']")],
});

또는 스크린샷을 찍는 동안 스타일시트를 적용합니다.

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  stylePath: "./tests/screenshot.css",
});

tests/screenshot.css 예제입니다.

[data-testid="release-date"],
[data-testid="animated-cursor"] {
  visibility: hidden !important;
}

테스트를 통과시키려고 실제 제품 UI를 숨기지 마세요. 마스킹은 시각 질문에 포함되지 않는 불안정한 콘텐츠에만 사용합니다.

차이 임계값을 신중하게 설정합니다

Playwright는 제한된 픽셀 차이를 허용할 수 있습니다.

await expect(page).toHaveScreenshot("features-page.png", {
  fullPage: true,
  maxDiffPixels: 100,
});

작은 렌더링 차이에 유용하지만 실제 회귀를 숨길 수도 있습니다. 임계값을 낮게 유지하고 필요한 이유를 기록하며, 비교를 완화하기 전에 페이지를 더 결정적으로 만드는 편이 좋습니다.

playwright.config.ts에 스크린샷 검증 기본값을 공유할 수도 있습니다.

import { defineConfig } from "@playwright/test";

export default defineConfig({
  expect: {
    toHaveScreenshot: {
      maxDiffPixels: 100,
    },
  },
});

기준 이미지를 검토하고 업데이트합니다

스크린샷 테스트가 실패했을 때 물어야 할 것은 '어떻게 초록색으로 바꾸지?'가 아니라 '이 시각 변화가 예상된 것인가?'입니다.

버그라면 UI를 고치고 테스트를 다시 실행하세요. 의도된 변화라면 기준 이미지를 업데이트합니다.

$ npx playwright test --update-snapshots

그런 다음 풀 리퀘스트에서 새 기준 이미지를 검토하세요. 스냅샷 업데이트도 코드 변경처럼 취급합니다. 무엇이 왜 바뀌었는지 이해한 사람이 확인해야 합니다.

CI에서 스크린샷 테스트를 실행합니다

스크린샷 비교는 환경에 민감합니다. 글꼴, 운영체제, 브라우저 버전, 하드웨어, 헤드리스 모드가 픽셀에 영향을 줍니다. 안정적인 결과를 위해 같은 환경에서 기준 이미지를 만들고 비교하세요.

실제로는 보통 다음 원칙을 사용합니다.

• CI 또는 일치하는 로컬 컨테이너에서 만든 기준 스냅샷을 커밋
• 풀 리퀘스트에서 스크린샷 프로젝트 실행
• 차이를 예상한 것이 아니라면 macOS 기준 이미지를 Linux CI와 섞지 않기
• Playwright와 브라우저 바이너리를 의도적으로 업데이트
• 변경된 스냅샷을 승인하기 전에 검토

실패 원인을 이해하기 어렵다면 Playwright HTML 보고서나 추적 뷰어를 사용하세요. 실패한 스크린샷 테스트에는 빨간 빌드 표시보다 더 많은 검토 맥락이 필요합니다.

일반 스크린샷 자동화가 알맞은 경우

스크린샷 테스트는 코드로 관리하는 UI 품질 점검을 위한 것입니다. 검토, 보고, 보관, 콘텐츠 작업에 쓸 스크린샷을 수집하는 것과는 다른 일입니다.

URL에서 출력 파일이 필요하다면 일반 Playwright 스크린샷 자동화를 사용하세요.

작은 Chrome 중심 스크립트가 필요하고 Playwright Test가 필요하지 않다면 Puppeteer 스크린샷 자동화를 사용합니다.

테스트 모음을 관리하지 않고 URL을 추가하고, 캡처 옵션을 조정하고, 결과를 검토하고, 스크린샷을 내보내는 노코드 작업에는 Shotomatic Website Capture를 사용하세요. 반응형 스크린샷을 직접 검토하는 팀에는 충분할 수 있습니다. 자동 합격·불합격 테스트는 Playwright Test에 유지하세요.

자주 하는 실수

• 페이지를 너무 넓게 테스트: 전체 페이지 기준 이미지보다 중요한 구간부터 시작하세요.
• 불안정한 데이터 캡처: 실행마다 바뀌는 콘텐츠에는 고정 테스트 데이터, 마스크 또는 스타일을 사용하세요.
• 무작정 스냅샷 업데이트: 시각 차이를 검토한 뒤에만 기준 이미지를 업데이트하세요.
• 한 컴퓨터에서 기준 이미지를 만들고 다른 컴퓨터에서 비교: 렌더링 환경을 일관되게 유지하세요.
• 시각 테스트를 동작 테스트로 취급: 스크린샷과 함께 글, 역할, 탐색, 상호작용을 일반 검증으로 확인하세요.

자주 묻는 질문

Playwright로 스크린샷 테스트를 할 수 있나요?

그렇습니다. Playwright Test에는 expect(page).toHaveScreenshot() 및 expect(locator).toHaveScreenshot() 스크린샷 검증이 포함되어 있습니다.

스크린샷 테스트와 스크린샷 저장은 어떻게 다른가요?

스크린샷 저장은 이미지 파일을 만듭니다. 스크린샷 테스트는 새 이미지를 승인된 기준 이미지와 비교하고 차이가 허용 임계값을 넘으면 테스트를 실패시킵니다.

Playwright는 스크린샷 기준 이미지를 어디에 저장하나요?

기본적으로 테스트 파일 이름에 -snapshots가 붙은 디렉터리에 저장합니다. Playwright 구성의 snapshotPathTemplate로 경로를 바꿀 수 있습니다.

Playwright 스크린샷 기준 이미지는 어떻게 업데이트하나요?

시각 변화가 의도된 것인지 검토한 뒤 --update-snapshots 플래그로 Playwright Test를 실행하세요.

모든 페이지에 Playwright 스크린샷 테스트를 써야 하나요?

아닙니다. 중요하고 안정적인 UI 상태에 사용하세요. 동작은 일반 검증으로 확인하고, 배치 변화가 중요한 페이지나 컴포넌트에만 시각 기준 이미지를 사용합니다.

참고 자료

위 예제는 다음 현재 공식 문서를 기준으로 확인했습니다.

• Playwright Test 설정은 Playwright 설치 가이드를 참고했습니다.
• toHaveScreenshot(), 기준 이미지, 업데이트 과정, 비교 옵션은 Playwright 시각 비교 가이드를 참고했습니다.
• fullPage, mask, stylePath, maxDiffPixels, threshold 및 관련 옵션은 Playwright PageAssertions.toHaveScreenshot() API를 참고했습니다.
• 자동 재시도 웹 검증은 Playwright 검증 가이드를 참고했습니다.
• 실패한 테스트 검토는 Playwright 테스트 실행 및 디버깅 가이드와 추적 뷰어 가이드를 참고했습니다.