Análise do chromedp: um navegador real ainda exige a condição certa para estar pronto

chromedp é uma biblioteca pura em Go, licenciada sob MIT, que controla um Chrome real por meio do Chrome DevTools Protocol. Ela lê o DOM depois que o JavaScript da página termina de executar, tudo dentro de um programa Go, sem depender de WebDriver separado nem de runtime Node. O módulo Go entra na compilação da aplicação, mas, para funcionar de fato, ainda é necessário um executável externo do Chrome, cuja vida útil é gerenciada por meio de contexts do Go.

A instalação foi só um go get e um Chrome que eu precisei fornecer por conta própria: criar um allocator, derivar um context e passar uma lista de ações para Run. Neste host macOS arm64, com um headless shell já aquecido em disco, um processo novo até o primeiro resultado de script teve mediana de 102 ms. Isso é apenas uma base local, não uma afirmação geral de que a inicialização nunca vira gargalo. Em um fixture que injeta um link 800 milissegundos após o carregamento, duas de quatro estratégias de leitura retornaram antes de o link existir.

O navegador era real, o conteúdo estava lá, e o código simplesmente não estava esperando pela hora certa. Essa lacuna foi a lição mais útil que o chromedp me deu, e isso não é um bug — é a diferença entre "renderizei a página" e "esperei exatamente pelo que eu queria", uma distinção que a conversa comum sobre navegadores headless costuma achatar. Quem decide se você obtém os dados é a estratégia de espera, não o navegador. Todos os números aqui vêm de um fixture local que eu controlo, com a verdade de referência registrada antes de qualquer execução, e os resumos brutos estão na pasta chromedp do nosso repositório de benchmark.

O que o chromedp realmente é

A stack do chromedp é enxuta por design. Sem servidor Selenium. Sem camada de compatibilidade do WebDriver. Sem Node escondido nos bastidores. Seu programa Go abre um WebSocket para uma instância do Chrome e fala CDP diretamente com ela, que é basicamente o mesmo protocolo de transporte usado pelo Puppeteer, só que sem o JavaScript.

Quando consultei em 27 de julho de 2026, o repositório tinha 13.212 estrelas e 178 issues abertas, sob licença MIT. A versão que testei foi v0.16.0, que é a tag mais recente no repositório. Vale um aviso para não confundir: a página de Releases do GitHub ainda mostra v0.15.1 (publicada em 2026-04-01) como o último objeto de release, enquanto go get github.com/chromedp/chromedp@latest resolve para v0.16.0. Os módulos Go e os objetos de release do GitHub se afastaram aqui. Não está quebrado, mas é irritante quando você tenta descobrir exatamente o que está executando.

O modelo mental é todo baseado em Go contexts. Você cria um context de allocator (que sabe como iniciar o Chrome), deriva dele um context de browser e então chama chromedp.Run(ctx, actions...) com uma lista de Actions. Um context filho de um browser context vira uma nova aba. Cancelou o context, a coisa que ele representa desaparece. Se você já trabalhou com concorrência em Go, isso soa imediatamente familiar; se não, nosso guia para começar com web scraping em Go é uma entrada mais suave do que o godoc do chromedp.

Um limite importante para definir cedo: o chromedp entrega um DOM renderizado. Ele não entrega dados estruturados. Tudo o que você extrai desse DOM — campos, tabelas, preços — é código que você escreve e mantém. É um driver, não uma framework de scraping.

A engrenagem por trás do capô

Tudo no chromedp é uma Action, e Run executa uma sequência delas em ordem contra um target. Navigate, Click, Evaluate, OuterHTML, WaitVisible — tudo segue a mesma interface, tudo é combinável, tudo são apenas comandos CDP vestindo tipos Go. Essa uniformidade é a melhor decisão de design da biblioteca, porque mantém o açúcar sintático e o protocolo cru no mesmo nível.

Isso importa porque esse açúcar é propositalmente leve. O chromedp foi construído sobre cdproto, um conjunto gerado de bindings Go tipados que cobre toda a superfície do DevTools Protocol, e o godoc do chromedp documenta as duas camadas lado a lado. Quando não existe a Action de conveniência, você desce para a chamada de domínio — network.Enable(), page.CaptureScreenshot(), runtime.Evaluate() — dentro do mesmo Run. Não existe uma parede entre "a API bonita" e "a API de verdade", o que não acontece em todo driver de navegador.

As ações de espera são onde entra o julgamento do dia a dia, e há mais delas do que a maioria das pessoas usa:

