Playwright Test의 toHaveScreenshot()은 첫 실행 때 현재 페이지의 스크린샷을 캡처해 기준(Reference) 이미지로 저장합니다. 이후 실행부터는 pixelmatch 라이브러리가 현재 화면과 저장된 기준 이미지를 픽셀 단위로 비교해 시각적 차이를 검증하는 구조입니다.
toHaveScreenshot() 기본 동작: 첫 실행 기준 스크린샷 생성 원리
Playwright Test에서 await expect(page).toHaveScreenshot()을 호출하면 테스트 러너는 먼저 해당 테스트에 대응하는 기준 스냅샷 파일이 있는지 확인합니다.
최초 실행 시에는 비교할 대상인 골든 이미지(Golden Image)가 없어 Playwright는 현재 페이지의 스크린샷을 생성해 파일 시스템에 기준 스크린샷으로 저장합니다. 이후 실행에서는 이 기준 파일과 현재 렌더링된 화면을 비교합니다.
시각 비교 엔진: pixelmatch의 픽셀 단위 비교와 안정화 대기
Playwright의 시각 비교는 pixelmatch 라이브러리를 기반으로 합니다. 단순한 이미지 비교를 넘어 테스트의 신뢰성을 높이는 내부 메커니즘이 함께 작동합니다.
1. 페이지 안정화 대기 메커니즘
toHaveScreenshot()은 한 번의 캡처로 비교를 끝내지 않습니다. 이 함수는 연속된 두 페이지 스크린샷이 동일한 결과(same result)를 낼 때까지 대기하며, 최종적으로 일치하는 마지막 스크린샷을 기대값과 비교합니다. 페이지 내 동적 요소나 렌더링 지연이 만드는 거짓 양성(False Positive) 실패를 막기 위한 안정화 장치입니다.
2. 픽셀 비교 프로세스
안정화 단계가 끝나면 pixelmatch가 픽셀 단위 비교를 수행합니다. 캡처된 새 스크린샷의 각 픽셀을 기준 이미지와 대조하며, 픽셀 간 차이가 설정된 임계값(threshold)을 초과하면 테스트는 실패로 처리됩니다.
비교 허용치 조정: threshold, maxDiffPixels, maxDiffPixelRatio
시각 비교의 엄격함은 toHaveScreenshot()에 전달하는 옵션으로 조정합니다. 주요 옵션과 그 역할은 다음과 같습니다.
| 옵션명 | 설명 및 작동 원리 | 기본값 및 범위 |
|---|---|---|
| threshold | YIQ 색공간에서 동일 픽셀 간의 지각된 색 차이 허용치입니다. | 0(엄격) ~ 1(느슨), 기본값 0.2 |
| maxDiffPixels | 비교 시 허용 가능한 서로 다른 픽셀의 절대 개수입니다. | TestConfig.expect에서 설정 가능 |
| maxDiffPixelRatio | 전체 픽셀 수 대비 다른 픽셀이 차지하는 허용 비율입니다. | 0 ~ 1 범위 |
이 옵션들은 개별 테스트 호출 시 전달하거나, playwright.config.ts 내의 expect 설정으로 전역 또는 프로젝트 단위의 기본값을 지정할 수 있습니다.
기준 스크린샷 저장 규칙: 파일명과 형식
생성된 스냅샷은 정해진 명명 규칙에 따라 파일 시스템에 저장됩니다. 기본 형식은 PNG이며, WebP 무손실 형식도 지원합니다.
- 저장 경로: 스냅샷은
<테스트파일명>-snapshots디렉터리에 저장됩니다. - 파일명 구조:
[스냅샷-이름]-[브라우저명]-[플랫폼].png형식으로 생성됩니다.
- 예시:
example-test-1-chromium-darwin.png
- 플랫폼 구분 이유: 브라우저와 운영체제(플랫폼)마다 렌더링 결과가 달라지기 마련이라, Playwright는 환경별로 별도의 기준 파일을 만들어 관리합니다.
비교 실패 결과 해석: expected, actual, diff 이미지
시각 비교 결과가 임계값을 초과해 테스트가 실패하면 Playwright는 분석을 위해 세 가지 종류의 이미지를 생성합니다.
- Expected (기대 이미지): 파일 시스템에 저장되어 있던 기준(Reference) 스크린샷입니다.
- Actual (실제 이미지): 현재 테스트 실행에서 캡처된 실제 화면입니다.
- Diff (차이 이미지): 두 이미지의 차이점을 시각적으로 표시한 이미지입니다.
일관된 비교 환경: OS·하드웨어 영향과 제어 옵션
브라우저 렌더링은 다양한 외부 요인의 영향을 받습니다. 그래서 환경 일치가 필수입니다.
1. 렌더링에 영향을 주는 요인
아래 요소들이 변경되면 동일한 코드라도 스크린샷 결과가 달라지며, 비교 실패로 이어지기도 합니다.
- 호스트 OS 및 OS 버전
- 시스템 설정 및 하드웨어 구성
- 전원 상태 (배터리 사용 vs 전원 어댑터 연결)
- 헤드리스(Headless) 모드 여부
기준 스크린샷을 생성한 환경과 비교를 수행하는 환경이 같아야 일관된 결과가 나옵니다.
2. 결정성(Determinism)을 높이기 위한 옵션
환경 외에 페이지 내부의 동적 요소를 제어하는 옵션도 있습니다.
- mask: 특정 로케이터 요소를 지정하면 해당 영역이 핑크색 박스(
#FF00FF)로 덮여 비교 대상에서 제외됩니다. 마스크 색상은 v1.35부터maskColor옵션으로 바꿀 수 있습니다. - animations: 기본값은
'disabled'이며, CSS 애니메이션, 트랜지션, Web Animations를 정지시켜 스크린샷의 결정성을 높입니다. - 커스텀 스타일시트: 스크린샷 촬영 시점에 커스텀 스타일시트를 적용해 변동성이 큰 요소를 필터링하면 결정성이 한층 높아집니다.
기준 스크린샷 갱신: –update-snapshots 사용 시점과 절차
UI 변경으로 기존 기준 스크린샷이 더 이상 유효하지 않으면 새 화면을 기준으로 업데이트가 필요합니다.
이때는 CLI 명령에 --update-snapshots 플래그를 붙여 테스트를 실행합니다.
- 명령어:
npx playwright test --update-snapshots
이 플래그를 붙여 실행하면 Playwright는 현재 화면을 다시 캡처해 기존 기준 스냅샷 파일을 갱신합니다.