Como adicionar um solucionador de CAPTCHA à automação do Patchright

Resumo

• O Patchright controla um navegador Chromium; um CAPTCHA que exige resposta ainda precisa de uma etapa separada de resolução.
• A detecção do reCAPTCHA pode depender do estado do JavaScript no ambiente principal da página, enquanto o Patchright avalia scripts em um ambiente isolado por padrão.
• Um pequeno adaptador de página permite que o SDK oficial CapSolver Core inspecione a mesma página do Patchright sem abrir um segundo navegador.
• Comece com um widget de teste local, depois valide separadamente a resolução paga e a resposta da aplicação antes de usar a integração em um fluxo de trabalho maior.

Um script Patchright pode navegar com sucesso, encontrar o formulário e então parar em um widget reCAPTCHA. Trocar de biblioteca de navegador não fornece a resposta que o widget e a aplicação exigem. Nesse ponto, você precisa de um resolvedor de CAPTCHA, além de uma verificação de que a aplicação aceitou o resultado.

Este tutorial de resolvedor de CAPTCHA com Patchright conecta uma sessão de navegador Python ao CapSolver por meio de seu SDK oficial Core. O detalhe útil é o ambiente JavaScript da página: ler o DOM visível e ler a configuração do reCAPTCHA pertencente à página são operações diferentes. O exemplo abaixo lida com essa distinção, mantém uma única página aberta e verifica a detecção em um fixture de desenvolvimento local. Use esta abordagem para páginas que você possui ou para as quais tenha permissão de automatizar.

O que é o Patchright e quando um resolvedor de CAPTCHA ajuda

Patchright é um derivado mantido pela comunidade do Playwright, com uma interface de automação em Python semelhante. O repositório Python oficial documenta o suporte ao Chromium e seu uso como import de substituição para o Playwright. Firefox e WebKit não são suportados pelo Patchright.

Desenvolvedores usam o Patchright para controlar páginas, interagir com elementos e executar fluxos de trabalho de navegador. Um resolvedor se torna relevante quando um CAPTCHA suportado impede que um fluxo de trabalho autorizado conclua um formulário ou atinja o resultado esperado. Se sua página já é acessível, não há motivo para fazer uma solicitação paga de resolução.

A integração tem três responsabilidades separadas. O Patchright controla a navegação e o ciclo de vida da página. O resolvedor lê entradas de desafios suportados e solicita uma solução. O fluxo de trabalho da sua aplicação decide se o formulário ou a página seguinte realmente teve sucesso. O glossário de CAPTCHA explica o mecanismo de verificação por trás dessa separação.

Para testes rotineiros da sua própria aplicação, prefira as configurações de desenvolvimento do fornecedor de CAPTCHA. Uma verificação de integração com um resolvedor pago é uma tarefa separada de testar se a validação comum do seu formulário funciona.

Por que a detecção de reCAPTCHA precisa do contexto correto da página

A detecção de reCAPTCHA pode precisar de configurações criadas pelo widget no ambiente JavaScript principal da página. A opção documentada do Patchright para evaluate(), isolated_context, tem valor padrão True; globais JavaScript pertencentes à página podem, portanto, estar ausentes de uma avaliação comum, mesmo quando o widget está visível.

No exemplo controlado usado neste guia, a avaliação padrão não conseguia ver window.___grecaptcha_cfg, enquanto a avaliação com isolated_context=False conseguia. O SDK precisa de acesso a esse estado da página para este caminho de reCAPTCHA. Um timeout ou um resultado vazio de detecção deve, portanto, levar a uma checagem do contexto antes de você mudar a site key ou enviar solicitações repetidas de resolução.

O adaptador abaixo encaminha as avaliações do SDK para o ambiente principal da página. Ele não modifica arquivos instalados do Patchright nem troca o ambiente para cada operação de navegador. Navegação e localizadores comuns permanecem em raw_page; apenas o objeto de página passado ao SDK usa esse wrapper. Trate-o como um exemplo de integração testado para as versões listadas abaixo, não como uma declaração de parceria oficial com o Patchright ou de compatibilidade universal.

Instale os pacotes e verifique os pré‑requisitos

O exemplo usa Python 3.12, Patchright 1.64.1 e capsolver-core 0.1.1. Instale os pacotes em um ambiente isolado e instale o runtime Chromium do Patchright. Fixe essas versões para a checagem de setup, para que uma atualização de pacote não altere silenciosamente o comportamento.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "patchright==1.64.1" "capsolver-core==0.1.1"
python -m patchright install chromium

