<div id="readability-page-1" class="page"><div id="SE-ef7bbb14-0dc2-4818-93a5-6df3e1bd7126">
 트러블슈팅 리포트: Playwright VRT 1px 규격 오차 해결
1. 문제 현상 (Problem)
<ul><li>PR 생성 후 GitHub Actions(Ubuntu Linux) 환경에서 실행된 Playwright 시각적 회귀 테스트(VRT)가 실패함.
</li><li>에러 메시지: Expected an image 375px by 1287px, received 375px by 1288px.
</li><li>특이사항: 이전에 전역 overflow-x: hidden을 제거하여 가로 30px 팽창 버그를 해결하고, maxDiffPixelRatio 옵션으로 폰트 안티앨리어싱 색상 오차를 해결해 CI를 통과시켰던 상태였음. 그러나 순수 마크다운(docs) 파일들을 정리하여 커밋한 이후, 갑자기 1px의 높이 규격 불일치 에러가 발생하기 시작함.
</li></ul>2. 원인 분석 (Root Cause Analysis)
치명적인 에러의 원인은 의도치 않은 Baseline 오염과 OS 간 렌더링 한계의 결합이었습니다.
<ul><li>마크다운 작업 중 Baseline 의도치 않은 업데이트
</li><li>문서 통합 작업을 진행하면서 로컬(Mac) 환경에서 알 수 없는 이유(실수 혹은 환경 변화)로 footer-baseline-Mobile-Safari-Min-Width-.png 스냅샷 파일이 갱신되었고, 이것이 마크다운 파일들과 함께 git push 되었습니다.
</li><li>OS 간 물리적 1px 높이 불일치 (규격 불일치)
</li><li>새롭게 올라간 로컬(Mac) 기준 이미지의 높이는 1287px이었으나, CI(Linux)가 렌더링한 화면의 높이는 1288px이었습니다.
</li><li>이는 Mac(CoreText)과 Linux(FreeType)의 폰트 서브 픽셀 반올림 차이 및 브라우저 기본 스크롤바 렌더링 두께 차이 등이 누적되어 만들어낸 1px의 물리적 격차입니다.
</li><li>maxDiffPixelRatio 옵션의 한계
</li><li>이 옵션은 두 이미지의 가로x세로 픽셀 크기가 "완벽히 동일할 때" 내부의 픽셀 색상 오차만을 눈감아 주는 기능입니다. 따라서 이미지의 높이 자체가 1px 달라지면 해당 옵션은 무시되고 즉시 에러가 발생합니다.
</li></ul>3. 해결 과정 (Resolution)
에러를 임시로 회피하는 것이 아니라, 렌더링 변수를 원천 차단하는 방향으로 아키텍처를 고도화했습니다.
Step 1. 잘못된 접근 방지 (maxDiffPixels 제거)
<ul><li>처음엔 maxDiffPixels: 1 옵션을 추가하여 1px의 크기 차이를 무시하려 했으나, 이 옵션은 크기가 아니라 '내부 픽셀 색상이 다른 점의 개수'를 의미한다는 것을 파악하고 불필요한 설정을 즉시 제거했습니다.
</li></ul>Step 2. 렌더링 변수 원천 통제 (스크롤바 비활성화 CSS 주입)
<ul><li>OS마다 스크롤바를 렌더링하는 방식과 공간 차지 비율이 달라 레이아웃이 1px씩 틀어지는 현상을 방지하기 위해, Playwright 테스트 실행 시에만 강제로 주입되는 CSS 파일(screenshot-spec.css)을 생성했습니다.
</li><li>css /* e2e/screenshot-spec.css */ ::-webkit-scrollbar{display: none!important;} *{scrollbar-width: none!important;-ms-overflow-style: none!important;} 
</li></ul>Step 3. 관심사 분리(SoC)를 통한 프로젝트 구조 최적화
<ul><li>처음에는 CSS 파일을 tests/ 폴더에 생성했으나, 프로젝트의 Playwright 기본 진입점이 testDir: './e2e'로 설정되어 있음을 확인했습니다.
</li><li>단위 테스트(Jest)와 E2E(Playwright) 환경의 리소스가 섞이는 것을 방지하기 위해, CSS 파일을 e2e/screenshot-spec.css로 이동시켜 설정을 완벽히 캡슐화했습니다.
</li></ul>Step 4. 기준점(Baseline) 클린 갱신 및 쓰레기 파일 청소
<ul><li>기존에 스크롤바가 포함된 채로 찍혔던 낡은 스냅샷 폴더(snapshots)들을 모두 삭제했습니다.
</li><li>이를 통해 더 이상 사용하지 않는 쓰레기(Orphan) 스냅샷 파일들을 대청소함과 동시에, 스크롤바가 숨겨진 새로운 렌더링 환경을 바탕으로 pnpm run test:e2e:update를 실행하여 오염되지 않은 완벽한 기준점을 일괄 재생성했습니다.
</li></ul>4. 결론 및 성과 (Conclusion &amp; Impact)
<ul><li>크로스 플랫폼 VRT 한계 극복: 단순히 픽셀 색상 차이를 무시하는 수준(maxDiffPixelRatio)을 넘어, 스크롤바 간섭으로 인한 '물리적 1px 규격 틀어짐'이라는 치명적인 OS 렌더링 변수를 통제하는 데 성공했습니다.
</li><li>테스트 환경 최적화 및 용량 다이어트: VRT 전용 CSS 리소스를 e2e 폴더 내에 캡슐화하여 아키텍처의 관심사를 명확히 분리했고, 잔여 스냅샷 찌꺼기들을 싹 지우고 재정비함으로써 Repository 관리 효율을 높였습니다.
</li><li>견고해진 CI 파이프라인: 이제 로컬(Mac)에서 편하게 스냅샷을 찍어 올려도 CI(Ubuntu)에서 무의미한 UI 테스트 실패가 발생하지 않으며, 온전히 코드 품질에만 집중할 수 있는 완벽한 초록불(Pass) 파이프라인이 정립되었습니다.
</li></ul>​
​

 </div></div>

Dev-JeromeBaek.

트러블슈팅 리포트: Playwright VRT 1px 규격 오차 해결 1. 문제 현상 (Problem) PR 생성 후 GitHub Actions(Ubuntu Linux) 환경에서 실행된 Playwright 시각적 회귀 테스트(VRT)가 실패함. 에러 메시지: Expected an image 375px by 1287px, received 375px by 1288px. 특이사항: 이전에 전역 overflow-x: hidden을 제거하여 가로 30px 팽창 버그를 해결하고, maxDiffPixelRatio 옵션으로 폰트 안티앨리어싱 색상 오차를 해결해 CI를 통과시켰던 상태였음. 그러나 순수 마크다운(docs) 파일들을 정리하여 커밋한 이후, 갑자기 1px의 높이 규격 불일치 에러가 발생하기 시작함. 2. 원인 분석 (Root Cause Analysis) 치명적인 에러의 원인은 의도.......

[Error_Playwright] - Playwright VRT 트러블슈팅 (2): 세로 1px 미세 오차 원천 차단 및 스크롤바 렌더링 통제

댓글