헤드리스 브라우저

헤드리스 브라우저는 화면에 사용자 인터페이스를 띄우지 않고 실행되는 웹 브라우저입니다. 스크린샷 캡처, 테스트 실행, 웹 콘텐츠 수집 같은 작업을 코드로 자동화할 때 사용합니다.

헤드리스 브라우저의 작동 방식

헤드리스 브라우저는 Chrome, Firefox, Safari에서 페이지를 그리는 코드와 같은 완전한 브라우저 엔진을 그래픽 창 없이 실행합니다. HTML을 불러오고 JavaScript를 실행하며 CSS를 적용해 눈에 보이는 브라우저와 같은 방식으로 페이지를 렌더링합니다. 결과를 모니터 대신 화면 밖 버퍼로 보낸다는 점만 다릅니다.

보통 Chrome과 Chromium용 Puppeteer나 Chromium, Firefox, WebKit용 Playwright 같은 라이브러리로 헤드리스 브라우저를 제어합니다. 스크립트 하나로 URL을 열고 콘텐츠가 로드되기를 기다린 다음 페이지를 조작하고 스크린샷을 찍습니다. 사람이 마우스나 키보드를 건드릴 필요가 없습니다.

GUI를 띄우는 비용이 없어 메모리 사용을 줄일 수 있고, 디스플레이가 없는 서버, CI 파이프라인, 컨테이너 환경에서도 실행할 수 있습니다.

헤드리스 브라우저를 쓰는 곳

• 자동 스크린샷 — 제품 페이지, 마케팅 사이트, 문서, 경쟁사 페이지처럼 많은 웹페이지의 시각적 기록을 코드로 캡처합니다.
• 시각적 회귀 테스트 — 코드 변경 전후의 스크린샷을 비교해 의도하지 않은 UI 차이를 찾습니다.
• 웹 스크래핑 — 단순한 HTTP 요청만으로 접근하기 어려운 JavaScript 중심 페이지를 불러온 뒤 렌더링된 콘텐츠를 추출합니다.
• PDF 생성 — 웹페이지를 브라우저에 보이는 레이아웃 그대로 렌더링해 PDF 문서로 내보냅니다.
• 성능 테스트 — 화면에 브라우저 창을 띄우지 않고 페이지 로딩 시간, 리소스 크기, 렌더링 성능을 측정합니다.

헤드리스 캡처와 창을 띄운 캡처

눈에 보이는 브라우저로 스크린샷을 찍는 방법은 단순하지만 수동 작업입니다. 페이지를 열고 창 크기를 맞춘 뒤 Mac에서는 Cmd+Shift+3, Windows에서는 Win+Shift+S를 누릅니다. 한두 번 찍을 때는 충분하지만 규모를 늘리기 어렵습니다.

헤드리스 캡처는 코드로 제어합니다. 스크립트 하나가 여러 뷰포트 크기로 수백 페이지를 차례로 또는 병렬로 캡처할 수 있습니다. 모니터가 없는 서버에서 실행하고 CI/CD 파이프라인에 연결할 수 있으며 누가 실행해도 일정한 결과를 냅니다.

렌더링 결과는 거의 같습니다. 다만 데스크톱에 설치된 글꼴이 헤드리스 환경에는 없을 수 있고, GPU 가속 기능이 소프트웨어 렌더링으로 바뀔 수 있습니다. 애니메이션을 원하는 순간에 찍으려면 명시적으로 기다리는 로직도 필요합니다.

이 일관성이 스크린샷 작업에서 헤드리스 브라우저가 중요한 이유입니다. 뷰포트, DPR, 대기 조건, 쿠키 처리를 코드로 정하면 모든 캡처가 같은 절차를 따릅니다. 서로 다른 노트북에서 수동으로 만든 스크린샷보다 비교하고 게시하며 신뢰하기 쉽습니다.

흔한 실수

• 콘텐츠가 로드되기를 기다리지 않습니다. 헤드리스 브라우저는 빠르게 실행됩니다. 페이지를 연 직후 캡처하면 지연 로딩 이미지, 웹 글꼴, 비동기 콘텐츠가 아직 그려지지 않았을 수 있습니다. 캡처 전에 선택자, 네트워크 유휴 상태, 특정 요소를 기다리는 조건을 명시하세요.
• 뷰포트와 기기 픽셀 비율을 무시합니다. 헤드리스 모드의 기본 뷰포트는 800x600처럼 작은 경우가 많습니다. 원하는 결과에 맞춰 뷰포트 크기와 기기 배율을 명시하세요.
• 글꼴을 빠뜨립니다. 서버 환경에는 데스크톱에 설치된 글꼴이 없을 수 있습니다. 대체 글꼴로 표시되면 글자 모양과 배치가 달라집니다. 필요한 글꼴을 설치하거나 해당 글꼴이 들어 있는 Docker 이미지를 사용하세요.
• 쿠키 배너와 팝업을 처리하지 않습니다. 자동 캡처는 페이지를 새 방문자처럼 엽니다. 스크립트에서 동의 창과 팝업을 닫지 않으면 콘텐츠 대신 오버레이가 찍힙니다.