Playwright con perfiles de identidad coherentes

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 se ocupa de la navegación y la interacción, mientras el perfil seleccionado gobierna la identidad que presenta el navegador.

La integración comienza 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 deben comprobarse con las versiones de producción.

Impacto en la privacidad: por qué Playwright + BotBrowser

La automatización estándar puede exponer características del host que quedan fuera del límite de privacidad previsto. Un navegador respaldado por perfiles permite controlar esa exposición en un despliegue autorizado y mantener alineadas las características relacionadas durante 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 mantiene la configuración de privacidad fuera de los scripts de página y permite asociar una asignación de perfil revisada con cada proceso o flujo de contexto compatible.

Esta separación de responsabilidades concentra la integración en la configuración de lanzamiento. Las interacciones habituales con páginas, los selectores, las aserciones y la intercepción de red siguen usando las API de Playwright. Valida el comportamiento con las versiones de BotBrowser y Playwright que utilices, junto con la carga prevista.

Decisiones de integración

Por qué playwright-core y no playwright

El paquete npm estándar playwright incluye su propio binario de Chromium. Cuando instalas playwright, descarga y gestiona los binarios del navegador automáticamente. Esto es conveniente para uso general pero entra en conflicto con BotBrowser, que proporciona su propio binario de Chromium modificado.

El paquete playwright-core proporciona la misma API sin navegadores incluidos. Requiere que especifiques un executablePath al lanzar, que es exactamente lo que necesitas para apuntar Playwright al binario de BotBrowser.

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

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

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 configuración pequeña resulta más fácil de revisar, reproducir y revertir.

Añade opciones solo cuando exista un requisito documentado de la aplicación. Guarda los secretos en el sistema de gestión del despliegue y registra las versiones de BotBrowser y Playwright con el resultado del trabajo.

Contextos de navegador en Playwright

El contexto de Playwright define 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 la prueba.

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

Enfoques comunes y limitaciones

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 conectar la biblioteca con el binario BotBrowser elegido para el despliegue.

Cambios en la página

Un script de página puede cambiar valores aislados después de la navegación, pero no crea una identidad 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.

Builds privados

Mantener un build privado de Chromium exige seguimiento de releases, empaquetado y distribución por plataforma. BotBrowser proporciona binarios versionados y perfiles correspondientes para que la aplicación se centre en el flujo de Playwright.

Enfoque de BotBrowser

BotBrowser se conecta mediante la opción estándar executablePath de Playwright. El inicio requiere playwright-core, un binario BotBrowser y un paquete de perfil correspondiente. Páginas, contextos, navegación, capturas y tracing siguen usando las API habituales de Playwright.

Carga el perfil al inicio antes de la primera página. Para Per-Context Fingerprint, aplica el perfil del contexto antes de iniciar su primera página o proceso de trabajo. Los flujos Context y Live compatibles requieren ENT Tier3.

Configuración y uso

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 permisos 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=path/to/profile.enc',
    ],
    headless: true,
  });

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

  // Tu lógica de automatización aquí
  const title = await page.title();
  console.log('Título de la página:', title);

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

Lanzamiento headless y validación del perfil

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

Usa un directorio de datos independiente para cada proceso y conserva su stderr. Empieza con un grupo pequeño, confirma que las páginas se abren con normalidad y aumenta la concurrencia mediante una cola limitada. Cierra páginas, contextos y navegador en todas las rutas de salida.

Perfil + proxy + configuración regional

Revisa el perfil, la ruta de red aprobada, la configuración regional, la zona horaria y la cuenta de aplicación como una sola decisión. Sus supuestos regionales deben coincidir. Entrega las credenciales mediante el almacén de secretos y no las incluyas en trazas, capturas ni salida del terminal.

Comprobación de aislamiento de sesiones

