Cómo agregar un solucionador CAPTCHA a la automatización de Patchright

Resumen

• Patchright controla un navegador Chromium; un CAPTCHA que requiere una respuesta sigue necesitando un paso de resolución por separado.
• La detección de reCAPTCHA puede depender del estado de JavaScript en el entorno principal de la página, mientras que Patchright evalúa scripts en un entorno aislado de forma predeterminada.
• Un pequeño adaptador de página permite que el SDK oficial CapSolver Core inspeccione la misma página de Patchright sin abrir un segundo navegador.
• Comienza con un widget de prueba local y luego valida por separado la resolución de pago y la respuesta de la aplicación antes de usar la integración en un flujo de trabajo más amplio.

Un script de Patchright puede navegar correctamente, encontrar el formulario y luego detenerse en un widget de reCAPTCHA. Cambiar de biblioteca de navegador no proporciona la respuesta que el widget y la aplicación requieren. En ese punto necesitas un resolvedor de CAPTCHA, además de una comprobación de que la aplicación aceptó el resultado.

Este tutorial de resolución de CAPTCHA con Patchright conecta una sesión de navegador en Python con CapSolver a través de su SDK oficial Core. El detalle útil es el entorno de JavaScript de la página: leer el DOM visible y leer la configuración propiedad de la página de reCAPTCHA son operaciones distintas. El ejemplo siguiente gestiona esa distinción, mantiene una sola página abierta y verifica la detección en un fixture de desarrollo local. Usa este enfoque para páginas que te pertenecen o para las que tienes permiso de automatización.

Qué es Patchright y cuándo ayuda un resolvedor de CAPTCHA

Patchright es un derivado mantenido por la comunidad de Playwright con una interfaz de automatización en Python similar. El repositorio oficial de Python documenta su soporte para Chromium y su uso como importación de reemplazo para Playwright. Patchright no admite Firefox ni WebKit.

Los desarrolladores usan Patchright para controlar páginas, interactuar con elementos y ejecutar flujos de trabajo en el navegador. Un resolvedor se vuelve relevante cuando un CAPTCHA compatible impide que un flujo de trabajo autorizado complete un formulario o alcance su resultado esperado. Si tu página ya es accesible, no hay motivo para hacer una solicitud de resolución de pago.

La integración tiene tres responsabilidades separadas. Patchright se encarga de la navegación y del ciclo de vida de la página. El resolvedor lee las entradas de los desafíos compatibles y solicita una solución. Tu flujo de trabajo de aplicación decide si el formulario o la página posterior realmente tuvo éxito. El glosario de CAPTCHA explica el mecanismo de verificación detrás de esta separación.

Para pruebas rutinarias de tu propia aplicación, prefiere la configuración de desarrollo del proveedor de CAPTCHA. La comprobación de la integración con un resolvedor de pago es una tarea separada de probar si tu validación de formularios habitual funciona.

Por qué la detección de reCAPTCHA necesita el contexto adecuado de página

La detección de reCAPTCHA puede necesitar configuración creada por el widget en el entorno principal de JavaScript de la página. La opción documentada de evaluate() de Patchright, isolated_context, tiene como valor predeterminado True; por lo tanto, es posible que los globales de JavaScript propiedad de la página no estén presentes en una evaluación normal incluso cuando el widget es visible.

En el ejemplo controlado usado para esta guía, la evaluación predeterminada no podía ver window.___grecaptcha_cfg, mientras que la evaluación con isolated_context=False sí podía. El SDK necesita acceso a ese estado de la página para esta ruta de reCAPTCHA. Por lo tanto, un tiempo de espera o un resultado de detección vacío deberían dar lugar primero a una comprobación de contexto antes de que cambies la clave de sitio o envíes solicitudes repetidas de resolución.

El adaptador siguiente reenvía las evaluaciones del SDK al entorno principal de la página. No modifica los archivos instalados de Patchright ni cambia el entorno para cada operación del navegador. La navegación y los localizadores normales permanecen en raw_page; solo el objeto de página pasado al SDK usa este contenedor. Trátalo como un ejemplo de integración probado para las versiones listadas a continuación, no como una afirmación de asociación oficial con Patchright ni de compatibilidad universal.

