1. O que é e para que serve

Puppeteer é uma biblioteca para Node.js que fornece uma API de alto nível para controlar o navegador Chrome (ou Chromium) através do protocolo DevTools Protocol. Por padrão, o Puppeteer opera em modo headless (sem interface gráfica), tornando-se a ferramenta ideal para automatizar tarefas web no lado do servidor. No entanto, quando necessário, é possível executar o navegador completo com interface para depuração.

Os principais casos de uso do Puppeteer incluem: web scraping (extração de dados de sites dinâmicos que usam JavaScript), testes automatizados de aplicações web (testes e2e), geração de screenshots e PDFs de páginas, emulação de ações do usuário (cliques, preenchimento de formulários, navegação), além de monitoramento de desempenho de páginas web. Diferente de requisições HTTP simples, o Puppeteer executa JavaScript na página, permitindo obter conteúdo gerado dinamicamente.

A biblioteca é ativamente mantida pela equipe do Google e utilizada em produção por milhares de empresas. O Puppeteer oferece controle total sobre o navegador: desde gerenciamento de abas e interceptação de requisições de rede até emulação de dispositivos móveis e geolocalização. É uma ferramenta versátil que substitui um conjunto inteiro de utilitários para trabalhar com conteúdo web.

2. Instalação

Para instalar o Puppeteer via npm (Node Package Manager), execute o comando no terminal na raiz do seu projeto:

npm install puppeteer

Este comando baixará a biblioteca e automaticamente fará o download de uma versão compatível do Chromium (cerca de 300-400 MB). Se você quiser usar um Chrome/Chromium já instalado no sistema, instale o puppeteer-core:

npm install puppeteer-core

Ao usar puppeteer-core, você precisará especificar o caminho para o executável do navegador ao iniciar. Para trabalhar com a biblioteca, é necessário Node.js versão 18.0.0 ou superior (recomenda-se a versão LTS).

3. Início rápido — exemplo mínimo funcional

Crie um arquivo exemplo.js e adicione o código abaixo, que tira um screenshot de uma página web:

const puppeteer = require('puppeteer');

(async () => {
    // Inicia o navegador
    const browser = await puppeteer.launch();
    // Abre uma nova página
    const page = await browser.newPage();
    // Navega para o site
    await page.goto('https://example.com');
    // Tira um screenshot
    await page.screenshot({ path: 'exemplo.png' });
    // Fecha o navegador
    await browser.close();
})();

Execute o script com o comando node exemplo.js. Na pasta, aparecerá o arquivo exemplo.png com o screenshot da página example.com. Este é um exemplo mínimo, mas totalmente funcional de automação de navegador.

4. Principais métodos/funções/classes

Abaixo estão 8 métodos e classes essenciais do Puppeteer com descrição e exemplos de código.

4.1. puppeteer.launch()

Assinatura: puppeteer.launch([options]) → Promise<Browser>

O que faz: Inicia uma instância do navegador Chromium/Chrome. Aceita um objeto de opções (headless, slowMo, args, etc.). Retorna um objeto Browser.

const browser = await puppeteer.launch({
    headless: false, // Mostrar o navegador
    slowMo: 100,    // Desacelerar ações (ms)
    args: ['--window-size=1920,1080']
});