const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: [
    '--bot-profile=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 cada cuenta de prueba autorizada.
await context1.close();
await context2.close();

Usa tu propia aplicación de staging y las aserciones habituales del producto. Confirma inicio y cierre de sesión, limpieza de almacenamiento, cancelación y cierre del contexto. No recopiles señales del navegador ni contenido que la prueba de aplicación no necesite.

Intercepción de red

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

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

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

Gestión de viewport

// Opción 1: Dejar que el perfil controle el viewport (recomendado)
const browser = await chromium.launch({
  executablePath: 'path/to/botbrowser/chrome',
  args: [
    '--bot-profile=path/to/profile.enc',
  ],
  headless: true,
});
const context = await browser.newContext(); // Sin sobreescritura 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 reduce el área visible. Evita sobrescribir el viewport desde Playwright salvo que la prueba requiera 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

Empieza con una sesión de preproducción autorizada. Confirma que el navegador inicia, la primera navegación termina, la captura se completa y el navegador se cierra sin errores de perfil o proceso. Repite con el mismo perfil y la misma ruta de red para mantener una base comparable.

En procesos por lotes, registra errores de lanzamiento, el estado de salida del navegador y el stderr de cada proceso. 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.

Mantén explícita la pareja de versiones

Registra juntos la versión de BotBrowser y el paquete de Playwright. Fija ambos en el manifiesto del despliegue y actualízalos mediante la revisión habitual de dependencias. Comprueba páginas propias o autorizadas que representen la producción: navegación, interacciones necesarias, aserciones, capturas usadas por el trabajo y cierre ordenado.

Trata el navegador, el paquete de automatización, el perfil y la imagen del sistema operativo como una unidad rastreable. Así se puede reproducir un resultado sin recopilar contenido de página ajeno a la integración.

Revisa una pareja de versiones candidata

Prepara la pareja candidata en la misma clase de host utilizada por el despliegue. Restaura el archivo de bloqueo de dependencias, instala la versión elegida de BotBrowser y utiliza 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 red y la configuración de la aplicación coinciden con el registro de la versión. Una prueba en el equipo de desarrollo ayuda durante la preparación, pero no sustituye una comprobación en el entorno operativo previsto.

Ejecuta la pareja candidata sobre un conjunto estable de páginas propiedad 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, los documentos generados y el cierre ordenado. Si cambia un resultado esperado, conserva la pareja anterior mientras se revisa la diferencia. No cambies al mismo tiempo el navegador, el paquete de Playwright, el paquete de perfil y el código de la aplicación, ya que la evidencia no permitiría identificar qué elemento requiere atención.

Ejecuta una comprobación de calidad con una sola sesión

Empieza con una sesión y una cuenta aprobada. Comprueba el inicio, la primera página necesaria, la acción de la aplicación, la limpieza y la salida del navegador como un único ciclo de vida. Antes de cerrar el contexto, confirma que la prueba solo creó las cookies, el almacenamiento, los permisos y los archivos previstos por la aplicación. Después del cierre, abre una sesión nueva y verifica que el estado de la cuenta anterior no está presente, salvo que la persistencia sea un requisito explícito.

Prueba también la cancelación y el fallo de una aserción. Una tarea cancelada debe detener la actividad nueva, cerrar su contexto y liberar el navegador según la política. Un fallo de la aplicación debe conservar el registro operativo mínimo y seguir la misma ruta de limpieza. Esta comprobación establece un límite de sesión fiable antes de poner más trabajo en cola o estudiar la capacidad.

Conserva evidencia de recuperación

Guarda un registro breve de cada pareja aceptada. Incluye la versión del navegador, la versión del paquete 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. Indica si pasaron el inicio, el flujo representativo, la limpieza del estado, la cancelación y el cierre. Añade la revisión de la prueba de aplicación para que otra persona pueda repetir la misma comprobación autorizada.

Cuando se rechace una pareja candidata, registra el primer límite del ciclo de vida que no terminó y la unidad restaurada. 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.

Propiedad del proceso y del contexto

Cada proceso debe tener un responsable en el ciclo de vida de la aplicación. Ese componente lo crea, asigna el perfil y la ruta aprobados, observa el inicio y lo cierra ante éxito, cancelación o error. Un contexto también debe pertenecer a un límite concreto de sesión y almacenamiento. No lo devuelvas a un grupo general si el siguiente trabajo no puede heredar su estado.

Las cancelaciones requieren el mismo cierre que las rutas correctas. Detén trabajo nuevo, cierra el contexto activo y libera el navegador según la política de despliegue. Registra si la limpieza terminó, ya que los procesos olvidados terminan apareciendo como presión de memoria o reutilización no prevista.

Alineación y observabilidad

Revisa juntos el perfil y la ruta de red. La configuración regional, la zona horaria y la región del proxy deben describir el mismo entorno autorizado. Cuando cambien las credenciales, conserva el perfil y las páginas de validación. Cuando cambie el perfil, conserva la ruta. Así se puede clasificar cualquier diferencia.

La telemetría útil es operativa: finalización del inicio, disponibilidad de la primera página, duración, cierre del contexto, estado de salida, demora en cola e identificadores de versión. Capturas, vídeo, traces y archivos de red pueden contener datos privados. Actívalos solo para un caso aprobado, con acceso y retención definidos, y desactívalos después.

Actualización y recuperación

Despliega una versión nueva en un grupo pequeño y compárala con un grupo sin cambios usando la misma carga, perfil, ruta y clase de host. Si las aserciones, la estabilidad o el cierre se apartan del plan, restaura la pareja anterior antes de probar otra modificación.

Clasifica los fallos por el primer límite visible que no se completó: lanzamiento, validación del perfil, primera navegación, aserción o cierre. Conserva la salida normal y el estado de salida, vuelve a la última unidad funcional y cambia un componente por prueba. El registro de soporte necesita el grupo, el resultado observable, las versiones, la acción correctiva y la validación final, no un historial completo de páginas.

Notas de 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 incorrectamente dependiendo del directorio de trabajo.
• No establezcas viewport en los contextos del navegador a menos que necesites específicamente sobreescribir el viewport del perfil. Deja que el perfil controle las dimensiones de pantalla.
• Establece DISPLAY=:10.0 al ejecutar en servidores Linux, incluso en modo headless.
• Mantén explícita la propiedad del perfil. Usa únicamente la asignación compatible con el flujo BotBrowser elegido y aplícala antes de la primera página.
• Cierra los navegadores cuando termines. El trabajo sin cerrar continúa consumiendo capacidad del host.
• Maneja los errores de lanzamiento. Verifica que la ruta del binario sea correcta y que el binario tenga permisos de ejecución si el lanzamiento falla.

Preguntas frecuentes

¿Puedo usar el paquete completo de Playwright?

Sí, pero descarga otro navegador que no hace falta en esta configuración. playwright-core mantiene separadas la biblioteca de automatización y el binario BotBrowser.

¿Necesito scripts de página para la identidad?

No. Carga un paquete de perfil correspondiente al iniciar el navegador o aplica el perfil Per-Context compatible antes del primer target.

¿Puedo usar codegen o inspector?

Usa las herramientas de desarrollo con el mismo ejecutable y la misma configuración de perfil del proyecto. Mantén alineadas las versiones de desarrollo y producción.

¿Cómo ejecuto BotBrowser en Ubuntu?

Instala las bibliotecas requeridas por la versión y sigue la guía Headless Server Setup. Elige la ruta gráfica con la guía Linux GPU Backend.

¿Puedo usar un proxy por contexto?

Sí. Los flujos de proxy Context y Live requieren ENT Tier3. Aplica el proxy y el perfil antes de iniciar la primera página o proceso de trabajo.

¿Cuántos procesos de trabajo puedo ejecutar?

Mide páginas representativas en el host objetivo. Usa una cola limitada, reserva memoria y verifica el cierre completo antes de aumentar la concurrencia.

¿Funcionan tracing y capturas?

Playwright ofrece ambas funciones cuando la pareja de versiones y el entorno elegidos las admiten. Comprueba los artefactos que necesita la aplicación, aplica controles de acceso y conservación, e incluye su coste en las mediciones de capacidad.

¿Puedo usar TypeScript?

Sí. playwright-core incluye definiciones TypeScript.

Siguientes pasos

Integrar BotBrowser con Playwright requiere cambios centrados en el lanzamiento: instala playwright-core, apunta executablePath al binario de BotBrowser y agrega --bot-profile a los argumentos de lanzamiento. Las interacciones habituales con páginas, la intercepción de red, las capturas de pantalla y las aserciones siguen usando las API de Playwright. Valida la compatibilidad con las versiones elegidas de BotBrowser y Playwright bajo la carga prevista.

Para temas relacionados, consulta Primeros pasos con Puppeteer para el equivalente con Puppeteer, Recetas CLI para más combinaciones de banderas, y Gestión de perfiles para organizar perfiles.