Instala los paquetes y comprueba los prerrequisitos

El ejemplo usa Python 3.12, Patchright 1.64.1 y capsolver-core 0.1.1. Instala los paquetes en un entorno aislado e instala el runtime de Chromium de Patchright. Fija estas versiones para la comprobación de configuración de modo que una actualización de paquete no cambie su comportamiento silenciosamente.

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

El ejemplo de detección no necesita una clave de API de CapSolver. La resolución real requiere tu propia clave válida y recursos suficientes en la cuenta. Configura el cliente con la opción documentada create_capsolver(api_key=...) y guarda la clave en la configuración secreta de tu aplicación. La guía del Core SDK documenta la creación del cliente, la detección, la resolución y los campos de resultados.

La comprobación de configuración que aparece a continuación se ejecutó contra una página local usando la clave pública de prueba de reCAPTCHA de Google. La resolución de pago, el relleno del token y la aceptación por parte de la aplicación de un token resuelto no se ejecutaron para esta guía. No uses este fixture como prueba de tasa de éxito en producción.

Ejecuta una comprobación local de configuración de Patchright y el SDK

La comprobación de configuración abre un fixture local, espera a que el widget de prueba se inicialice e imprime los parámetros del CAPTCHA devueltos por el SDK oficial. Guárdalo como patchright_sdk_check.py y ejecútalo con Python en el entorno anterior.

La URL local se sirve a través de una ruta del navegador, por lo que no se necesita un servidor web separado. El script del widget sigue cargándose desde Google y requiere acceso a la red. La clave de sitio pública proviene de la guía de pruebas de reCAPTCHA de Google; es una clave de desarrollo, no una 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())

La ejecución correcta devolvió un elemento con tipo reCaptchaV2, la URL de la página local y la clave de sitio pública de prueba. Ese resultado confirma que Patchright abrió la página y que el SDK pudo leer el widget inicializado a través del adaptador. No contiene un token resuelto y no demuestra que un formulario de producción lo aceptaría.

El navegador se cierra en finally, incluso cuando falla la carga del widget o la detección. El cliente del SDK también sale de su contexto asincrónico. Mantén esa limpieza al mover la integración a un script más largo, especialmente cuando un desafío provoca una excepción.

Canjea tu código de bonificación de CapSolver

Aumenta tu presupuesto de automatización al instante.
Usa el código de bonificación CAP26 al recargar tu cuenta de CapSolver para obtener un 5% extra de bonificación en cada recarga, sin límites.
Canjéalo ahora en tu Panel de CapSolver

Añade la resolución después de la comprobación de detección

La resolución pertenece dentro de los contextos activos del navegador y del SDK, antes de que la página se cierre o navegue a otro lugar. En tu página de aplicación autorizada, crea el cliente del SDK con tu clave, envuelve la página actual de Patchright como se muestra arriba y usa la llamada oficial en modo navegador.

La siguiente línea es la llamada oficial del SDK, sin cambios. Requiere una clave de API configurada; la ejecución de pago con este adaptador de Patchright no se probó aquí. Colócala mientras cap y la page envuelta siguen en alcance, en lugar de ejecutarla como un script independiente.

results = await cap.solve_on_page(page)

Inspecciona los elementos devueltos antes de continuar. El SDK expone error, solution y filled para que puedas distinguir un intento fallido, una solución devuelta y el relleno del token. No envíes el formulario si falta la solución requerida o si el resultado relevante informa de un error.

Para reCAPTCHA v2, los parámetros oficiales de la tarea explican la relación entre la URL de la página, la clave de sitio y el tipo de tarea. Confirma que el desafío detectado coincide con la página prevista. Una clave copiada de otro entorno o de un estado antiguo de la página no es una entrada útil solo porque tenga el formato correcto.

Confirma el resultado de la aplicación antes de continuar

