[2026] Puppeteer 완벽 가이드 | 웹 스크래핑·자동화·PDF 생성·테스트·실전 활용

· 14분 읽기 · 수정 중급
[2026] Puppeteer 완벽 가이드 | 웹 스크래핑·자동화·PDF 생성·테스트·실전 활용

이 글의 핵심

Puppeteer로 웹 자동화를 구현하는 완벽 가이드입니다. 스크래핑, 스크린샷, PDF 생성, 폼 자동화, 테스트까지 실전 예제로 정리했습니다.

실무 경험 공유: 수동 데이터 수집을 Puppeteer로 자동화하면서, 작업 시간이 10시간에서 10분으로 단축된 경험을 공유합니다.

들어가며: “수동 작업이 많아요”

실무 문제 시나리오

시나리오 1: 데이터 수집이 번거로워요
수동 복사는 느립니다. Puppeteer로 자동화할 수 있습니다. 시나리오 2: PDF 생성이 필요해요
라이브러리는 제한적입니다. Puppeteer로 완벽한 PDF를 생성할 수 있습니다. 시나리오 3: E2E 테스트가 필요해요
수동 테스트는 비효율적입니다. Puppeteer로 자동화할 수 있습니다.

1. Puppeteer란?

핵심 특징

Puppeteer는 Headless Chrome 제어 라이브러리입니다. 주요 기능:

  • 웹 스크래핑: 데이터 수집
  • 스크린샷: 페이지 캡처
  • PDF 생성: 웹 페이지를 PDF로
  • 폼 자동화: 자동 입력
  • E2E 테스트: 자동화 테스트

2. 설치 및 기본 사용

설치

npm install puppeteer

기본 예제

아래 코드는 typescript를 사용한 구현 예제입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import puppeteer from 'puppeteer';
(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  const title = await page.title();
  console.log('Title:', title);
  await browser.close();
})();

3. 스크래핑

텍스트 추출

아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다, 반복문으로 데이터를 처리합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://news.ycombinator.com');
const titles = await page.$$eval('.titleline > a', (elements) =>
  elements.map((el) => el.textContent)
);
console.log(titles);
await browser.close();

복잡한 스크래핑

아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다, 반복문으로 데이터를 처리합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

const products = await page.$$eval('.product', (elements) =>
  elements.map((el) => ({
    name: el.querySelector('.name')?.textContent,
    price: el.querySelector('.price')?.textContent,
    image: el.querySelector('img')?.src,
  }))
);
console.log(products);

4. 스크린샷

전체 페이지

아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// 실행 예제
await page.goto('https://example.com');
await page.screenshot({
  path: 'screenshot.png',
  fullPage: true,
});

특정 요소

const element = await page.$('.header');
await element?.screenshot({ path: 'header.png' });

5. PDF 생성

다음은 typescript를 활용한 상세한 구현 코드입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

await page.goto('https://example.com', {
  waitUntil: 'networkidle0',
});
await page.pdf({
  path: 'page.pdf',
  format: 'A4',
  printBackground: true,
  margin: {
    top: '20px',
    right: '20px',
    bottom: '20px',
    left: '20px',
  },
});

6. 폼 자동화

로그인

아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

await page.goto('https://example.com/login');
await page.type('#email', '[email protected]');
await page.type('#password', 'password123');
await page.click('button[type="submit"]');
await page.waitForNavigation();
console.log('Logged in!');

파일 업로드

const fileInput = await page.$('input[type="file"]');
await fileInput?.uploadFile('./file.pdf');

7. 대기

waitForSelector

다음은 간단한 typescript 코드 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

await page.waitForSelector('.content', {
  visible: true,
  timeout: 5000,
});

waitForNavigation

다음은 간단한 typescript 코드 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

await Promise.all([
  page.waitForNavigation(),
  page.click('a.link'),
]);

커스텀 대기

await page.waitForFunction(
  () => document.querySelector('.data')?.textContent?.length > 0
);

8. 실전 예제: 뉴스 스크래핑

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 반복문으로 데이터를 처리합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

import puppeteer from 'puppeteer';
import fs from 'fs/promises';
async function scrapeNews() {
  const browser = await puppeteer.launch({ headless: true });
  const page = await browser.newPage();
  await page.goto('https://news.ycombinator.com');
  const articles = await page.$$eval('.athing', (elements) =>
    elements.slice(0, 10).map((el) => {
      const titleEl = el.querySelector('.titleline > a');
      const scoreEl = el.nextElementSibling?.querySelector('.score');
      return {
        title: titleEl?.textContent || ',
        url: titleEl?.href || ',
        score: scoreEl?.textContent || '0',
      };
    })
  );
  await fs.writeFile('news.json', JSON.stringify(articles, null, 2));
  console.log(`Scraped ${articles.length} articles`);
  await browser.close();
}
scrapeNews();

정리 및 체크리스트

핵심 요약

  • Puppeteer: Headless Chrome 제어
  • 웹 스크래핑: 데이터 수집
  • 스크린샷: 페이지 캡처
  • PDF 생성: 웹을 PDF로
  • 폼 자동화: 자동 입력
  • E2E 테스트: 자동화

구현 체크리스트

  • Puppeteer 설치
  • 브라우저 실행
  • 페이지 이동
  • 스크래핑 구현
  • 스크린샷 생성
  • PDF 생성
  • 폼 자동화

같이 보면 좋은 글

  • Playwright 완벽 가이드
  • Cypress E2E 테스트 가이드
  • 웹 스크래핑 가이드

이 글에서 다루는 키워드

Puppeteer, Web Scraping, Automation, PDF, Testing, Node.js, Chrome

자주 묻는 질문 (FAQ)

Q. Playwright와 비교하면 어떤가요?

A. Playwright가 더 빠르고 크로스 브라우저 지원이 좋습니다. Puppeteer는 Chrome에 특화되어 있습니다.

Q. 합법적인가요?

A. 스크래핑은 사이트의 robots.txt와 이용약관을 확인해야 합니다.

Q. Headless 모드가 뭔가요?

A. UI 없이 백그라운드에서 실행되는 모드입니다. 더 빠르고 서버에 적합합니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, Google에서 만든 안정적인 라이브러리입니다.

... 996 lines not shown ... Token usage: 63706/1000000; 936294 remaining Start-Sleep -Seconds 3