Cómo conectar Playwright a un navegador remoto con CDP
TL;DR
Playwright se conecta a un navegador Chromium existente con chromium.connectOverCDP(); launch() inicia un navegador diferente.
Una sesión administrada debe estar ready antes de solicitar credenciales CDP de corta duración y adjuntar el cliente.
La clave de API del ciclo de vida y el token de acceso CDP autentican diferentes conexiones y no se pueden sustituir entre sí.
Un apretón de manos WebSocket exitoso prueba la conectividad; una afirmación de página prueba que tu tarea alcanzó el resultado esperado.
Reutilizar una pestaña firmada existente requiere una selección de página explícita dentro de la misma sesión en ejecución.
Desconectar Playwright no confirma que el navegador administrado se haya detenido; detén la sesión por separado y verifica ended.
¿Cómo funciona la conexión de Playwright mediante CDP?
Playwright conectarse a través de CDP adjunta tu programa Node.js a un navegador Chromium que ya se está ejecutando a través del Protocolo DevTools de Chrome. El script se ejecuta en tu laptop o trabajador; el navegador renderiza páginas y realiza solicitudes de sitios web en el host remoto. Por lo tanto, un punto final alojado elimina la necesidad de instalar un binario de navegador en ese trabajador, mientras deja selectores, afirmaciones y decisiones de tareas en tu código.
Nstdata Cloud Browser proporciona navegadores en la nube administrados para la automatización del navegador y agentes de IA. Este tutorial utiliza una sesión creada en el panel de control para que puedas observar el navegador mientras demuestras la conexión. La tarea final abre una página de ejemplo pública, verifica su respuesta HTTP y valida su encabezado. Nada se envía a una cuenta o formulario.
La distinción es importante al extender un flujo de trabajo de raspado web de Playwright existente: reemplaza la conexión del navegador deliberadamente y luego verifica la selección de contexto y la limpieza. Copiar un punto final remoto en una configuración de lanzamiento local no crea el mismo modelo de ejecución.
Usa connectOverCDP() para un punto final CDP de Chromium, connect() para un servidor Playwright compatible y launch() cuando tu aplicación posee un proceso de navegador local. Estos métodos se dirigen a diferentes contratos de servidor. La API Playwright BrowserType identifica CDP como exclusivo de Chromium y de menor fidelidad que el protocolo nativo de Playwright.
Método
Superficie remota
Punto de partida apropiado
chromium.launch()
Un ejecutable de navegador iniciado por tu código
Desarrollo local y un navegador que operas tú mismo
chromium.connect()
Un punto final de servidor de navegador Playwright
Un despliegue controlado de cliente/servidor de Playwright
chromium.connectOverCDP()
Un punto final CDP de Chromium
Un navegador existente o sesión administrada compatible
La compatibilidad con CDP no promete un comportamiento idéntico para cada característica avanzada de Playwright. Prueba las operaciones que tu aplicación realmente necesita contra el navegador administrado. La navegación básica que pasa no establece que el rastreo, los flujos de trabajo de extensión, las descargas o cada opción de contexto se comporten como un navegador lanzado localmente.
¿Qué necesitas antes de conectarte?
Necesitas Node.js 22.12 o posterior, playwright-core, un espacio de trabajo Nstdata accesible, una sesión lista y la clave de API empresarial correcta. Obtén una clave personal bajo Settings → Account, o una clave de miembro del equipo bajo Members. Confirma el saldo del espacio de trabajo y la actual concesión de concurrencia antes de lanzar un navegador.
Campo
De dónde proviene
A dónde pertenece
NSTDATA_API_KEY
Tu clave de cuenta o equipo
Encabezado HTTP del ciclo de vida x-api-key, sin Bearer
NSTDATA_TEAM_ID
Un equipo unido, al usar una clave personal
Opcional x-team-id en cada solicitud del ciclo de vida
NSTDATA_SESSION_ID
La sesión que iniciaste
Rutas de búsqueda de sesión y de endpoint de credenciales
cdpUrl
Respuesta de credenciales de automatización
Argumento de endpoint de connectOverCDP()
headerName, accessToken
La misma respuesta de credenciales
Encabezados de conexión CDP
expiresAt
La misma respuesta de credenciales
Verificación de expiración antes del adjunto
Una clave de miembro del equipo está vinculada a su equipo; agregar otro ID de equipo no lo cambia. Mantén el contexto del espacio de trabajo consistente a lo largo del flujo de trabajo. No uses un JWT de inicio de sesión de panel de control como la clave de API empresarial.
El cliente a continuación fue ejercido a través de una conexión CDP real a un Chromium local fresco y aislado. La rama de credenciales de Nstdata requiere tu clave de API y no se ejecutó contra una cuenta de pago. La ejecución local verifica las operaciones del cliente; no establece autenticación de cuenta administrada ni comportamiento de facturación.
¿Cómo conectas Playwright a Nstdata Cloud Browser?
Conéctese creando una sesión visible, recuperando las credenciales para esa misma sesión y pasando esas credenciales a Playwright. La actual guía de automatización de navegador documenta el ciclo de vida y la separación de credenciales utilizados a continuación.
Paso 1: Iniciar una sesión de navegador
Abra Cloud Browser → Playground, seleccione el espacio de trabajo deseado y configure Session Name, Proxy Country, Resource Class y Session Duration. Haga clic en Launch Browser. Espere hasta que el área de herramientas muestre Running y la vista previa esté disponible.
[Captura de pantalla: Playground mostrando una sesión en ejecución y el área de herramientas CDP, con todas las URL de acceso y tokens ocultos.]
Elija la configuración de proxy y entorno antes de lanzar. El país del proxy selecciona una ubicación de salida; no promete una IP fija. La duración de la sesión es un límite automático de tiempo de vida, distinto del tiempo de espera de navegación en su script.
Paso 2: Instalar la dependencia del cliente
Cree un directorio de proyecto e instale la versión utilizada para este ejemplo. playwright-core proporciona el cliente sin descargar un navegador para el trabajador.
mkdir remote-playwright-demo
cd remote-playwright-demo
npm init -ynpminstall --save-exact playwright-core@1.65.1
Paso 3: Guardar el módulo auxiliar de conexión
Guarde el siguiente módulo como cloud-api.mjs. Busca la sesión original, requiere state === 'ready', solicita credenciales y valida la identidad y expiración de la sesión devuelta. La rama solo de loopback es para un navegador de prueba aislado para desarrolladores; la producción sigue la rama de credenciales de Nstdata.
Prerequisito de credenciales: Las solicitudes de API de Nstdata en este módulo requieren su clave, ID de sesión y contexto de equipo opcional. Suminístrelos localmente; nunca pegue sus valores reales en el control de versiones o en un registro compartido.
const root ='https://api.nstdata.io/api/v1/cloud-browser';exportasyncfunctionapi(method, path, body){const key = process.env.NSTDATA_API_KEY;if(!key)thrownewError('Set NSTDATA_API_KEY');const headers ={'x-api-key': key };if(process.env.NSTDATA_TEAM_ID) headers['x-team-id']= process.env.NSTDATA_TEAM_ID;if(body) headers['content-type']='application/json';let response;try{ response =awaitfetch(root + path,{ method, headers,redirect:'error',body: body ?JSON.stringify(body):undefined,signal:AbortSignal.timeout(20_000),});}catch{throwObject.assign(newError('API transport failed; reconcile the original operation'),{retryable:true});}const retryable = response.status===429|| response.status>=500;let result;try{ result =await response.json();}catch{throwObject.assign(newError('Invalid API JSON'),{ retryable });}if(!response.ok|| result.err===true|| result.success===false){throwObject.assign(newError(`Cloud Browser API HTTP ${response.status}`),{ retryable });}if(!result.data)thrownewError('Missing API data');return result.data;}exportasyncfunctionconnection(id){if(!id)thrownewError('Set NSTDATA_SESSION_ID');const path =`/sessions/${encodeURIComponent(id)}`;const session =awaitapi('GET', path);if(session.state!=='ready')thrownewError(`Session is ${session.state}, not ready`);const c =awaitapi('POST', path +'/automation-credentials');if(c.sessionId!== id ||!c.headerName||!c.accessToken||!(Date.parse(c.expiresAt)>Date.now())||newURL(c.cdpUrl).protocol!=='wss:'){thrownewError('Invalid or expired CDP credentials');}return{endpoint: c.cdpUrl,headers:{[c.headerName]: c.headerName.toLowerCase()==='authorization'?`Bearer ${c.accessToken}`: c.accessToken},};}exportasyncfunctionendpoint(){// An isolated local CDP endpoint can test the client without managed credentials.if(process.env.LOCAL_CDP_URL){const url =newURL(process.env.LOCAL_CDP_URL);if(!['127.0.0.1','localhost','[::1]'].includes(url.hostname)){thrownewError('LOCAL_CDP_URL must use loopback');}return{endpoint: url.href,headers:{}};}returnconnection(process.env.NSTDATA_SESSION_ID);}
Paso 4: Guardar la tarea de verificación de página
Guarde este script como connect-playwright.mjs. El script crea una página dentro del contexto predeterminado y cierra solo esa página antes de liberar el cliente. Lea la semántica de limpieza de navegador conectado antes de adaptar la limpieza a una sesión compartida.
Prerequisito de credenciales: la ruta de ejecución gestionada requiere la configuración del entorno del Paso 3. La lógica de la página y el verdadero apretón de manos CDP fueron verificados localmente.
import{ chromium }from'playwright-core';import{ endpoint }from'./cloud-api.mjs';asyncfunctionmain(){const config =awaitendpoint();let browser;let page;try{ browser =await chromium.connectOverCDP(config.endpoint,{headers: config.headers,timeout:30_000,});const context = browser.contexts()[0];if(!context)thrownewError('Default context is unavailable'); page =await context.newPage();const response =await page.goto(process.env.TARGET_URL||'https://example.com/',{waitUntil:'domcontentloaded',timeout:30_000,});if(!response?.ok())thrownewError('Navigation did not return a successful response');const heading =await page.getByRole('heading',{name:'Example Domain',exact:true}).innerText();console.log(JSON.stringify({connected: browser.isConnected(), heading,taskPassed:true}));}finally{try{if(page)await page.close();}finally{if(browser)await browser.close();}}}main().catch(()=>{console.error("Browser task failed; inspect private diagnostics and the original session."); process.exitCode=1;});
Paso 5: Ejecutar la prueba de conexión
Cree un archivo privado .env que contenga NSTDATA_API_KEY y NSTDATA_SESSION_ID, con sus valores reales después de =. Agregue NSTDATA_TEAM_ID solo si corresponde. Excluya este archivo del control de versiones, luego ejecute el comando a continuación. Deje LOCAL_CDP_URL sin establecer para la sesión administrada.
node --env-file=.env connect-playwright.mjs
Para el objetivo predeterminado, el éxito es un objeto JSON que contiene connected: true, heading: "Example Domain", y taskPassed: true. El localizador basado en roles verifica el resultado de la página en lugar de tratar un socket conectado como finalización de tarea. Si cambia TARGET_URL, cambie la aserción para que coincida con la página autorizada prevista.
Paso 6: Detener la sesión administrada
Regrese a la sesión original y haga clic en Stop Browser. Espere a que la sesión termine. En un trabajo de propiedad de API, llame a DELETE /api/v1/cloud-browser/sessions/{sessionId} y sondee la misma sesión hasta que su state sea ended. Cerrar la pestaña de vista previa o liberar Playwright no es esta operación de detención.
¿Cómo se integra Cloud Browser en un flujo de trabajo de producción de Playwright?
Nstdata Cloud Browser se adapta a un flujo de trabajo de Playwright cuando su equipo desea ejecución de navegador administrada con controles de sesión visibles. Su aplicación mantiene la propiedad de la tarea, el esquema de salida y los criterios de aceptación. El servicio proporciona la sesión de navegador remoto y su superficie de conexión. El mismo navegador en ejecución se puede ver manualmente y operar a través de CDP. Eso hace que una tarea fallida sea inspeccionable sin asumir que el script eligió la página o cuenta correcta.
Ejecución administrada: adjunte un cliente desde un trabajador que no tenga su propia instalación de Chromium; mantenga los tiempos de espera y aserciones a nivel de aplicación.
Configuración de proxy a nivel de sesión: use la configuración de proxy incorporada seleccionada sin agregar una puerta de enlace de proxy separada a este script de cliente; mida el tráfico del proxy junto con el tiempo de ejecución del navegador.
Inspección en vivo: observe la página activa y los diagnósticos disponibles cuando falla un selector; la inspección no repara automáticamente la lógica de la aplicación.
¿Por qué falla una conexión CDP o abre la página equivocada?
Una conexión CDP falla cuando su endpoint, credenciales, estado de sesión o ruta de red son inválidos; la página equivocada generalmente indica una selección incorrecta de contexto o pestaña.
Síntoma
Causa probable
Próxima acción
La autenticación HTTP del ciclo de vida falla
Clave incorrecta o contexto de equipo
Verifique x-api-key y x-team-id consistente
La autorización de CDP falla
Token expirado o encabezado incorrecto
Consulte la misma sesión lista y solicite credenciales nuevas
El navegador se conecta pero la aplicación está desconectada
Se utilizó una nueva página/contexto o otra sesión
Seleccione explícitamente la pestaña autorizada existente
La aserción de encabezado se agota
Página equivocada, redirección o contenido cambiado
Inspeccione la página seleccionada y el marcador esperado
La sesión está ended
La vida útil ha expirado o el navegador fue detenido
Iniciar una tarea deliberadamente nueva; no reutilizar credenciales antiguas
Evite reiniciar repetidamente todo el trabajo para solucionar problemas de autenticación. Un nuevo ID de sesión puede ocultar la falla original y crear un uso adicional en tiempo de ejecución. Mantenga los identificadores de solicitud/sesión en los registros operativos, mientras redacta los tokens de acceso y las URL completas de CDP.
¿Qué debes verificar antes de poner la integración en producción?
Verifique la conexión gestionada, la tarea de página real y la finalización de la sesión confirmada como verificaciones separadas. Ejecute un canario de producción estrecho con el espacio de trabajo y el objetivo previstos, registre su ID de sesión y la salida aceptada, y confirme ended después. Expanda solo después de que sus interacciones requeridas funcionen con el navegador remoto. Esto le da al equipo una prueba de aceptación repetible en lugar de una demostración solo de conexión.
Q: ¿Puede Playwright conectarse a través de CDP a Firefox o WebKit?
No. La conexión CDP de Playwright es para navegadores basados en Chromium. Utilice el flujo de trabajo de navegador soportado correspondiente cuando su prueba requiera Firefox o WebKit.
Q: ¿Instalo Chromium en el trabajador?
No se requiere ningún binario de navegador para este ejemplo de conexión remota. Instale playwright-core en el trabajador y conéctese al navegador que se ejecuta en la sesión gestionada.
Q: ¿El script de inicio rápido reutiliza mi pestaña iniciada?
No. Este script crea una nueva página. Para una entrega manual de inicio de sesión, seleccione la página existente por su origen esperado, camino y marcador de cuenta dentro de la misma sesión en ejecución.
Q: ¿Puedo usar la clave de API comercial como token de CDP?
No. Utilice la clave comercial para solicitudes de ciclo de vida, luego obtenga el accessToken de corta duración y el headerName de la respuesta de credenciales de automatización.
Q: ¿Desconectar restablece la duración de la sesión?
No. Reconectar un cliente no extiende la duración de la sesión gestionada. Consulte el estado original antes de solicitar nuevas credenciales.
Q: ¿Es suficiente una verificación de encabezado exitosa para producción?
La verificación del encabezado es suficiente para esta demostración de conexión. Las tareas de producción necesitan sus propios criterios de aceptación, manejo de fallos y limpieza confirmada, utilizando solo sitios web y cuentas que está autorizado a automatizar.
Automatización del navegador con intervención humana: del inicio de sesión manual a tareas automatizadas
Deje que un operador inicie sesión a través de Live View antes de que un script verifique la misma pestaña de la aplicación. Defina la propiedad, las afirmaciones de cuenta, los límites de aprobación y la limpieza sin incluir una contraseña en la automatización.
Ivy Lin
Nov. 17th 2026
Inicia navegadores en la nube bajo demanda
Gestiona huellas digitales y CAPTCHA
Automatiza flujos de trabajo e impulsa agentes de IA
Desde la extracción de datos web y las pruebas hasta la automatización con IA, ejecútalo todo en la nube.