Como detectar CAPTCHA em testes de navegador com Robot Framework

Resumo

• O Robot Framework pode chamar uma pequena biblioteca de palavras‑chave em Python que usa o SDK oficial CapSolver Core para inspecionar uma página com CAPTCHA.
• O exemplo retorna para o teste Robot o tipo de CAPTCHA detectado, a URL da página e a sitekey.
• Execute o teste contra uma página de desenvolvimento própria usando a chave pública de teste do reCAPTCHA do Google.
• A palavra‑chave abre e fecha seu próprio navegador; ela não se conecta a uma sessão do SeleniumLibrary ou do Browser Library.
• A detecção confirma a etapa de descoberta de inputs. Ela nem resolve o CAPTCHA nem prova que um formulário em produção aceite o resultado de um resolvedor.

Um teste de navegador no Robot Framework pode falhar porque a página agora exibe um CAPTCHA em vez do conteúdo que a próxima asserção espera. Aumentar um timeout genérico não explica essa mudança. Uma verificação específica de CAPTCHA pode dar ao teste um resultado útil: o tipo de desafio e os parâmetros de que um fluxo aprovado de resolução precisaria.

O Robot Framework é um framework open source para testes de aceitação e automação de processos robóticos. Sua sintaxe de palavras‑chave permite que as equipes expressem verificações enquanto bibliotecas em Python implementam as operações subjacentes. Este tutorial conecta uma palavra‑chave em Python ao CapSolver por meio do SDK oficial Core e verifica que o Robot recebe resultados reais de detecção a partir de uma página no navegador.

Onde a detecção de CAPTCHA deve entrar em um teste Robot

A detecção de CAPTCHA deve ocorrer em um ponto de verificação conhecido da página, antes de o teste tratar uma página bloqueada como uma resposta normal da aplicação.

Por exemplo, um fluxo de navegador permitido espera um formulário de busca, mas em vez disso encontra um desafio. A primeira pergunta útil é se há um CAPTCHA suportado presente. Um resultado de reconhecimento pode então informar um próximo passo controlado: usar a integração de resolução documentada, pausar para ação humana ou registrar uma falha de teste específica.

Isso é diferente de tratar todo elemento ausente como um CAPTCHA. Uma página também pode falhar porque seu script de aplicação não carregou, sua rota mudou ou um seletor está errado. Mantenha a detecção de CAPTCHA separada desses diagnósticos.

O guia do usuário do Robot Framework documenta bibliotecas de teste em Python e a execução de palavras‑chave. A pequena biblioteca abaixo usa esse ponto de extensão. É uma integração de exemplo, não uma afirmação de que o Robot Framework inclui uma biblioteca CapSolver nativa.

Instale os pacotes em um único ambiente

Instale o Robot Framework, o Playwright e o Core SDK no mesmo ambiente Python para que o runner de testes possa importar os três.

O exemplo usa Python 3.12, Robot Framework 7.5, Playwright 1.64.0 e capsolver-core 0.1.1. O repositório oficial do framework é a fonte para o contexto do projeto e rotas de instalação suportadas.

python -m pip install robotframework==7.5 playwright==1.64.0 capsolver-core==0.1.1
python -m playwright install chromium

Execute a instalação e os testes com o mesmo interpretador. Uma falha de configuração comum é instalar uma biblioteca de navegador em um ambiente e executar o Robot a partir de outro. A importação então falha antes mesmo de a página ser aberta.

Este exemplo apenas detecta um widget e lê seus parâmetros públicos. A resolução paga exigiria uma chave de API de resolvedor válida, prontidão de conta e um fluxo de trabalho aprovado separado. Nenhum resultado pago é produzido pelo teste abaixo.

Crie um fixture de CAPTCHA próprio

Crie index.html em um diretório de fixtures dedicado e sirva‑o na sua própria máquina.

O Google documenta a chave pública de teste do reCAPTCHA v2 em sua orientação para testes automatizados. O fixture usa essa chave para carregar um widget reconhecível sem usar a configuração de um site de produção.

<!doctype html><html><head><title>Owned CAPTCHA test fixture</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>

Inicie um servidor local a partir desse diretório:

python -m http.server 8766 --bind 127.0.0.1

O script do widget ainda precisa de acesso de rede ao Google. Se o widget do fixture não carregar, verifique esse pré‑requisito antes de interpretar um resultado de detecção vazio. O servidor local expõe o fixture apenas na interface de loopback.

Uma chave de teste é útil para verificar a fiação e o reconhecimento. Ela não é evidência representativa da dificuldade de desafios de produção, do desempenho de resolução paga ou da aceitação pela aplicação. Mantenha esses testes separados na checklist de release.

Adicione a biblioteca de palavra‑chave em Python

Salve a biblioteca a seguir como CaptchaCheck.py ao lado do seu arquivo de teste Robot.

A biblioteca chama o método documentado get_captcha_info do Core SDK. O wrapper específico para Robot é deliberadamente pequeno: ele inicia um event loop, abre um navegador, lê as informações e fecha o navegador em um bloco finally.

import asyncio
from robot.api.deco import keyword
from capsolver_core import create_capsolver
from playwright.async_api import async_playwright

@keyword("Inspect CAPTCHA Page")
def inspect_captcha_page(url):
    return asyncio.run(_inspect(url))

async def _inspect(url):
    async with async_playwright() as pw:
        browser = await pw.chromium.launch(headless=True)
        try:
            page = await browser.new_page()
            await page.goto(url, wait_until="networkidle")
            async with create_capsolver() as cap:
                infos = await cap.get_captcha_info(page)
            return [{"type": item.type.value, "url": item.website_url,
                     "site_key": item.website_key} for item in infos]
        finally:
            await browser.close()

