Como adicionar um solucionador de CAPTCHA ao chromedp em Go

Resumo

• chromedp controla o Chrome a partir de Go; um serviço de CAPTCHA separado fornece o resultado da resolução quando um fluxo de trabalho permitido precisa dele.
• Fixe a versão do chromedp porque os exemplos atuais usam APIs que diferem de tutoriais mais antigos.
• Teste o acesso ao navegador e a conexão com a API do solver separadamente antes de executar um desafio pago.
• Inspecione tanto os erros de Go quanto o ErrorId da API; um erro Go nil não prova sucesso do serviço.
• Mantenha juntos os dados da tentativa atual de desafio do navegador e depois verifique a página após aplicar o resultado.

chromedp é uma biblioteca Go para controlar navegadores por meio do Chrome DevTools Protocol. Desenvolvedores a utilizam para testes e automação de navegador sem introduzir um controlador em Python ou JavaScript. Quando uma tarefa de navegador aprovada encontra um CAPTCHA suportado, a aplicação Go pode chamar um solver e continuar gerenciando a mesma página.

A CapSolver fornece um SDK oficial em Go e APIs de tarefas documentadas para a etapa de resolução. Este guia conecta essas responsabilidades sem apresentar a biblioteca de navegador como um solver. A checagem executável usa um fixture de navegador local próprio e uma requisição de API real com uma chave de placeholder deliberadamente inválida. Ela verifica a fiação (wiring) e o tratamento de erros, não uma resolução paga.

Onde a resolução de CAPTCHA se encaixa no chromedp?

A resolução de CAPTCHA se encaixa entre coletar os parâmetros atuais do desafio e continuar a operação de navegador que precisa do resultado.

O repositório oficial do chromedp fornece o controlador de navegador. Seu programa Go abre a página permitida, lê o estado relevante e decide quando um desafio suportado precisa ser tratado. O solver fornece sua saída documentada; o chromedp continua responsável pelas ações subsequentes na página.

Um CAPTCHA não é prova de que toda operação de navegador parada exige uma requisição de resolução. Um campo ausente, falha de navegação ou erro da aplicação podem exigir outra correção. Identifique o desafio real antes de escolher um tipo de tarefa.

Para um formulário de QA próprio, a sequência é direta: abrir o formulário, identificar sua configuração de CAPTCHA, solicitar uma solução quando apropriado, aplicá-la pelo caminho de integração esperado da aplicação e checar a confirmação do formulário. Este guia não fornece um callback universal ou script de envio para sites arbitrários.

Instale dependências Go compatíveis

Use um módulo Go isolado e dependências fixadas para que as chamadas de API deste artigo correspondam ao seu build.

O ambiente verificado usou Go 1.27.3, github.com/chromedp/chromedp@v0.21.0 e github.com/capsolver/capsolver-go@v0.0.0-20251204081438-e4e07af23eae. O Chrome foi instalado localmente e iniciado em um contexto de navegador temporário separado.

Crie um diretório de trabalho, inicialize seu módulo com go mod init captcha-browser-check e depois execute:

go get github.com/chromedp/chromedp@v0.21.0 github.com/capsolver/capsolver-go@v0.0.0-20251204081438-e4e07af23eae

As notas de versão v0.21.0 indicam que Go 1.25 e posteriores são suportados. Use a documentação dessa versão ao adaptar um script de navegador mais antigo. Misturar exemplos antigos baseados em ponteiros com a API de ações tipadas mais recente pode produzir erros de compilação antes que qualquer requisição ao navegador ou solver seja executada.

A documentação oficial da API de saldo inclui o método Balance() do SDK em Go. Uma chamada de saldo é útil para separar acesso de conta/API da resolução específica de desafios. Ela não cria uma tarefa de CAPTCHA.

Execute a verificação de conexão do navegador e da API

Execute uma pequena verificação que prove que o Chrome consegue ler uma página própria e que o SDK em Go pode receber uma resposta real da API.

