Playwright con perfiles de identidad coherentes

Playwright puede controlar un ejecutable de BotBrowser con una identidad basada en perfil, pero no garantiza la aceptación de un sitio de terceros ni sustituye los controles de cuenta y privacidad de la aplicación.

TL;DR

• Usa playwright-core con el ejecutable de BotBrowser y un perfil aprobado, sin descargar un navegador incluido.
• Mantén juntos el perfil, la ruta, la pareja de versiones, el ciclo de vida del contexto y el registro de limpieza.
• Valida una sesión antes de aumentar la concurrencia y conserva resultados operativos sin recopilar contenido de páginas por defecto.

Contents

• Cómo encajan Playwright y BotBrowser
• Lanzamiento, contextos y comprobaciones de la aplicación
• Validación y pareja de versiones
• Responsabilidad, coherencia de red y telemetría
• Despliegue, reversión y solución de problemas
• Conclusión práctica

Cómo encajan Playwright y BotBrowser

Playwright ofrece automatización del navegador, esperas fiables y una API clara para los flujos de página. BotBrowser añade una identidad de navegador respaldada por perfiles para trabajos autorizados de privacidad y compatibilidad. Playwright sigue encargándose de la navegación y la interacción, mientras el perfil seleccionado gobierna la identidad que presenta el navegador.

La integración empieza en el lanzamiento. La instalación, la política de proxy, la propiedad de los contextos, el viewport y el ciclo de vida del proceso deben describir el mismo despliegue. Los ejemplos siguientes usan flujos compatibles de Playwright e indican los puntos que conviene comprobar con las versiones que se ejecutan en producción.

La automatización estándar del navegador puede exponer características del host que quedan fuera del límite de privacidad previsto. Un navegador respaldado por perfiles permite que un despliegue autorizado controle esa exposición y mantenga alineadas las características relacionadas durante toda la sesión.

Playwright gestiona la navegación, las comprobaciones de la aplicación y la lógica de interacción. BotBrowser mantiene la identidad de la familia de navegador seleccionada. Esta separación deja la configuración de privacidad fuera de los scripts de página y da a los operadores una asignación de perfil revisada que pueden seguir junto con cada proceso del navegador o flujo de contexto compatible. Los selectores, las aserciones y la intercepción de red siguen usando las API de Playwright.

Por qué playwright-core y no playwright

El paquete npm estándar playwright incluye su propio binario de Chromium y descarga los binarios del navegador de forma automática. Es cómodo para un uso general, pero entra en conflicto con BotBrowser, que proporciona su propio binario de Chromium modificado.

El paquete playwright-core ofrece la misma API sin navegadores incluidos. Exige indicar un executablePath al lanzar, que es justo la forma de apuntar Playwright al binario de BotBrowser.

# Instala playwright-core, no playwright
npm install playwright-core

Mantén pequeña la configuración de lanzamiento

Indica a playwright-core el ejecutable de BotBrowser y asigna el perfil aprobado antes de abrir una página. Mantén visibles en la configuración del despliegue la versión, el perfil y el modo del navegador. Una superficie de lanzamiento pequeña resulta más fácil de revisar, reproducir y revertir.

Añade opciones solo cuando la aplicación tenga un requisito documentado para ellas. Guarda los secretos en el sistema de gestión de secretos del despliegue. Registra las versiones de BotBrowser y Playwright junto con el resultado del trabajo para que soporte pueda reproducir la misma pareja de versiones.

Contextos de navegador en Playwright

Un contexto de navegador de Playwright es un límite de sesión para cookies, almacenamiento, permisos y caché. Úsalo para separar cuentas de prueba autorizadas y estados de aplicación. Asigna un responsable claro a cada contexto y ciérralo cuando termine esa prueba.

La asignación del perfil depende del flujo compatible de BotBrowser que se utilice. Aplica la asignación aprobada antes de que el contexto abra su primera página y mantenla estable durante toda la vida del contexto.

Alternativas y sus límites

Navegador incluido. El navegador incluido con Playwright sirve para automatización general, pero no carga un paquete de perfil de BotBrowser. Usa playwright-core para que la biblioteca de automatización se conecte al binario de BotBrowser elegido para el despliegue.

