BackstopJS로 시각적 회귀 테스트 구축 및 자동화 경험 공유

기존 유료 서비스(Percy, Chromatic 등) 대신 무료 오픈소스인 BackstopJS를 선택한 이유는 변경 전후 이미지를 겹쳐 동시에 비교할 수 있는 기능과 비용 효율성 때문이다. 이 도구는 크롬 헤드리스 브라우저와 Puppeteer를 활용해 렌더링된 UI를 캡처하고, 저장된 기준 이미지와 비교하여 달라진 영역을 시각적으로 표시한다.

설정 및 실행 프로세스

backstop init으로 초기화한 후 backstop.json 또는 커스텀 JS 파일(backstop.config.js)에서 시나리오를 관리한다. 복잡한 설정을 모듈화하기 위해 JS 파일 사용을 권장하며, 모든 명령어 실행 시 --config 옵션을 명시해야 한다. 첫 실행 전 backstop reference로 기준 이미지를 생성하고, 이후 backstop test로 변경 사항을 검증한다. 테스트 실패 시 backstop approve를 통해 새로운 이미지를 기준점으로 업데이트한다.

Docker 환경 구축의 필요성

로컬 환경에서는 폰트 렌더링 차이 등으로 인해 코드 변경이 없어도 테스트가 실패하는 경우가 발생한다. 이를 해결하기 위해 Docker 컨테이너 내에서 Headless Chromium을 실행하여 일관된 환경을 보장한다. Alpine Linux 기반 이미지에서는 Chromium과 관련 라이브러리(nss, freetype 등)를 수동으로 설치해야 하며, Puppeteer의 실행 경로를 지정해야 한다. 또한, 테스트 속도를 최적화하기 위해 asyncCaptureLimit와 asyncCompareLimit 값을 조정할 수 있다.

CI/CD 연동 및 활용

Git push 시 스토리북 프리뷰 서버 생성 도커파일에 Backstop 테스트 스크립트를 추가하여 자동화한다. 테스트 결과 HTML 리포트는 프리뷰 서버 URL(.../backstop_data/html_report/)로 접근 가능하도록 설정하여, PR 리뷰 시 시각적 변경 사항을 즉시 확인할 수 있게 한다. 특히 스토리북의 Organism 단위 컴포넌트 테스트에 효과적이며, 동적 요소 제외(hideSelectors)나 허용 오차 범위(mismatchThreshold) 설정을 통해 유연하게 대응할 수 있다.