Gerenciamento de processo é o outro ponto da mecânica que vale conhecer, porque ele decide se o seu programa vai deixar um navegador rodando para trás. O chromedp inicia o Chrome via exec.CommandContext do Go. Cancelar esse context mata o processo. Esse único detalhe de implementação explica tanto o comportamento correto quanto o problema que encontrei nos testes.

A configuração é um binário Go mais um Chrome que você precisa fornecer

go get github.com/chromedp/chromedp resolveu limpo para v0.16.0, sem drama, e a árvore de dependências não traz imports de cgo. Então a frase “pure Go, sem dependências externas” que você verá repetida é verdadeira — sobre o módulo Go.

Ela não é verdadeira sobre o runtime. O chromedp controla um Chrome externo e, sem Chrome na máquina, a execução falha imediatamente. Todas as medições que fiz forneceram o executável exato via chromedp.ExecPath, apontando para um headless shell do Chrome for Testing 151.0.7922.10. Isso não é uma crítica — para controlar um navegador você precisa de um navegador —, mas “sem dependências externas” e “você precisa distribuir um Chrome de 155 MB junto com o binário” são histórias de implantação bem diferentes, e só uma delas aparece no README.

Um segundo problema de configuração me custou tempo e vale a pena saber antes de escrever qualquer código. A issue #1591 relata que o runner go test do Go 1.25+ cancela o NewExecAllocator no meio da inicialização; o mesmo código roda normalmente como binário compilado. Eu montei um binário de teste com go build e usei isso em todas as medições, em vez de acionar qualquer coisa via go test. O Go aqui era 1.26.5, macOS arm64. Se sua primeira experiência com chromedp for um arquivo de teste que morre durante o startup do Chrome, leia essa issue antes de culpar seu próprio código.

Na prática: quatro formas de ler a mesma página, duas vazias

O fixture é um servidor local em 127.0.0.1 que entrega três classes de conteúdo que diferem apenas em quando entram no DOM: um <a> estático nos bytes servidos, um <a> criado por um <script> inline durante a análise inicial e um <a> criado por setTimeout um número configurável de milissegundos depois do evento load. Os marcadores e hrefs dos dois links criados por script são montados a partir de fragmentos de string em JavaScript, então não existe nenhum literal contíguo nos bytes servidos. Um resultado “found” prova, portanto, que o Chrome executou JavaScript, e não apenas leu HTML.

O recall é calculado em Python com base em marcadores de verdade de referência pré-registrados, e não dentro do probe em Go, então o probe não consegue trapacear sabendo a resposta. Cada estratégia foi executada três vezes; os conjuntos encontrados foram idênticos nas três execuções.

Duas linhas voltam com dois links em três. A leitura ingênua falha porque Navigate retorna no evento load e o terceiro link ainda não existe. WaitReady("body") falha por um motivo mais sutil, e pior na prática: body já está anexado no load, então a espera é satisfeita instantaneamente e você sente que fez a coisa certa. Ele voltou em 107 ms, mais rápido do que o caminho sem espera, e entregou a mesma página incompleta.

Para confirmar o mecanismo em vez de presumir, varri o atraso de injeção e refiz os dois extremos (recall-summary.json):

O tempo gasto por WaitVisible acompanha o atraso de injeção neste fixture — 100 para 208, 400 para 519, 800 para 911, 1500 para 1625 — evidência de que ele bloqueou até o nó aparecer, em vez de ler cedo demais. A linha de 0 ms é a fronteira: setTimeout(…, 0) pode disparar antes da leitura imediata, então o caminho sem espera pode capturá-lo. A partir de 100 ms nesta variação, o caminho sem espera falhou em todas as execuções.

Em produção, o mesmo erro de timing pode gerar HTML válido com zero linhas extraídas e sair com código 0, a menos que o pipeline cheque a cardinalidade da saída. Esse é um modo de falha plausível, sustentado pelo comportamento do fixture, não um incidente medido aqui. Renderizar é só metade do requisito; a leitura precisa esperar uma condição de nível de aplicação ligada aos dados desejados.

WaitReady e WaitVisible não competem — eles respondem perguntas diferentes

A formulação comum é que WaitVisible seria “mais confiável” que WaitReady. Isso é impreciso o suficiente para fazer mal. Em uma página com um nó anexado ao DOM mas estilizado com display: none, os dois se separam claramente (waitsem-summary.json, três execuções idênticas):