Cambios a nivel de página. Un script de página puede modificar valores aislados después de la navegación, pero no crea una identidad de navegador coherente entre el inicio, los procesos de trabajo, los gráficos, los medios y la red. Mantén la configuración de identidad en el perfil del navegador en lugar de añadir scripts de página.

Builds propios. Mantener un build privado de Chromium exige seguir las versiones, empaquetar y distribuir por plataforma. BotBrowser proporciona binarios versionados y paquetes de perfil correspondientes para que la aplicación se centre en el flujo de Playwright.

Lanzamiento, contextos y comprobaciones de la aplicación

Prerrequisitos

• Binario de BotBrowser (descargar desde GitHub)
• Un archivo de perfil de huella digital (formato .enc)
• Node.js 18+
• npm install playwright-core

Asegúrate de que el binario de BotBrowser tenga permiso de ejecución:

chmod +x path/to/botbrowser/chrome

Lanzamiento básico

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: 'path/to/botbrowser/chrome',
    args: ['--bot-profile=/absolute/path/to/profile.enc'],
    headless: true,
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');

  // Aquí va tu lógica de automatización
  const title = await page.title();
  console.log('Page title:', title);

  await browser.close();
})();

Perfil, ruta de red y configuración regional

Revisa la familia del perfil, la ruta de red aprobada, la configuración regional, la zona horaria y la cuenta de la aplicación como una sola decisión de despliegue. Sus supuestos regionales deben coincidir. Pasa la ruta con --proxy-server en args en lugar de usar las opciones de proxy propias de Playwright, y utiliza una ruta absoluta para --bot-profile.

Entrega las credenciales mediante el almacén de secretos del despliegue y no las incluyas en trazas, capturas ni salida del terminal. El mismo lanzamiento puede llevar --bot-timezone, --bot-locale y --bot-languages cuando la prueba autorizada necesite una región concreta.

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/absolute/path/to/profile.enc',
    // Entrega la ruta desde el almacén de secretos del despliegue
    `--proxy-server=${process.env.BOT_PROXY_URL}`,
    '--bot-timezone=Europe/Berlin',
    '--bot-locale=de-DE',
    '--bot-languages=de-DE,de,en-US,en',
  ],
  headless: true,
});

Comprobación de aislamiento de sesiones

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: ['--bot-profile=/absolute/path/to/profile.enc'],
  headless: true,
});

const context1 = await browser.newContext();
const context2 = await browser.newContext();

const page1 = await context1.newPage();
const page2 = await context2.newPage();

await page1.goto('https://staging.example.test/account-a');
await page2.goto('https://staging.example.test/account-b');

// Ejecuta las aserciones normales de la aplicación para cada cuenta de prueba autorizada.
await context1.close();
await context2.close();

La comprobación debe usar tu propia aplicación de staging y las aserciones habituales del producto. Confirma que el inicio de sesión, el cierre de sesión, la limpieza del almacenamiento, la cancelación y el cierre del contexto se comportan como exige el plan de pruebas. No recopiles señales del navegador ni datos de página que la prueba de la aplicación no necesite.

Intercepción de red

const context = await browser.newContext();
const page = await context.newPage();

// Intercepta solicitudes con la API habitual de Playwright
await page.route('**/*.png', route => route.abort());
await page.route('**/api/**', route => {
  console.log('API request:', route.request().url());
  route.continue();
});

await page.goto('https://example.com');

Gestión del viewport

// Opción 1: deja que el perfil controle el viewport (recomendado)
const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: ['--bot-profile=/absolute/path/to/profile.enc'],
  headless: true,
});
const context = await browser.newContext(); // Sin sobrescritura de viewport

// Opción 2: viewport explícito (puede entrar en conflicto con perfiles móviles)
const context2 = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
});

Los perfiles móviles deben conservar el viewport definido por el perfil. BotBrowser 150.0.7871.46 mantiene alineado el visual viewport cuando un teclado en pantalla cambia el área visible de la página. Evita sobrescribir el viewport desde Playwright salvo que la prueba requiera explícitamente otras dimensiones.

