Perguntas frequentes

Qual é o status da compatibilidade entre navegadores?

O suporte oficial ao Firefox é experimental. O objetivo da colaboração contínua com o Mozilla é oferecer suporte a casos de uso de teste de ponta a ponta comuns, para os quais os desenvolvedores esperam cobertura em vários navegadores. A equipe da Puppeteer precisa da contribuição dos usuários para estabilizar o suporte ao Firefox e chamar nossa atenção para as APIs que estão faltando.

Do Puppeteer v2.1.0 em diante, é possível especificar puppeteer.launch({product: 'firefox'}) para executar os scripts do Puppeteer no Firefox Nightly, sem outros patches
personalizados. Embora um experimento mais antigo exigisse uma versão com patch do Firefox, a abordagem atual funciona com o Firefox "stock".

Continuamos colaborando com outros fornecedores de navegadores para oferecer suporte ao Puppeteer a navegadores, como o Safari. Esse esforço inclui a análise de um padrão para executar comandos em vários navegadores, em vez de depender do protocolo não padrão DevTools usado pelo Chrome.

Quais são os objetivos e princípios do Puppeteer?

Os objetivos do projeto são:

  • Fornecer uma biblioteca compacta e canônica que destaque os recursos do protocolo DevTools.
  • Fornecer uma implementação de referência para bibliotecas de teste semelhantes. Com o tempo, essas outras estruturas poderiam adotar o Puppeteer como camada fundamental.
  • Aumentar a adoção de testes de navegador headless/automáticos.
  • Ajude os novos recursos do protocolo DevTools para a versão dogfood... e detecte bugs.
  • Saiba mais sobre os aspectos problemáticos dos testes automatizados de navegador e ajude a preencher essas lacunas.

Adaptamos os princípios do Chromium para nos ajudar a orientar as decisões dos produtos:

  • Velocidade: o Puppeteer tem quase zero sobrecarga de desempenho em uma página automatizada.
  • Segurança: o Puppeteer opera fora do processo em relação ao Chromium, o que torna seguro automatizar páginas potencialmente maliciosas.
  • Estabilidade: o Puppeteer não deve ser instável nem vazar memória.
  • Simplicidade: o Puppeteer oferece uma API de alto nível fácil de usar, entender e depurar.

O Puppeteer vai substituir o Selenium/WebDriver?

Não. Os dois projetos são valiosos por motivos muito diferentes:

  • O Selenium/WebDriver foca na automação entre navegadores. Sua proposta de valor é uma única API padrão que funciona em todos os principais navegadores.
  • A Puppeteer foca no Chromium. A proposta de valor dele inclui recursos mais avançados e maior confiabilidade.

Dito isso, você pode usar o Puppeteer para executar testes com o Chromium, como o jest-puppeteer, que é voltado à comunidade. Embora essa não deva ser sua única solução de teste, ela tem alguns pontos positivos em comparação com o WebDriver:

  • O Puppeteer requer nenhuma configuração e vem com a versão do Chromium com que funciona melhor. É melhor ter alguns testes executando apenas o Chromium do que nenhum teste.
  • O Puppeteer tem uma arquitetura orientada a eventos, o que remove vários inconsistências em potencial. Não são necessárias chamadas malignas "sleep(1000)" em scripts de marionetes.
  • O Puppeteer é executado headless por padrão, o que a torna rápida a execução. O Puppeteer v1.5.0 também expõe os contextos do navegador, possibilitando o carregamento em paralelo eficiente da execução de testes.
  • O Puppeteer brilha quando se trata da depuração: vire o bit "headless" para false, adicione "slowMo" e você verá o que o navegador está fazendo. Você pode até abrir o Chrome DevTools para inspecionar o ambiente de teste.

Por que o Puppeteer v.XXX não funciona com o Chromium v.YYY?

Vemos o Puppeteer como uma entidade indivisível com o Chromium. Cada versão do Puppeteer agrupa uma versão específica do Chromium, a única com que tem garantia de funcionar.

Essa não é uma restrição artificial. Na verdade, muito trabalho está ocorrendo no repositório do Chromium. Aqui está uma história típica:

  1. Um bug do Puppeteer foi informado
  2. Esse é um problema com o protocolo DevTools, por isso o corrigimos no Chromium.
  3. Quando a correção upstream for concluída, lançamos o Chromium atualizado no Puppeteer

No entanto, muitas vezes é preferível usar o Puppeteer com o Google Chrome oficial em vez do Chromium. Para que isso funcione, instale uma versão de puppeteer-core que corresponda à versão do Chrome.

Por exemplo, para executar o Chrome 101 com puppeteer-core, use a tag npm chrome-101:

npm install puppeteer-core@chrome-101

Qual versão do Chromium o Puppeteer usa?