WaitReady significa anexado. WaitVisible significa visível. Faça a pergunta errada e você ou passa direto por conteúdo que nunca renderizou, ou trava por todo o timeout em um nó que nunca teria ficado visível. O comportamento de deadline em si é limpo — um context deadline exceeded correto e exato em 4 s, sem travamento e sem estado zumbi — o que já é mais do que alguns drivers conseguem.

Uma armadilha relatada não apareceu. A issue #440 diz que WaitVisible("#id") trava com a query padrão, e isso não se reproduziu na v0.16.0 — query padrão, ByID e ByQuery retornaram no nó visível em todas as execuções. Não reproduzido não é o mesmo que corrigido: aqui é só uma forma de seletor em uma página, o que não encerra a issue.

O defer cancel() que você pulou está segurando o telhado

Contagem de processos, não valores de retorno. Cada execução de ciclo de vida usou um --user-data-dir exclusivo e contou processos reais do navegador Chrome com pgrep, filtrando os filhos renderer. Cada caminho foi executado três vezes (lifecycle-summary.json).

Cancelar é limpo, rápido e exatamente o que exec.CommandContext promete. (Cada órfão foi forçadamente encerrado pelo harness depois; o host ficou limpo.)

Isso é comportamento conhecido, documentado e limitado à plataforma — a medição é minha, a descoberta não. O tracker do chromedp cobre isso por vários ângulos: #774 descreve a mesma não saída no FreeBSD, #752 relata processos Chromium pendurados no macOS, e #562 junto com #1566 explicam o mecanismo. O que eu acrescentei foi a contagem de processos e o timing dos dois lados da comparação, algo que esses relatos qualitativos não trazem.

O mecanismo em si tem a ver com build tags, e vale a pena conhecê-lo. No código-fonte da v0.16.0, allocate_linux.go define Pdeathsig = SIGKILL no processo filho, então Linux recebe um sinal de morte do pai no nível do kernel. Já allocate_other.go, que é o que o macOS compila, transforma essa chamada em no-op. Não existe sinal equivalente no darwin, então nada mata o Chrome quando seu programa termina. Enquanto isso, o texto do godoc soa como uma promessa geral — o comando padrão “envia SIGKILL para qualquer browser aberto quando o programa Go encerra” — mas a limitação para Linux aparece apenas em código com build tag que você teria de ler. Dizer que a documentação exagera é justo; chamar isso de bug do chromedp, não.

A consequência prática continua a mesma: no macOS, defer cancel() é estrutural. Se você pular isso, cada execução vazará um processo de navegador. Eu não testei Linux, então não estou generalizando esse resultado de órfãos para lá — o código sugere que Linux se comporta de forma diferente, e sugestão não é medição.

Cold start, concorrência e os detalhes chatos que definem seu deploy

102 ms foi a mediana entre processo novo, allocator, context, navegação para localhost e primeiro Evaluate, ao longo de cinco processos, variando de 98 a 111 ms (coldstart-summary.json). Neste fixture macOS arm64 com um headless shell já aquecido em disco, a inicialização foi pequena em comparação com a espera por conteúdo atrasado. Containers, sistemas de arquivos frios, CI, ambientes serverless e navegação em produção não foram medidos.

Em concorrência, o chromedp oferece duas formas — um browser com vários contexts filhos (abas) ou vários browsers independentes. Quatro navegações, três execuções cada (concurrency-summary.json):

O achado medido aqui é a contagem de processos: um processo de browser Chrome versus quatro para essas quatro navegações locais triviais. As faixas de tempo total não se sobrepuseram, mas continuam sendo indicativas, não um benchmark de throughput. RSS e PSS não foram medidos, então este teste não prova economia de memória.

O pequeno probe do caminho de erro não é detalhado o suficiente aqui para sustentar uma afirmação de robustez: o rascunho não identifica se status HTTP, erro de navegação, evento ou lógica do harness expôs cada condição. Trate o tratamento de 500/dead-link como não relatado até que o resultado exato da API e o artefato bruto sejam publicados.

O que não foi testado, e portanto está fora do alcance destes números: comportamento de lifecycle no Linux, concorrência além de N=4 ou com trabalho real por página, diferenças de memória (eu contei processos, não RSS), interceptação de rede e captura de requisições, e os relatos abertos de timeout em WaitReady nas issues #168 e #1593 — eles descrevem timeouts intermitentes, enquanto o que medi foi a semântica de espera, uma pergunta diferente. Uma máquina, uma build do Chrome.

O chromedp não é o único driver Go CDP neste comparativo: o rod passou pelo mesmo fixture, harness, host e build do Chrome na mesma sessão, e terá seu próprio texto.

Prós e contras

Prós:

• Acesso real ao CDP — as Actions de conveniência e as chamadas de domínio brutas do cdproto convivem no mesmo Run, então você não bate em teto de API.
• Base local de cold cycle de 102 ms p50, com faixa de 98–111 ms no fixture macOS testado.
• Cancelar remove o Chrome em cerca de 13 ms, de forma consistente, em todas as execuções.
• Contexts filhos compartilham um processo de browser para N abas (1 processo versus 4 em browsers separados).
• Determinismo nos testes — conjuntos de recall, semântica de espera e resultados de lifecycle foram idênticos em três repetições cada.
• Tratamento limpo de deadline: WaitVisible em uma condição inalcançável retornou um context deadline exceeded correto e exato em 4 s, sem travar.
• Módulo puro em Go (sem cgo), licenciado sob MIT; ainda assim, um executável externo do Chrome é necessário em runtime.

Contras:

• Exige um Chrome externo em runtime; a fama de “sem dependências” vale apenas para o módulo Go.
• WaitReady("body") é uma armadilha que parece correta e falha silenciosamente com conteúdo pós-load — voltou em 107 ms com a página incompleta.
• O caminho ingênuo Navigate + leitura perde tudo o que é injetado ≥ ~100 ms após o load, de forma determinística e sem erro.
• No macOS, sair sem cancel() deixa o browser órfão (3/3 execuções). É comportamento conhecido e limitado à plataforma, mas fácil de esquecer.
• A redação do godoc sobre SIGKILL na saída soa universal, quando o mecanismo está apenas em código com build tag para Linux.
• go test no Go 1.25+ pode cancelar a inicialização do allocator (#1591); prefira construir um binário.
• Ele retorna um DOM, não dados estruturados — cada campo que você quer vira código de parsing que você precisa manter.
• A tag mais recente (v0.16.0) está à frente do último objeto de Release do GitHub (v0.15.1), o que deixa a checagem de versão momentaneamente confusa.

Para quem o chromedp serve — e para quem é melhor evitar

Se o seu serviço já é Go e você precisa de um navegador real dentro dele, o chromedp está muito perto da escolha óbvia. Sem processo Node para supervisionar, sem servidor WebDriver para manter vivo, um binário compilado mais um Chrome que você distribui ou instala. O modelo de context se encaixa nas primitivas de concorrência do Go de forma tão direta que a vida útil do browser acaba sendo governada pela mesma disciplina de defer que o resto do código usa. E se você precisar de algo fora da API de conveniência — eventos de rede via CDP, hooks precisos de ciclo de vida da página, truques em nível de protocolo — basta descer para cdproto sem sair da biblioteca.

Também é uma boa opção quando você quer controle explícito sobre as esperas. As actions de wait são primitivas, não heurísticas; elas fazem exatamente o que dizem, o que vira vantagem assim que você aceita que a escolha certa agora é sua responsabilidade.

Evite se sua equipe não escreve Go — o custo real é a linguagem, não a biblioteca. Evite se você quer uma ergonomia de auto-wait que adivinhe corretamente por você, porque o chromedp não vai adivinhar; ele fará exatamente o que você pediu e devolverá o que a página tinha naquele momento. Evite, ou reserve orçamento sério para isso, se o que você precisa é de registros estruturados em vez de um DOM: cada campo é um seletor que você escreve, testa e corrige quando o site muda. E se “só me dê os dados dessas 500 URLs” for o requisito inteiro, montar orquestração de navegador em Go é bastante máquina para o pedido. Nosso guia de automação de navegador mostra quando essa máquina se justifica e quando não.

Alternativas, inclusive onde nossa própria stack se encaixa

Dentro da categoria de drivers de navegador, o rod é outro driver Go CDP, enquanto Playwright e Puppeteer são opções do lado Node, cobertas no nosso comparativo entre Playwright e Puppeteer. Os contratos de espera deles não são intercambiáveis. O Playwright faz auto-wait por actionability antes de muitas ações; isso ainda não diz quando os dados da aplicação terminaram de chegar após a ação. O chromedp oferece primitivas de espera de nível mais baixo e deixa tanto a actionability quanto as condições de prontidão da aplicação para quem chama. Se você estiver mapeando o campo mais amplo, nosso panorama de scrapers open source que testamos cobre crawlers estáticos e bibliotecas de extração do outro lado dessa linha.

Leitura relacionada: análise do Browserless.

Um serviço gerenciado de extração é uma categoria diferente. Ele troca controle de browser e seletor por renderização terceirizada e modelagem de schema. Isso pode ser útil quando o entregável é um conjunto de registros estruturados, e não um DOM, enquanto o chromedp é a melhor opção quando o navegador precisa permanecer sob o controle do seu serviço Go. Nós construímos o Thunderbit, um serviço desse tipo, mas não o executamos contra este fixture; portanto, este teste não sustenta comparação de equivalência, latência, qualidade de extração ou custo com o chromedp.

Experimente o Thunderbit para extração de dados da web

Veredito

Vale a pena usar chromedp? Sim, se você escreve em Go e quer um navegador real sob seu controle. Neste fixture local, ele alcançou o primeiro resultado de script em 102 ms p50, removeu o Chrome em cerca de 13 ms após o cancelamento e usou um processo de browser para quatro abas concorrentes. Essas são observações delimitadas, não promessas universais de desempenho; o atrativo duradouro é o acesso direto ao CDP em Go quando a camada de conveniência já não basta.

Só dimensione as promessas corretamente, porque a reputação exagera duas coisas. “Pure Go, sem dependências” descreve o módulo; em runtime, você está distribuindo e gerenciando um binário Chrome. E “use um navegador headless e você conseguirá o conteúdo dinâmico” só é verdade quando sua espera está ligada ao nó que você quer — uma leitura ingênua e WaitReady("body") me entregaram uma página sem conteúdo que foi injetado 800 ms depois do load, silenciosamente, todas as vezes. No macOS, defer cancel() não é preferência de estilo; se você o omitir, vaza um browser por execução, o que é um comportamento conhecido da plataforma, mas continua sendo um problema seu. Acertando essas três coisas, o chromedp é um dos drivers de navegador mais previsíveis que medi. Errando, ele falha em silêncio, que é o pior tipo de falha para um scraper.

Experimente o Thunderbit para extração de dados da web Get Started Free

FAQs

O chromedp realmente enxerga conteúdo renderizado por JavaScript? Sim — mas só com uma espera ligada ao nó que você quer. Em um fixture onde um link foi injetado 800 ms após o evento load, Navigate seguido de leitura falhou em vê-lo, e WaitReady("body") também falhou, enquanto WaitVisible naquele nó e um poll em JavaScript o recuperaram, em três de três execuções cada. Ao variar o atraso, a leitura sem espera falhou em todos os casos a partir de 100 ms. Renderizar é necessário; esperar corretamente é o que torna isso suficiente.

Qual é a diferença entre WaitReady e WaitVisible? WaitReady bloqueia até o nó estar anexado ao DOM. WaitVisible bloqueia até ele estar realmente visível. Em um nó anexado, mas com display: none, WaitReady retornou em cerca de 6 ms, enquanto WaitVisible foi até o deadline de 4 segundos e devolveu um context deadline exceeded limpo. Nenhum dos dois é “mais confiável” — eles respondem perguntas diferentes, e escolher o errado é a armadilha real.

Eu realmente preciso de defer cancel() com chromedp? No macOS, sim. Cancelar o context e o allocator removeu o Chrome iniciado em 12–13 ms em todas as execuções; sair do processo Go sem cancelar deixou um browser órfão em todas as três execuções. Isso é comportamento conhecido e limitado à plataforma — o tracker do chromedp documenta o mesmo padrão de não saída em outros sistemas não-Linux, e o kill por morte do pai que resolve isso vive em código com build tag apenas para Linux. Eu não testei Linux, então trate o resultado de órfãos como limitado ao macOS.

O chromedp precisa de Chrome instalado separadamente? Sim. O módulo Go em si é puro Go, sem cgo, mas ele controla um navegador externo e falha imediatamente sem um. Eu forneci explicitamente um headless shell do Chrome for Testing 151.0.7922.10 via chromedp.ExecPath. A vantagem é que o custo de inicialização é pequeno: um ciclo frio completo até o primeiro resultado de script teve mediana de 102 ms em cinco processos novos, variando de 98 a 111 ms.

Devo compartilhar um browser entre abas ou subir browsers separados? Prefira contexts filhos quando a meta for minimizar a contagem de processos do browser. Quatro navegações localhost em um browser usaram 1 processo Chrome; quatro browsers separados usaram 4. O tempo total também favoreceu a configuração compartilhada (214 ms contra 264 ms de mediana), mas quatro páginas locais triviais não são um benchmark de throughput. Memória não foi medida. Browsers separados ainda podem ser a escolha certa quando você precisa de isolamento de sessão mais forte, proxies diferentes ou um raio de impacto de crash menor; esses trade-offs ficaram fora deste teste.