Capturas de pantalla y PDF

const page = await context.newPage();
await page.goto('https://example.com');

// Captura un artefacto exigido por el plan de prueba autorizado.
await page.screenshot({ path: 'screenshot.png', fullPage: true });

// Generación de PDF
await page.pdf({ path: 'page.pdf', format: 'A4' });

Validación y pareja de versiones

Empieza con una sesión de preproducción autorizada. Confirma que el navegador se inicia, que la primera navegación termina, que las capturas se completan y que el navegador se cierra sin errores de perfil o de proceso. Repite con el mismo perfil y la misma ruta para que la base siga siendo comparable.

En la automatización por lotes, registra los errores de lanzamiento, el estado de salida del navegador y el stderr de cada proceso de trabajo. Mantén fijos la versión del binario, el paquete de perfil, la política de proxy y la política de viewport mientras validas un cambio de integración.

Lanzamientos headless y validación del perfil

BotBrowser 150.0.7871.46 informa en la salida del terminal de perfiles ausentes, inválidos, caducados o de otra versión durante un lanzamiento headless. Carga un paquete de perfil correspondiente antes de navegar y trata un fallo de validación del perfil como un inicio fallido del proceso de trabajo.

Usa un directorio de datos de usuario independiente para cada proceso del navegador y conserva el stderr de cada proceso de trabajo. Empieza con un grupo pequeño, confirma que las páginas con perfil se abren con normalidad y aumenta después el paralelismo con una cola limitada. Cierra páginas, contextos y navegador en todas las rutas de salida.

Mantén explícita la pareja de versiones

Registra juntos la versión de BotBrowser y la del paquete de Playwright. Las bibliotecas de automatización evolucionan junto con los protocolos del navegador, y un flujo estable con una pareja de versiones no debe suponerse idéntico cuando cambia cualquiera de los dos lados. Fija ambas versiones en el archivo de bloqueo de la aplicación o en el manifiesto del despliegue y actualízalas con la misma revisión que usas para otras dependencias de producción.

Una comprobación de versión debe usar páginas representativas propias del equipo o autorizadas expresamente para pruebas. Confirma la navegación normal, las interacciones necesarias, las aserciones de la aplicación, las capturas o documentos que usa el trabajo y el cierre ordenado. Incluye los modos headless y con interfaz solo cuando ambos formen parte del despliegue. Un modo que nunca se publica no necesita ampliar la matriz de pruebas.

Trata el paquete de perfil, el binario del navegador, el paquete de automatización y la imagen del sistema operativo como una única unidad de versión trazable. Si la aplicación se ejecuta en contenedores, registra también la revisión de la imagen. Así un resultado inesperado se puede reproducir sin recopilar datos de página ajenos a la integración.

Revisa una pareja de versiones candidata

Prepara la candidata en la misma clase de host que usa el despliegue. Restaura el archivo de bloqueo de dependencias, instala la versión elegida de BotBrowser y usa el paquete de perfil aprobado para esa versión. Antes de iniciar la sesión, confirma que la ruta del ejecutable, el modo de lanzamiento, la política de ruta y la configuración de la aplicación coinciden con el registro de versión. Un resultado obtenido en un portátil de desarrollo sirve durante la preparación, pero no sustituye una comprobación en el entorno de operación previsto.

Ejecuta la candidata sobre un conjunto estable de páginas propias del equipo. Mantén sin cambios la cuenta de prueba, los datos de la aplicación, la ruta y las aserciones esperadas. Compara resultados visibles para el usuario, como la navegación correcta, las acciones de formulario completadas, los documentos generados y el cierre ordenado. Si un resultado esperado cambia, conserva la pareja anterior mientras se revisa la diferencia. Evita cambiar en un solo paso el navegador, el paquete de Playwright, el paquete de perfil y el código de la aplicación, porque la evidencia resultante no indicará qué elemento de la versión requiere atención.

Realiza una comprobación de calidad de una sola sesión

Usa sessionId para delimitar esta comprobación.