Salve isto como main.go e execute go run . a partir do módulo inicializado. O atributo local FIXTURE_ONLY é dado de teste, não um sitekey real. A chave de API é deliberadamente inválida, e o programa espera que o serviço a rejeite.

package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "net/http/httptest"
    "time"
    "github.com/chromedp/chromedp"
    capsolver "github.com/capsolver/capsolver-go"
)

func main() {
    // Um fixture local verifica a fiação do navegador. Não é um CAPTCHA real.
    fixture := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprint(w, `<title>Owned QA fixture</title><div id="widget" data-sitekey="FIXTURE_ONLY"></div>`)
    }))
    defer fixture.Close()
    ctx, cancel := chromedp.NewContext(context.Background())
    defer cancel()
    ctx, deadline := context.WithTimeout(ctx, 30*time.Second)
    defer deadline()
    if err := chromedp.Do(ctx, chromedp.Navigate(fixture.URL)); err != nil { log.Fatal(err) }
    sitekey, err := chromedp.Run(ctx, chromedp.AttributeValue("#widget", "data-sitekey"))
    if err != nil { log.Fatal(err) }
    if !sitekey.Exists || sitekey.Value != "FIXTURE_ONLY" { log.Fatal("Fixture key not found") }; fmt.Println("Fixture key:", sitekey.Value)
    // Credencial deliberadamente inválida: verifica um erro real de API, não uma conta.
    solver := capsolver.CapSolver{ApiKey: "YOUR_API_KEY"}
    result, err := solver.Balance()
    if err != nil { log.Fatal(err) }
    fmt.Println("API error:", result.ErrorId, result.ErrorCode)
    if result.ErrorId == 0 { log.Fatal("Expected the placeholder credential to be rejected") }
}

A execução verificada imprimiu Fixture key: FIXTURE_ONLY, seguida de um erro de API com ErrorId igual a 1 e ERROR_KEY_DOES_NOT_EXIST. Trate esse código exato como a resposta observada para esta verificação de placeholder, não como uma resposta garantida para toda credencial inválida.

Isso estabelece o acesso local ao navegador e um caminho real de requisição–resposta até a API. Nenhuma conta real foi consultada, nenhum desafio foi resolvido e nenhum envio de formulário foi realizado.

Inspecione o atributo retornado explicitamente

A ação AttributeValue atual retorna um AttributeResult contendo o valor do atributo e uma flag de existência.

O exemplo verifica ambos os campos antes de prosseguir. Um atributo ausente deve interromper a coleta de parâmetros em vez de se tornar um sitekey vazio em uma requisição paga. Um seletor que funciona neste fixture próprio não é um seletor universal para toda integração de CAPTCHA.

Verifique erros de negócio separadamente dos erros de Go

O SDK verificado pode retornar uma resposta do serviço já analisada sem retornar um erro de Go.

É por isso que o exemplo verifica result.ErrorId após tratar err. Uma falha de rede, falha de parsing de JSON e uma resposta válida descrevendo um erro de conta são condições diferentes. Leia a resposta retornada em detalhes em vez de assumir que err == nil significa que a conta ou tarefa foi bem-sucedida.

Resgate Seu Código de Bônus da CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código de bônus CAP26 ao recarregar sua conta CapSolver para ganhar 5% de bônus extra em cada recarga — sem limites.
Resgate agora no seu Painel CapSolver

Mapeie o desafio atual para uma tarefa documentada

Use a referência de tarefa do CAPTCHA selecionado para construir a requisição de resolução a partir da página que você realmente inspecionou.

Para reCAPTCHA v2, a documentação oficial de tarefas especifica a família de tarefas e campos como websiteURL e websiteKey. Use a grafia e capitalização documentadas. Não construa um nome de tarefa de memória nem copie um exemplo antigo de SDK sem checar o contrato atual.

O SDK oficial em Go expõe Solve() para um mapa de tarefa. Uma implementação em produção deve fornecer a credencial real de forma segura, passar os parâmetros atuais da tarefa e inspecionar o resultado retornado ou erro de acordo com a versão fixada do SDK.