A lista retornada contém dicionários simples, o que é conveniente para asserções no Robot. Uma lista vazia significa que essa inspeção não retornou nenhuma informação correspondente. Ela não deve ser convertida em uma alegação de que nenhum possível desafio existe em nenhum ponto do fluxo.

A espera pelo carregamento da página é apropriada para este pequeno fixture. Uma aplicação em produção com atividade de rede persistente pode precisar de uma condição de prontidão diferente, específica da página. Não copie networkidle para toda aplicação presumindo que isso prova que o widget relevante terminou de renderizar.

Resgate Seu Código de Bônus 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 Dashboard CapSolver

Execute o teste Robot e inspecione o resultado

Salve o seguinte como captcha.robot ao lado da biblioteca e execute enquanto o servidor local do fixture estiver disponível.

*** Settings ***
Library    CaptchaCheck.py
Library    Collections

*** Variables ***
${PAGE_URL}    http://127.0.0.1:8766/

*** Test Cases ***
Identify The Fixture CAPTCHA
    ${items}=    Inspect CAPTCHA Page    ${PAGE_URL}
    Should Not Be Empty    ${items}
    ${first}=    Get From List    ${items}    0
    Should Be Equal    ${first}[type]    reCaptchaV2
    Log    ${items}

python -m robot --outputdir results captcha.robot

O teste verifica se o detector retornou um resultado e se o fixture é identificado como reCaptchaV2. Seu log contém a URL da página retornada e a sitekey pública. O relatório gerado pelo Robot informa se essas asserções passaram.

Uma aprovação estabelece uma cadeia específica: o Robot invocou sua palavra‑chave em Python, o Playwright abriu o fixture, o Core SDK inspecionou a página real e os dados retornados chegaram às asserções do Robot. O código fecha o navegador mesmo quando ocorre uma exceção.

Leia as falhas no estágio em que acontecem. Um erro de import é um problema de dependência. Um erro de navegação é um problema de acesso à página. Um timeout pode significar que o fixture não estabilizou. Uma falha na asserção do tipo significa que os dados retornados não corresponderam à expectativa do fixture. Essas condições precisam de correções diferentes.

Conecte a detecção a um fluxo de resolução com cuidado

A detecção fornece informações para uma decisão de resolução, mas o próximo passo deve preservar o contexto de página de que a tarefa necessita.

O guia oficial do SDK descreve a resolução em navegador como uma operação separada. Se o seu fluxo de produção precisa resolver e continuar na mesma página, mantenha essa página e seu contexto de navegador vivos durante a operação. A palavra‑chave de diagnóstico neste artigo fecha o navegador e, portanto, não é um passo de continuação imediato para uma sessão autenticada existente.

Equipes que já usam SeleniumLibrary ou Robot Framework Browser também devem distinguir seu navegador ativo daquele aberto por este exemplo. Compartilhar uma URL não compartilha cookies, interações anteriores ou um objeto de página. Evite afirmar que um desafio foi resolvido no navegador ativo do teste quando o trabalho na verdade ocorreu em outro.

Para testes de regressão comuns em sites próprios, as chaves de teste do provedor podem ser a opção mais simples. Use um caminho de resolução real apenas quando o objetivo do teste exigir validar essa integração. O guia de chaves de teste do reCAPTCHA explica melhor essa fronteira.

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

Use um pequeno checkpoint explícito para distinguir um CAPTCHA reconhecido de uma falha genérica de elemento. O CapSolver fornece a capacidade de detecção neste exemplo; o Robot Framework transforma seu resultado em uma asserção de teste legível. Adicione resolução paga apenas como um passo separado, verificado, com a propriedade correta da página e verificações do resultado da aplicação.

FAQ

P: Este teste Robot resolve o CAPTCHA?

Não. Ele detecta o CAPTCHA do fixture e retorna seus parâmetros públicos. O teste não solicita uma solução paga nem verifica o envio de um formulário em produção.

P: Isto é um plugin oficial do Robot Framework?

Não. O wrapper de palavra‑chave em Python é um exemplo construído em torno do mecanismo de bibliotecas documentado do Robot Framework e do SDK Core oficial. O wrapper exato está incluído para que seu comportamento possa ser inspecionado.

P: Posso usar a mesma palavra‑chave dentro de testes com SeleniumLibrary?

Você pode chamar a palavra‑chave, mas ela abre um navegador Playwright separado. Ela não inspeciona nem continua a sessão de navegador do SeleniumLibrary. Uma integração com sessão existente precisa de uma transferência explícita e suportada.

P: Por que o fixture retorna uma lista vazia?

Verifique se o script do widget carregou, se a página esperada está sendo servida e se o SDK oferece suporte ao desafio presente. Um resultado vazio por si só não identifica a causa.

P: Preciso de uma chave de API de resolvedor para este exemplo?

A verificação demonstrada de detecção de parâmetros não envia uma tarefa de resolução paga. Um passo de resolução em produção requer as credenciais e pré‑requisitos documentados para essa operação.

P: Todo teste automatizado deve chamar um resolvedor de CAPTCHA?

Não. Use mecanismos de teste do provedor para testes de regressão rotineiros em sites próprios quando apropriado. Reserve testes de integração com resolvedor para o fluxo de trabalho que eles se destinam a validar, e mantenha‑os delimitados.