Empieza con una sesión y una cuenta aprobada. Verifica como un único ciclo de vida el inicio, la primera página necesaria, la acción de la aplicación, la limpieza y la salida del navegador. Antes de cerrar el contexto, confirma que la prueba creó solo las cookies, el almacenamiento, los permisos y los archivos que espera la aplicación. Tras el cierre, inicia una sesión nueva y confirma que el estado de la cuenta anterior ha desaparecido, salvo que la persistencia sea un requisito explícito.

Ejercita también la cancelación y el fallo de la aplicación, no solo el camino correcto. Un trabajo cancelado debe detener la actividad de páginas nuevas, cerrar su contexto y liberar el navegador según la política. Un fallo de aserción de la aplicación debe conservar el registro operativo mínimo y seguir la misma ruta de limpieza. Esta comprobación ofrece al equipo un límite de sesión fiable antes de encolar más trabajo o evaluar la capacidad.

Guarda evidencia de recuperación

Conserva un registro compacto de versión para cada pareja aceptada. Incluye la versión del navegador, la del paquete de Playwright, la familia del paquete de perfil, la imagen del sistema operativo, el grupo de despliegue, la fecha de validación y el resultado final. Anota si pasaron el inicio, el flujo representativo de la aplicación, la limpieza de estado, la cancelación y el cierre. Referencia la revisión de la prueba de la aplicación y releaseCheckId para la comprobación aprobada.

Cuando se rechaza una candidata, registra el primer límite del ciclo de vida que no se completó y la unidad de versión que se restauró. Confirma la pareja restaurada con la misma comprobación de una sola sesión antes de reabrir la cola. Esta evidencia muestra qué se desplegó, qué observó la aplicación y qué versión conocida devolvió el servicio a su estado revisado.

Responsabilidad, coherencia de red y telemetría

Propiedad de procesos y contextos

Usa browserProcessId y contextId como anclajes del ciclo de vida.

Cada proceso del navegador necesita un responsable dentro del ciclo de vida de la aplicación. Ese responsable lo crea, asigna el perfil aprobado y la política de ruta, observa el inicio y lo cierra tras un éxito, una cancelación o un error. Un componente auxiliar compartido puede imponer ese ciclo de vida, pero el código de la aplicación debe esperar a que termine la limpieza antes de dar un trabajo por completado.

Los contextos de navegador también necesitan un responsable claro. Usa un contexto para un límite definido de almacenamiento y sesión y ciérralo cuando termine ese trabajo. No devuelvas un contexto a un grupo general salvo que el siguiente trabajo pueda heredar expresamente su almacenamiento, sus permisos y su asignación de perfil. En trabajo sensible a la privacidad, un límite nuevo suele ser más fácil de revisar que un contexto longevo con responsabilidades cambiantes.

Las rutas de cancelación merecen la misma atención que las rutas correctas. Cuando un elemento de la cola caduca o quien llama se desconecta, detén el trabajo de páginas nuevas, cierra el contexto activo y libera el navegador según la política del despliegue. Registra si la limpieza terminó. Una cancelación silenciosa que deja procesos del navegador en marcha acabará apareciendo como presión de memoria o como reutilización inexplicable de perfiles.

Coherencia entre proxy y perfil

Registra la decisión de red revisada como routePolicy.

Trata la asignación del perfil y la ruta de red como una sola decisión revisada. La configuración regional, la zona horaria, los ajustes regionales y la región del proxy deben describir el mismo entorno autorizado. Mantén la elección de ruta en el flujo compatible del navegador o del despliegue en lugar de repartirla entre el código de página y varios manejadores externos.

Cuando rotan las credenciales, conserva el perfil y el conjunto de páginas mientras validas la ruta nueva. Cuando cambia un paquete de perfil, conserva la ruta aprobada mientras validas el paquete nuevo. Cambiar ambos a la vez dificulta clasificar un fallo. Tras cada cambio, repite las comprobaciones habituales de la aplicación y registra solo los identificadores de versión y el resultado que necesite soporte.

No escribas credenciales del proxy en la salida de consola, trazas, capturas ni metadatos de trabajos. Entrégalas mediante el sistema de gestión de secretos del despliegue y limita el acceso a las cuentas de servicio que inician el flujo autorizado. Revisa el enmascarado en el registrador de la aplicación antes de activar el tracing de Playwright en producción.