O exemplo de detecção não precisa de uma chave de API do CapSolver. A resolução real exige sua própria chave válida e recursos suficientes na conta. Configure o cliente com a opção documentada create_capsolver(api_key=...) e mantenha a chave na configuração secreta da sua aplicação. O guia do Core SDK documenta a criação do cliente, detecção, resolução e campos de resultado.

A checagem de setup abaixo foi executada contra uma página local usando a chave pública de teste do reCAPTCHA do Google. Resolução paga, preenchimento de token e aceitação do token resolvido pela aplicação não foram executados para este guia. Não use este fixture como teste de taxa de sucesso em produção.

Execute uma checagem local de Patchright e SDK

A checagem de setup abre um fixture local, espera o widget de teste inicializar e imprime os parâmetros do CAPTCHA retornados pelo SDK oficial. Salve como patchright_sdk_check.py e execute com Python no ambiente acima.

A URL local é servida por meio de uma rota do navegador, então não é necessário um servidor web separado. O script do widget ainda é carregado do Google e requer acesso à rede. A site key pública vem da orientação de teste de reCAPTCHA do Google; é uma chave de desenvolvimento, não uma credencial privada.

import asyncio
import json

from capsolver_core import create_capsolver
from patchright.async_api import async_playwright

TEST_URL = "http://127.0.0.1:8765/"
HTML = """<!doctype html><html><head><title>CAPTCHA integration check</title></head>
<body><h1>Owned development page</h1>
<div class="g-recaptcha" data-sitekey="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"></div>
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
</body></html>"""


class MainWorldPage:
    def __init__(self, page):
        self._page = page

    @property
    def url(self):
        return self._page.url

    async def evaluate(self, expression, arg=None):
        return await self._page.evaluate(expression, arg, isolated_context=False)

    async def wait_for_selector(self, selector, **kwargs):
        return await self._page.wait_for_selector(selector, **kwargs)


async def main():
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True)
        try:
            raw_page = await browser.new_page()
            await raw_page.route(
                TEST_URL, lambda route: route.fulfill(content_type="text/html", body=HTML)
            )
            await raw_page.goto(TEST_URL)
            page = MainWorldPage(raw_page)
            for _ in range(60):
                ready = await page.evaluate(
                    "() => !!window.___grecaptcha_cfg && "
                    "Object.keys(window.___grecaptcha_cfg.clients || {}).length > 0"
                )
                if ready:
                    break
                await asyncio.sleep(0.5)
            else:
                raise RuntimeError("Test widget did not initialize")

            async with create_capsolver() as cap:
                infos = await cap.get_captcha_info(page)
                result = [{"type": info.type.value, "url": info.website_url,
                           "site_key": info.website_key} for info in infos]
                print(json.dumps({"captcha_parameters": result}))
                assert result and result[0]["type"] == "reCaptchaV2"
        finally:
            await browser.close()


if __name__ == "__main__":
    asyncio.run(main())

A execução bem-sucedida retornou um item com tipo reCaptchaV2, a URL local da página e a site key pública de teste. Esse resultado confirma que o Patchright abriu a página e que o SDK conseguiu ler o widget inicializado por meio do adaptador. Ele não contém um token resolvido e não prova que um formulário em produção iria aceitá-lo.

O navegador é fechado no finally, inclusive quando o carregamento do widget ou a detecção falham. O cliente do SDK também encerra seu contexto assíncrono. Mantenha essa limpeza ao mover a integração para um script mais longo, especialmente quando um desafio causar uma exceção.

Resgate seu código de bônus do 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

Adicione a resolução após a checagem de detecção

A resolução pertence ao interior dos contextos ativos do navegador e do SDK, antes que a página seja fechada ou navegue para outro lugar. Na sua página de aplicação autorizada, crie o cliente SDK com sua chave, encapsule a página atual do Patchright como mostrado acima e use a chamada oficial em modo navegador.

A linha a seguir é a chamada oficial do SDK, sem alterações. Ela exige uma chave de API configurada; a execução paga com este adaptador Patchright não foi testada aqui. Coloque-a enquanto cap e a página encapsulada page ainda estiverem no escopo, em vez de executá-la como script independente.

results = await cap.solve_on_page(page)