Encontre a versão usando uma das seguintes maneiras:

  • Procure a entrada chromium em revisions.ts. Para encontrar a confirmação e o número da versão correspondentes do Chromium, procure a revisão com o prefixo r na seção "Localizar versões" do OmahaProxy.
  • Procure o mapa versionsPerRelease em versions.js, que contém um mapeamento entre as versões do Chromium e do Puppeteer. Observação: o arquivo contém apenas versões do Puppeteer em que o Chromium está atualizado. Nem todas as versões do Puppeteer estão listadas.

Qual versão do Firefox o Puppeteer usa?

Como o suporte ao Firefox é experimental, o Puppeteer faz o download do Firefox Nightly mais recente quando a variável de ambiente PUPPETEER_PRODUCT está definida como firefox. É também por isso que o valor de firefox em revisions.ts é latest. O Puppeteer não está vinculado a uma versão específica do Firefox.

Para buscar o Firefox Nightly como parte da instalação do Puppeteer:

PUPPETEER_PRODUCT=firefox npm i puppeteer
# or "yarn add puppeteer"

O que é considerado uma navegação?

Do ponto de vista do Puppeteer, "navegação" é tudo que muda o URL de uma página. Além da navegação normal em que o navegador acessa a rede para buscar um novo documento do servidor da Web, isso inclui navegações de âncora e o uso da API History.

Com essa definição de "navegação", a Puppeteer funciona perfeitamente com aplicativos de página única.

Qual é a diferença entre um evento de entrada "confiável" e "não confiável"?

Nos navegadores, os eventos de entrada podem ser divididos em dois grandes grupos: confiáveis e não confiáveis.

  • Eventos confiáveis: eventos gerados por usuários que interagem com a página, como usando um mouse ou teclado.
  • Evento não confiável: são eventos gerados por APIs da Web, como os métodos document.createEvent ou element.click().

Os sites podem distinguir entre esses dois grupos:

  • usando uma flag de evento Event.isTrusted;
  • procurava eventos que os acompanhavam. Por exemplo, todo evento 'click' confiável é precedido por eventos 'mousedown' e 'mouseup'.

Para fins de automação, é importante gerar eventos confiáveis. Todos os eventos de entrada gerados com o Puppeteer são confiáveis e disparam eventos de acompanhamento adequados.

Se, por algum motivo, alguém precisar de um evento não confiável, será sempre possível acessar um contexto de página com page.evaluate e gerar um evento falso:

await page.evaluate(() => {
  document.querySelector('button[type=submit]').click();
});

Quais recursos não são compatíveis com o Puppeteer?

Talvez o Puppeteer não se comporte como esperado ao controlar páginas que incorporam áudio e vídeo. Por exemplo, é provável que a reprodução de vídeo e as capturas de tela falhem. Há dois motivos para isso:

  • O Puppeteer está incluído no Chromium (não no Chrome). Assim, por padrão, ele herda todas as limitações relacionadas de mídia do Chromium. Isso significa que o Puppeteer não é compatível com formatos licenciados, como AAC ou H.264.
    • É possível forçar o Puppeteer a usar uma versão instalada separadamente do Chrome em vez do Chromium com a opção executablePath para puppeteer.launch. Use essa configuração apenas se precisar de uma versão oficial do Chrome com suporte a esses formatos de mídia.
  • Como o Puppeteer (em todas as configurações) controla uma versão para computador do Chromium ou do Chrome, os recursos compatíveis apenas com a versão do Chrome para dispositivos móveis não são compatíveis. Isso significa que o Puppeteer não é compatível com o HTTP Live Streaming (HLS).

Estou com problemas para instalar / executar o Puppeteer no meu ambiente de teste. Onde devo procurar ajuda?

Temos um guia de solução de problemas para vários sistemas operacionais que lista as dependências necessárias.

O download do Chromium é feito a cada npm ci execução. Como posso armazenar o download em cache?

O caminho de download padrão é node_modules/puppeteer/.local-chromium. No entanto, é possível alterar esse caminho com a variável de ambiente PUPPETEER_DOWNLOAD_PATH.

O Puppeteer usa essa variável para resolver o local executável do Chromium durante a inicialização. Portanto, não é necessário especificar PUPPETEER_EXECUTABLE_PATH também.

Por exemplo, para manter o download do Chromium em ~/.npm/chromium:

export PUPPETEER_DOWNLOAD_PATH=~/.npm/chromium
npm ci

# by default the Chromium executable path is inferred
# from the download path
npm test

# a new run of npm ci will check for the existence of
# Chromium in ~/.npm/chromium
npm ci

Tenho mais dúvidas. Onde devo perguntar?

Há muitas maneiras de receber ajuda com o Puppeteer:

Pesquise esses canais antes de postar sua pergunta.