Observabilidad sin recopilar páginas

Conserva firstPageReadyMs y exitCode como anclajes operativos, no el contenido.

La telemetría útil de la integración es sobre todo operativa. Registra la finalización del inicio del navegador, la disponibilidad de la primera página, la duración de la tarea, el cierre del contexto, el estado de salida del navegador, el retraso de la cola y los identificadores de versión. Estas observaciones indican si el sistema está sano sin conservar contenido de páginas ni un historial de navegación detallado.

Las capturas, los vídeos, las trazas y los archivos de red pueden contener datos de cuentas o estado privado de la aplicación. Actívalos solo para un caso de soporte aprobado o para un flujo que ya los requiera. Aplica controles de acceso y límites de retención antes de empezar a recopilar. Desactiva los diagnósticos temporales cuando se resuelva el problema.

Agrega los datos de capacidad por grupo de despliegue en lugar de asociar actividad detallada del navegador a una sesión concreta. La tendencia de memoria, la saturación de CPU, las salidas del navegador y los trabajos completados bastan para la mayoría de las decisiones de escalado. Mantén separada la revisión de privacidad de la de rendimiento cuando su evidencia tenga requisitos de retención distintos.

Despliegue, reversión y solución de problemas

Actualizaciones y reversión

Agrupa el despliegue bajo un deploymentGroup trazable.

Despliega primero una versión nueva del navegador o de Playwright en un grupo pequeño. Compárala con un grupo sin cambios que use la misma carga, la misma familia de perfil, la misma política de ruta y la misma clase de host. Haz una pausa cuando las aserciones de la aplicación, la estabilidad del navegador o los resultados de limpieza difieran del plan de versión. Restaura la pareja anterior antes de probar un segundo cambio.

El paquete de reversión debe incluir el binario anterior del navegador, el bloqueo de dependencias de automatización, un paquete de perfil compatible y la configuración del despliegue. Prueba ese paquete mientras siga vigente. Una instrucción de reversión no sirve si su binario ya se ha retirado o si su paquete de perfil ha caducado.

Tras un despliegue correcto, retira los paquetes antiguos según la política de retención de la organización. Conserva solo el registro de versión que necesite soporte: pareja de versiones, familia de perfil, grupo de despliegue, ventana de validación y resultado. Evita guardar trazas completas solo porque se recopilaron durante el staging.

Gestión de problemas de lanzamiento y ejecución

Clasifica el primer límite fallido con el campo failureBoundary.

Clasifica un trabajo fallido según el primer límite visible para el usuario que no se completó. Un fallo de lanzamiento, de validación del perfil, de la primera navegación, de una aserción de la aplicación o del cierre tienen responsables distintos. Conserva la salida normal del terminal y el estado de salida, y compara la unidad de versión asignada con la del último trabajo correcto.

Vuelve a la última pareja de versiones que funcionaba antes de cambiar varios ajustes. Confirma el acceso al binario, la asignación del perfil, la disponibilidad de la ruta y los recursos del host mediante las comprobaciones habituales del despliegue. Cuando la base funcione, introduce un solo cambio y repite el flujo representativo de la aplicación.

No conviertas una incidencia de producción en una inspección abierta de páginas. El registro de soporte debe contener el grupo de despliegue afectado, el resultado observable, los identificadores de versión, la acción correctiva y la validación final. Recopila evidencia adicional de páginas solo cuando el responsable de la aplicación lo autorice y la evidencia operativa normal sea insuficiente.

Lista de comprobación para producción

• Usa playwright-core, no el paquete completo playwright. El paquete completo descarga su propio Chromium, que no necesitas.
• Usa rutas absolutas para --bot-profile. Las rutas relativas pueden resolverse mal según el directorio de trabajo.
• No fijes un viewport en los contextos del navegador salvo que necesites sobrescribir el del perfil. Deja que el perfil controle las dimensiones de pantalla.
• Define DISPLAY=:10.0 al ejecutar en servidores Linux, incluso en modo headless.
• Mantén explícita la propiedad del perfil. Usa solo la asignación de perfil compatible con el flujo de BotBrowser elegido y aplícala antes de la primera página.
• Cierra los navegadores al terminar. El trabajo del navegador sin cerrar sigue consumiendo capacidad del host.
• Gestiona los errores de lanzamiento. Si el lanzamiento falla, comprueba que la ruta del binario sea correcta y que el binario tenga permiso de ejecución.