Inspecione os itens retornados antes de continuar. O SDK expõe error, solution e filled, para que você possa distinguir uma tentativa com falha, uma solução retornada e o preenchimento do token. Não envie o formulário se a solução obrigatória estiver ausente ou se o resultado relevante indicar um erro.

Para reCAPTCHA v2, os parâmetros oficiais da tarefa explicam a relação entre a URL da página, a site key e o tipo de tarefa. Confirme que o desafio detectado corresponde à página pretendida. Uma chave copiada de outro ambiente ou de um estado antigo da página não é uma entrada útil apenas porque tem o formato correto.

Confirme o resultado da aplicação antes de continuar

O sucesso da aplicação é uma verificação separada após resolução e preenchimento. Seu fluxo de trabalho ainda pode precisar enviar um formulário ou aguardar um callback específico da página. A orientação de verificação no servidor do Google explica por que a aplicação deve validar a resposta. Defina o sinal de sucesso da sua própria aplicação, como uma mensagem de confirmação ou a seção de resultado esperado, e interrompa quando esse sinal não aparecer.

Evite tratar uma resposta HTTP, uma string de token ou filled=True como prova de que toda a tarefa de navegador teve sucesso. Se a página rejeitou a resposta, preserve um resumo útil do erro e investigue a causa antes de tentar novamente. O guia sobre tokens de CAPTCHA e cookies oferece contexto para interpretar saídas do resolvedor.

Solucione detecção vazia e falha na continuação

A solução de problemas deve começar na primeira etapa que falhou: carregamento da página, inicialização do widget, acesso ao contexto, resolução ou aceitação pela aplicação.

Comece com uma página e uma tentativa. Adicione novas tentativas limitadas apenas depois de entender quais falhas são temporárias. Reutilizar um resultado anterior após navegação pode associar uma solução ao estado errado da página, enquanto tentar novamente às cegas pode gerar custos sem corrigir o problema original.

Mudanças no Patchright e no SDK devem ser testadas juntas antes de atualizar um job de automação. Sua API familiar não garante comportamento idêntico de execução para toda extensão do Playwright ou SDK. Preserve a pequena checagem de detecção como teste de compatibilidade e execute uma checagem separada de resolução com credenciais e da aplicação no seu próprio ambiente antes do uso em produção.

Conclua a integração com uma checagem na aplicação

Uma integração útil com Patchright conecta a página atual do navegador, a tarefa de CAPTCHA suportada e um resultado observável da aplicação. Verifique primeiro o acesso ao contexto da página, depois valide a resolução paga com suas próprias credenciais e, por fim, confira se a ação pretendida no navegador foi concluída. Isso mantém o CapSolver focado na etapa de CAPTCHA, sem supor que todo problema de navegação é um desafio que ele pode resolver.

Construa fluxos de automação confiáveis com o CapSolver

Experimente o CapSolver quando seu fluxo de trabalho Patchright autorizado precisar de uma resposta de CAPTCHA suportada. Mantenha a resolução condicionada a um desafio real e verifique o resultado antes de ampliar a carga de trabalho.

FAQ

P: O Patchright resolve reCAPTCHA por conta própria?

Não. O controle do navegador não fornece um token de solução de reCAPTCHA. Se sua página autorizada ainda exige uma resposta de CAPTCHA, adicione uma etapa de resolução suportada ou use a configuração de teste de desenvolvimento da aplicação.

P: Por que um widget visível pode produzir um resultado de detecção vazio?

O script pode estar lendo um ambiente JavaScript diferente daquele em que o widget inicializou sua configuração. Verifique a inicialização e o acesso ao ambiente principal antes de supor que a site key esteja ausente.

P: Esta é uma integração oficial do Patchright?

Não. Este é um exemplo de integração usando o pacote oficial Patchright e o SDK CapSolver. O adaptador personalizado e o script de detecção foram executados com as versões listadas; a resolução paga não foi testada.

P: Preciso de uma chave de API para a checagem de setup local?

Não. A checagem de setup lê os parâmetros do widget público de desenvolvimento. Uma chave de API válida e recursos de conta são necessários para a chamada de resolução separada.

P: Posso usar Firefox ou WebKit com este exemplo?
Não. Os documentos do Patchright oferecem suporte para navegadores baseados em Chromium. O exemplo inicia seu runtime Chromium.

P: O preenchimento do token significa que o formulário foi aprovado na verificação?

Não. O preenchimento do token e a aceitação da aplicação são resultados distintos. Verifique a resposta da aplicação após a ação necessária antes de continuar seu fluxo de trabalho.