A verificação de conexão acima é, intencionalmente, não um programa completo de resolução paga. Antes de implantar a etapa de resolução, execute um desafio permitido com sua própria conta financiada e valide o resultado contra a aplicação própria. Essa etapa dependente de credencial não foi executada para este artigo, portanto nenhuma taxa de sucesso ou conclusão ponta a ponta é reivindicada.

Mantenha a URL da página, a família de desafios, a chave pública e os parâmetros opcionais exigidos associados à mesma operação de navegador. Se a navegação substituir a página ou regenerar o desafio, reinspecione as entradas antes de iniciar outra tentativa.

Aplique o resultado pela integração real da página

Use a solução da maneira esperada pela aplicação própria e depois verifique se o comportamento da aplicação mudou como pretendido.

Um resultado baseado em token não é uma instrução para clicar qualquer botão visível de verificação. Algumas aplicações usam callbacks, outras vinculam o resultado a um formulário, e a validação final do lado do servidor ainda é importante. Consulte a implementação da aplicação em vez de adivinhar o nome de um callback JavaScript.

A documentação de verificação de resposta do Google explica a etapa de verificação no servidor para reCAPTCHA. A automação de navegador alcançar uma linha de código após a resolução não é o mesmo que o servidor aceitar a resposta.

Mantenha a condição de sucesso do seu teste específica. Para um formulário próprio, inspecione sua confirmação ou registro de teste. Para um fluxo de leitura permitido, inspecione o conteúdo esperado. Evite tratar apenas o desaparecimento do widget como sinal de conclusão quando a aplicação possui um resultado mais confiável.

Diagnostique uma falha sem repetir todo o fluxo de trabalho

Diagnostique o componente que falhou antes de repetir navegação, verificações de conta e resolução ao mesmo tempo.

Um erro de compilação aponta para compatibilidade de código e dependências. Uma falha ao iniciar o navegador aponta para o executável ou ambiente de runtime. Uma chave ausente aponta para a inspeção da página. Um erro de serviço aponta para a resposta documentada da API. Um formulário rejeitado após uma solução aponta para a aplicação do resultado e para a própria aplicação.

Para falhas de contrato de entrada, o guia de solução de problemas de invalid-task-data mostra como comparar a requisição real com a tarefa selecionada. Mais tentativas de navegador não vão corrigir um campo escrito errado nessa requisição.

Mantenha um pequeno registro de diagnóstico com as versões de pacotes, estágio que falhou, identificador de tarefa quando disponível e informações de erro redigidas. Não registre a chave real da conta nem o token completo da solução. Ao escalar, descreva o que a verificação do navegador e a verificação da API estabeleceram separadamente.

Construa Fluxos de Automação Confiáveis com a CapSolver

Mantenha o chromedp no controle do navegador e coloque a chamada ao solver documentado exatamente na etapa de CAPTCHA. A CapSolver fornece a interface de resolução; sua aplicação é dona do estado da página, das decisões de erro e da checagem final de conclusão.

FAQ

P: O chromedp inclui resolução de CAPTCHA?

chromedp é um controlador de navegador. Este fluxo adiciona um serviço de resolução separado para desafios suportados encontrados durante tarefas permitidas.

P: O exemplo gasta crédito do solver?

Nenhuma tarefa paga é criada. O exemplo envia uma requisição de saldo com uma chave de placeholder deliberadamente inválida e verifica o erro resultante.

P: Por que a API pode rejeitar uma requisição quando o erro de Go é nil?

O SDK pode ter recebido e analisado com sucesso uma resposta que contém um erro em nível de serviço. Inspecione os campos de erro da resposta assim como o erro de Go.

P: Posso usar FIXTURE_ONLY como meu sitekey?

Não. É dado de teste local usado para verificar a leitura de atributos do navegador. Uma tarefa de resolução real precisa da chave pública atual da página permitida.

P: Uma resolução paga completa de CAPTCHA foi testada aqui?

Não. O escopo verificado é o fixture de navegador do chromedp e uma rejeição real da API. Resolução paga e aceitação por uma aplicação própria exigem sua conta e um teste ponta a ponta separado.