Preguntas frecuentes

• ¿Puedo usar el paquete completo de Playwright? Sí, pero descarga otro navegador que esta configuración no necesita. playwright-core mantiene la biblioteca de automatización separada del binario de BotBrowser.
• ¿Necesito scripts de página para la identidad? No. Carga un paquete de perfil correspondiente al iniciar el navegador o aplica el perfil por contexto compatible antes de que arranque el primer destino.
• ¿Puedo usar Playwright codegen o el inspector? Usa las herramientas de desarrollo de Playwright con el mismo ejecutable personalizado y la misma configuración de perfil del proyecto. Mantén alineadas las versiones de perfil de desarrollo y producción.
• ¿Cómo lo ejecuto en Ubuntu? Instala las bibliotecas de ejecución que exija la versión elegida y sigue la guía de Headless Server Setup. Elige la ruta gráfica con la guía de Linux GPU Backend.
• ¿Puedo usar un proxy por contexto? Sí. Los flujos de proxy Context y Live de BotBrowser requieren ENT Tier3. Aplica el proxy y el perfil antes de que arranque la primera página o proceso de trabajo y deja la autenticación a nivel de framework fuera de esta ruta.
• ¿Cuántos procesos de trabajo puedo ejecutar? Mide páginas representativas en el host de destino. Usa una cola limitada, conserva margen de memoria y verifica el desmontaje completo antes de aumentar la concurrencia.
• ¿Funcionan el tracing y las capturas? Playwright ofrece ambas funciones cuando la pareja de versiones elegida y el entorno de operación las admiten. Confirma los artefactos que necesita la aplicación, aplica controles de acceso y retención e incluye su coste de recursos en las mediciones de capacidad.
• ¿Puedo usar TypeScript? Sí. playwright-core incluye definiciones de TypeScript.

Conclusión práctica

Usa playwright-core para separar la automatización del ejecutable BotBrowser, asigna el perfil aprobado antes de la primera página y trata la ruta, la versión, la limpieza del contexto y la telemetría como un único flujo revisado. Así obtienes un límite de lanzamiento repetible sin afirmar control sobre una aplicación de terceros.

Qué cubre BotBrowser en este flujo

BotBrowser soporta el lanzamiento mediante el executablePath estándar de Playwright con --bot-profile y un --proxy-server opcional, de modo que el perfil seleccionado gobierna la identidad del navegador mientras Playwright sigue gestionando la navegación, los contextos y las aserciones en la misma configuración de lanzamiento repetible. En esta configuración eso significa una definición de lanzamiento revisada que un equipo puede fijar, repetir y revertir como una unidad de versión. BotBrowser no sustituye la API de automatización de Playwright, no garantiza ningún resultado en un sitio de terceros y no puede controlar la aplicación bajo prueba, el proveedor del proxy ni el estado de la cuenta. Los flujos Per-Context y de proxy Live requieren además ENT Tier3.

Instala playwright-core, apunta executablePath al binario de BotBrowser y asigna el perfil aprobado durante el lanzamiento. Valida la pareja de versiones exacta con la carga prevista antes del despliegue. Descarga BotBrowser o consulta los planes de precios para el flujo que necesites.

Para temas relacionados, consulta Primeros pasos con Puppeteer para el equivalente con Puppeteer, Recetas CLI para más combinaciones de opciones, Gestión de perfiles para organizar perfiles y Proxy por contexto para la propiedad de rutas entre contextos separados.

Para las cuatro superficies que debe cubrir una primera ejecución, empieza por el mapa de primeros pasos.

Fuentes públicas

• BotBrowser en GitHub
• Guía de BotBrowser para Playwright
• API BrowserType de Playwright