Puppeteer é uma biblioteca Node.js mantida pelo Google que fornece uma API de alto nível para controlar navegadores Chrome ou Chromium via o protocolo DevTools. Sua principal força reside na capacidade de interagir com páginas dinâmicas renderizadas por JavaScript, tornando-a essencial para extração de dados modernos, testes e2e e geração de conteúdo estático.

Estratégias de Espera Inteligentes para Conteúdo Dinâmico

Não basta navegar até uma URL: o desafio real está em determinar quando os dados alvo estão prontos para extração. Puppeteer oferece mecanismos flexíveis que vão além de timeouts fixos.

Espera por seletores com critérios refinados

await page.waitForSelector('.product-grid', {
  state: 'visible',
  timeout: 12000
});

// Espera por qualquer um dos indicadores de carregamento concluído
await Promise.any([
  page.waitForSelector('[data-status="ready"]'),
  page.waitForSelector('.loaded-flag'),
  page.waitForFunction(() => window.APP_READY === true)
]);

Validação condicional com waitForFunction

// Garante que a lista tenha pelo menos 5 itens visíveis
await page.waitForFunction(() => {
  const items = Array.from(document.querySelectorAll('.card'));
  return items.length >= 5 && 
         items.slice(0, 5).every(card => card.offsetHeight > 0);
}, { timeout: 18000 });

// Verifica se um estado global foi definido pelo framework
await page.waitForFunction('() => typeof window.__API_DATA__ !== "undefined"');

Otimização de navegação com waitUntil

await page.goto('https://loja.exemplo.com/produtos', {
  waitUntil: ['domcontentloaded', 'networkidle0']
});

Técnicas Eficientes de Extração Estruturada

A extração deve ser resiliente a mudanças leves na estrutura HTML e capaz de lidar com conteúdo gerado assincronamente.

Extração em lote com mapeamento seguro

const produtos = await page.$$eval('.produto-card', cards =>
  cards.map(card => ({
    id: card.dataset.id || null,
    nome: card.querySelector('.titulo')?.textContent?.trim() || '',
    preco: parseFloat(card.querySelector('.preco')?.textContent?.replace(/[^0-9.,]/g, '')) || 0,
    disponivel: card.classList.contains('em-estoque')
  }))
);

Captura de eventos DOM para conteúdo sob demanda

const conteudoAtualizado = await page.evaluate(() => {
  return new Promise(resolve => {
    const observer = new MutationObserver(mutations => {
      const elementoAlvo = document.querySelector('#lista-dinamica');
      if (elementoAlvo && elementoAlvo.children.length > 0) {
        observer.disconnect();
        resolve({
          total: elementoAlvo.children.length,
          ultimaAtualizacao: new Date().toISOString()
        });
      }
    });

    observer.observe(document.body, { childList: true, subtree: true });
  });
});

Manipluação de Formulários Complexos

Formulários modernos frequentemente envolvem validação em tempo real, campos condicionais e submissões assíncronas — exigindo abordagens mais sofisticadas do que simples preenchimento.

Preenchimento com simulação de comportamento humano

async function preencherCampoRealista(page, seletor, valor) {
  const campo = await page.locator(seletor);
  await campo.focus();

  // Digitação gradual com variação de velocidade
  for (const char of valor) {
    await page.keyboard.type(char, { delay: Math.floor(Math.random() * 60) + 30 });
  }

  // Simula revisão rápida em 20% dos casos
  if (Math.random() < 0.2) {
    await page.keyboard.press('ArrowLeft', { delay: 50 });
    await page.keyboard.press('Backspace', { delay: 40 });
    await page.keyboard.type(valor.slice(-1), { delay: 50 });
  }
}

await preencherCampoRealista(page, '#email', 'usuario@exemplo.com');

Gerenciamento de estado em formulários multi-etapa

class GerenciadorEtapa {
  constructor(pagina) {
    this.pagina = pagina;
    this.etapas = [];
  }

  async registrarEtapa(identificador, campos) {
    const valores = {};
    for (const campo of campos) {
      const valor = await this.pagina.locator(campo).inputValue();
      valores[campo] = valor;
    }
    this.etapas.push({ identificador, valores });
  }

  async restaurarEtapa(identificador) {
    const etapa = this.etapas.find(e => e.identificador === identificador);
    if (!etapa) return;

    for (const [seletor, valor] of Object.entries(etapa.valores)) {
      const campo = await this.pagina.locator(seletor);
      await campo.fill(valor);
    }
  }
}

Otimizações de Desempenho e Confiabilidade

Sistemas de extração em escala exigem controle rigoroso de recursos e estratégias de recuperação robustas.

Processamento paralelo com isolamento de contexto

const resultados = await Promise.allSettled([
  extrairDadosProduto(page, 'produto-1'),
  extrairDadosProduto(page, 'produto-2'),
  extrairDadosProduto(page, 'produto-3')
]);

function extrairDadosProduto(pagina, idProduto) {
  return pagina.evaluate((id) => {
    const el = document.querySelector(`[data-id="${id}"]`);
    return el ? {
      id,
      nome: el.querySelector('.nome')?.textContent,
      sku: el.dataset.sku
    } : null;
  }, idProduto);
}

Retentativas com backoff exponencial

async function tentarComRetentativa(url, maxTentativas = 3) {
  for (let i = 0; i < maxTentativas; i++) {
    try {
      await page.goto(url, { waitUntil: 'networkidle0', timeout: 25000 });
      await page.waitForSelector('.conteudo-principal', { timeout: 10000 });
      return await extrairDados();
    } catch (erro) {
      if (i === maxTentativas - 1) throw erro;
      const atraso = Math.pow(2, i) * 1000;
      await page.waitForTimeout(atraso + Math.random() * 500);
    }
  }
}

Trabalhando com Iframes e Contextos Isolados

Muitos formulários e widgets são carregados dentro de iframes — Puppeteer permite acessá-los diretamente sem necessidade de alternância manual de contexto.

async function preencherFormularioIframe(pagina, seletorIframe, acoes) {
  const iframe = await pagina.frameLocator(seletorIframe);
  
  for (const acao of acoes) {
    switch (acao.tipo) {
      case 'preencher':
        await iframe.locator(acao.seletor).fill(acao.valor);
        break;
      case 'selecionar':
        await iframe.locator(acao.seletor).selectOption(acao.valor);
        break;
      case 'clicar':
        await iframe.locator(acao.seletor).click();
        break;
    }
    await pagina.waitForTimeout(400);
  }
}

// Uso:
await preencherFormularioIframe(
  page,
  'iframe[src*="checkout"]',
  [
    { tipo: 'preencher', seletor: '#cpf', valor: '123.456.789-00' },
    { tipo: 'clicar', seletor: '#enviar' }
  ]
);