Puppeteer

Puppeteer는 브라우저를 제어하는 고수준 API를 제공하는 오픈 소스 Node.js 라이브러리입니다. 자동 스크린샷, 테스트, 웹 스크래핑에 널리 쓰입니다.

Puppeteer로 할 수 있는 일

Puppeteer는 Chrome DevTools Protocol과 WebDriver BiDi를 통해 지원 브라우저를 코드로 제어합니다. 사용자가 브라우저에서 하는 대부분의 작업과 자동화에만 가능한 작업을 실행합니다.

주요 기능은 다음과 같습니다.

• 페이지 이동 — URL을 열고 특정 네트워크 상태나 DOM 요소를 기다리며 리디렉션과 인증을 처리합니다.
• 스크린샷 캡처 — 페이지를 PNG, JPEG, WebP로 저장하고 현재 뷰포트나 스크롤 가능한 전체 페이지를 찍습니다.
• PDF 생성 — 페이지 크기, 여백, 머리글·바닥글을 지정해 렌더링한 페이지를 PDF로 내보냅니다.
• DOM 조작 — 요소를 클릭하고 양식을 채우며 드롭다운을 고르고 글자를 입력합니다. 캡처 전에 사용자 조작이 필요한 흐름을 자동화할 때 씁니다.
• 네트워크 가로채기 — 네트워크 요청을 감시하거나 수정하거나 막습니다. 오류 상태 시험, 광고 차단, 리소스 크기 측정에 사용합니다.
• JavaScript 실행 — 페이지 컨텍스트에서 JavaScript를 실행해 데이터를 추출하고 캡처 전에 DOM을 바꿉니다.

실제 브라우저 엔진을 제어하므로 CSS 레이아웃, 웹 글꼴, 애니메이션, JavaScript 콘텐츠를 포함한 렌더링 결과를 캡처합니다.

스크린샷에 Puppeteer 사용하기

스크린샷은 가장 흔한 사용 사례 중 하나입니다. page.screenshot() 메서드로 결과를 세밀하게 제어합니다.

뷰포트 크기와 기기 배율을 정해 스마트폰부터 4K 모니터까지 원하는 화면을 흉내 낼 수 있습니다. fullPage 옵션은 현재 보이는 영역뿐 아니라 스크롤 가능한 문서 전체를 캡처합니다. clip 영역으로 특정 직사각형만 찍을 수도 있습니다.

지연 로딩 페이지에서는 캡처 전에 스크롤해 모든 이미지를 활성화할 수 있습니다. 쿠키 배너와 팝업을 코드로 닫고, 스크린샷에 넣지 않을 요소를 숨기는 CSS도 주입할 수 있습니다.

스크린샷 도구와 API는 내부에서 Puppeteer나 비슷한 라이브러리를 사용해 이런 기능을 더 단순한 화면으로 제공하기도 합니다. 사용자는 브라우저 자동화 코드를 직접 쓰지 않고 페이지를 캡처합니다.

Chrome 중심 작업에서는 뷰포트, 대기 조건, 출력 형식을 한곳에 정하고 같은 스크립트를 감사, 보고서, 일정 캡처에 재사용할 수 있습니다. 브라우저가 스크린샷을 찍어야 하는 요구를 빠르게 코드로 옮기는 도구입니다.

Puppeteer와 Playwright 비교

두 라이브러리는 대표적인 헤드리스 브라우저 자동화 도구이며 많은 기능이 겹칩니다.

브라우저 지원이 가장 큰 차이입니다. 최신 Puppeteer는 Chrome for Testing과 안정판 Firefox를 지원합니다. Playwright는 Chromium 계열, Firefox, WebKit을 일관된 API로 지원해 WebKit 캡처까지 다룹니다.

API 설계는 비슷하지만 Playwright는 요소 동작 전 자동 대기와 격리된 브라우저 컨텍스트를 중심 기능으로 제공합니다. Puppeteer에서도 대기 조건과 브라우저 컨텍스트를 구성할 수 있으며 필요한 동작을 명시적으로 적는 경우가 많습니다.

성능은 대부분의 작업에서 비슷하고 실제 차이는 페이지와 실행 환경에 좌우됩니다. 속도만 가정하지 말고 대상 작업으로 측정하세요.

커뮤니티와 생태계 — Puppeteer는 더 오래 사용돼 플러그인과 튜토리얼 자료가 많습니다. Playwright는 교차 엔진 지원이 필요한 새 프로젝트에서 널리 선택됩니다.

흔한 실수

• 페이지 콘텐츠를 기다리지 않습니다. page.goto() 직후 page.screenshot()을 호출하면 덜 로드된 화면이 찍힐 수 있습니다. waitUntil: 'networkidle0'이나 특정 선택자 대기로 렌더링 완료 조건을 정하세요.
• 기본 뷰포트를 그대로 씁니다. 기본 800x600은 실제 화면 대부분과 맞지 않습니다. 정확한 고해상도 결과를 위해 뷰포트 크기와 기기 배율을 명시하세요.
• 쿠키 동의 배너를 무시합니다. 자동 캡처는 페이지를 처음 방문한 상태로 엽니다. 동의 오버레이를 닫지 않으면 콘텐츠 대신 배너가 찍힙니다.
• 서버에서 창이 보이는 모드를 사용합니다. 디스플레이가 없는 서버에서 headed 모드를 켜면 실패할 수 있습니다. 서버와 CI에서는 헤드리스 모드를 사용하세요.
• 페이지 이동 오류를 처리하지 않습니다. 페이지는 시간 초과, 오류 응답, 예상 밖 리디렉션을 일으킬 수 있습니다. 한 페이지 실패로 전체 스크립트가 중단되지 않도록 이동과 캡처 호출의 오류를 처리하세요.