CI에서 OpenScreenShot CLI를 사용해 실행 중인 애플리케이션의 PNG를 저장하고 검토하세요. Chrome 호환 브라우저를 준비하고, 애플리케이션을 시작해 준비될 때까지 기다린 뒤, 고정된 URL과 뷰포트로 캡처하세요. 결과 파일은 CI 제공업체의 아티팩트 기능으로 업로드하세요.

환경을 반복 가능하게 만들기

이미 pnpm을 사용하는 프로젝트라면 CLI를 개발 의존성으로 추가하고, 그에 따른 매니페스트와 lockfile 변경 사항을 커밋하세요.

pnpm add -D -E openscreenshot

CI에서는 프로젝트의 고정된 lockfile로 의존성을 설치하세요. 이 패키지는 puppeteer-core를 사용하며 브라우저를 다운로드하지 않으므로, 러너에 Chrome이나 Chromium도 있어야 합니다. 실행 파일이 지원되는 기본 위치에 없다면 CHROME_PATH를 설정하세요.

캡처를 비교할 때는 브라우저 버전, 글꼴, 뷰포트, 애플리케이션 데이터, 패키지 버전을 일정하게 유지하세요. 애플리케이션 코드가 바뀌지 않았더라도 글꼴이나 브라우저 렌더러가 바뀌면 이미지가 달라질 수 있습니다.

애플리케이션이 준비된 뒤 캡처하기

프로젝트 자체의 명령으로 개발 서버나 미리보기 서버를 시작하세요. 이 예제를 실행하기 전에 해당 경로와 그 의존 요소가 준비될 때까지 기다리세요. 포트 4321은 예시일 뿐이며 애플리케이션에 맞게 바꿔야 합니다.

mkdir -p artifacts
pnpm exec openscreenshot shot http://127.0.0.1:4321 --out artifacts/desktop.png --width 1440 --height 900
pnpm exec openscreenshot shot http://127.0.0.1:4321 --out artifacts/narrow.png --width 390 --height 844

이 명령은 뷰포트 캡처를 만듭니다. 페이지 전체를 검토하려면 --full을 추가하세요. CI 아티팩트 업로드 단계에 artifacts/ 디렉터리를 지정하면, 검토자가 풀 리퀘스트나 릴리스와 함께 파일을 열어 볼 수 있습니다.

CLI는 페이지 이동 중에 네트워크 유휴 상태를 기다리지만, 이것이 애플리케이션 고유의 작업이 끝났다는 보장은 아닙니다. 설정 가능한 선택자 대기나 주입할 설정 스크립트도 없습니다. 일반 경로에 애니메이션, 변하는 콘텐츠, 인증이 있다면 결정적인 데이터를 쓰는 안정적인 검토 전용 경로를 사용하세요.

캡처된 이미지는 통과한 시각 테스트가 아닙니다

이 명령은 서버 오류나 로딩 화면의 스크린샷을 찍은 뒤에도 성공으로 종료될 수 있습니다. PNG는 검토용 결과물로 취급하세요. 시각적 회귀 테스트 시스템에는 기준 이미지, 이미지 비교 방법, 임곗값, 의도한 변경을 승인하는 절차도 필요합니다. OpenScreenShot CLI는 이런 요소를 제공하지 않습니다.

좁은 스크린샷은 반응형 레이아웃을 점검하는 데 유용하지만 모바일 기기 에뮬레이션은 아닙니다. 마찬가지로 스크린샷은 상호작용, 접근성, API 동작을 검증하지 않습니다. 캡처 단계와 함께 애플리케이션에 필요한 검사를 유지하세요.

파이프라인 문제 해결

Chrome을 찾을 수 없음: 러너 이미지에 브라우저가 포함되어 있고 CHROME_PATH가 그 실행 파일을 가리키는지 확인하세요.

페이지 이동 실패 또는 시간 초과: 캡처 프로세스에서 서버에 접근할 수 있는지, 서버가 예상한 포트를 사용하는지, 캡처를 시작하기 전에 준비되었는지 확인하세요. 페이지 이동의 제한 시간은 30초입니다.

예상치 못한 로그인 페이지가 나타남: CLI는 새 브라우저 세션을 시작합니다. 로컬 프로필을 재사용하지 않으며 쿠키 주입도 제공하지 않습니다.

출력 파일이 없음: 출력 디렉터리를 만들고, 명령의 종료 상태를 확인하고, CI 작업 디렉터리를 기준으로 아티팩트 경로를 확인하세요.

플래그와 종료 코드는 CLI 레퍼런스 가이드에서 다룹니다. 다음에 어떤 페이지를 확인할지 사람이나 에이전트가 정해야 한다면 MCP 스크린샷 작업 흐름을 사용하세요.