El éxito de la aplicación es una comprobación separada después de la resolución y el relleno. Tu flujo de trabajo aún puede necesitar enviar un formulario o esperar una devolución de llamada específica de la página. La guía de verificación del lado del servidor de Google explica por qué la aplicación debe validar la respuesta. Define la señal de éxito en tu propia aplicación, como un mensaje de confirmación o la sección de resultado esperada, y detente cuando esa señal no llegue.

Evita tratar una respuesta HTTP, una cadena de token o filled=True como prueba de que toda la tarea del navegador tuvo éxito. Si la página rechazó la respuesta, conserva un resumen de error útil e inspecciona la causa antes de reintentar. La guía sobre tokens de CAPTCHA y cookies ofrece contexto para interpretar las salidas del resolvedor.

Soluciona la falta de detección y los fallos al continuar

La solución de problemas debe comenzar en el primer paso que falló: carga de la página, inicialización del widget, acceso al contexto, resolución o aceptación por parte de la aplicación.

Comienza con una página y un intento. Añade reintentos acotados solo después de entender qué fallos son temporales. Reutilizar un resultado anterior tras una navegación puede asociar una solución con un estado de página incorrecto, mientras que reintentar a ciegas puede aumentar los costes sin corregir el problema original.

Los cambios en Patchright y en el SDK deben probarse juntos antes de actualizar un trabajo de automatización. Su API familiar no garantiza un comportamiento de ejecución idéntico para cada extensión de Playwright o SDK. Conserva la pequeña comprobación de detección como prueba de compatibilidad y ejecuta una comprobación separada de resolución con credenciales y aceptación por parte de la aplicación en tu propio entorno antes de usarla en producción.

Termina la integración con una comprobación de la aplicación

Una integración útil de Patchright conecta la página actual del navegador, la tarea de CAPTCHA compatible y un resultado observable de la aplicación. Verifica primero el acceso al contexto de la página, luego valida la resolución de pago con tus propias credenciales y, por último, comprueba que la acción de navegador prevista se completó. Esto mantiene a CapSolver centrado en el paso del CAPTCHA sin suponer que todos los problemas de navegación son desafíos que puede resolver.

Crea flujos de trabajo de automatización fiables con CapSolver

Prueba CapSolver cuando tu flujo de trabajo autorizado con Patchright necesite una respuesta de un CAPTCHA compatible. Mantén la resolución condicionada a un desafío real y verifica el resultado antes de ampliar la carga de trabajo.

Preguntas frecuentes

P: ¿Patchright resuelve reCAPTCHA por sí mismo?

No. El control del navegador no proporciona un token de solución de reCAPTCHA. Si tu página autorizada sigue requiriendo una respuesta de CAPTCHA, añade un paso de resolución compatible o usa la configuración de pruebas de desarrollo de la aplicación.

P: ¿Por qué un widget visible puede producir un resultado de detección vacío?

Es posible que el script esté leyendo un entorno de JavaScript diferente de aquel en el que el widget inicializó su configuración. Comprueba la inicialización y el acceso al entorno principal antes de asumir que falta la clave de sitio.

P: ¿Es esta una integración oficial de Patchright?

No. Es un ejemplo de integración que usa el paquete oficial de Patchright y el SDK de CapSolver. El adaptador personalizado y el script de detección se ejecutaron con las versiones listadas; la resolución de pago no se probó.

P: ¿Necesito una clave de API para la comprobación de configuración local?

No. La comprobación de configuración lee los parámetros del widget público de desarrollo. Se requiere una clave de API válida y recursos en la cuenta para la llamada de resolución por separado.

P: ¿Puedo usar Firefox o WebKit con este ejemplo?
No. Los documentos de Patchright admiten navegadores basados en Chromium. El ejemplo inicia su runtime de Chromium.

P: ¿El relleno del token significa que el formulario pasó la verificación?

No. El relleno del token y la aceptación de la solicitud son resultados independientes. Verifica la respuesta de la aplicación después de la acción requerida antes de continuar tu flujo de trabajo.