Introducción a BotBrowser con Playwright

Introducción

Playwright es el framework de automatización de navegadores de Microsoft, reconocido por su auto-waiting confiable, soporte multi-navegador y API potente. BotBrowser reemplaza el binario Chromium estándar por uno que produce fingerprints consistentes controlados por archivos de perfil. Playwright gestiona la lógica de automatización y BotBrowser la capa de identidad del navegador.

Esta guía cubre instalación, configuración de lanzamiento, configuración de proxies, múltiples contextos, gestión de viewport, errores comunes y patrones de despliegue en producción.

Privacidad: por qué Playwright + BotBrowser

Playwright por defecto usa Chromium stock que expone la fingerprint real del sistema host. BotBrowser permite cargar perfiles de fingerprint distintos para cada instancia, presentando identidades de navegador separadas mientras el código de automatización permanece igual.

Antecedentes técnicos

Usar playwright-core en lugar de playwright

El paquete playwright incluye binarios de navegador descargados automáticamente, lo que choca con el uso de un binario personalizado. playwright-core ofrece la misma API sin navegadores incluidos y requiere pasar executablePath en launch.

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

Cómo funciona la configuración de lanzamiento

Playwright ejecuta el proceso Chrome con los argumentos proporcionados. Los argumentos de BotBrowser (--bot-profile, --bot-config-*) se pasan por args y BotBrowser los procesa al inicializar. Playwright conecta al servidor CDP que BotBrowser expone y controla la automatización.

Contextos de navegador

Un contexto es una sesión aislada con cookies y almacenamiento propios. Los contextos comparten el mismo perfil de fingerprint cargado a nivel de navegador; para identidades diferentes, lanza instancias de navegador separadas.

Integración mínima

1. Instala playwright-core.
2. Usa la ruta al binario de BotBrowser en executablePath.
3. Ten un archivo de perfil .enc.

Ejemplos de configuración y uso

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');

  console.log('Page title:', await page.title());
  await browser.close();
})();

Perfil + proxy + locale

const browser = await chromium.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
    '--proxy-server=socks5://user:pass@proxy:1080',
    '--bot-config-timezone=America/New_York',
    '--bot-config-locale=en-US',
  ],
  headless: true,
});

Múltiples contextos (misma identidad)

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

Múltiples identidades (instancias separadas)

async function createIdentity(profilePath, proxyUrl) {
  const args = [`--bot-profile=${profilePath}`];
  if (proxyUrl) args.push(`--proxy-server=${proxyUrl}`);

  return chromium.launch({ executablePath: '/path/to/botbrowser/chrome', args, headless: true });
}

Verificación y buenas prácticas

• Verifica navigator y screen desde page.evaluate para comprobar fingerprint.
• Usa playwright-core para evitar la descarga de Chromium por parte del paquete completo.
• Usa rutas absolutas para --bot-profile.
• En servidores Linux, exporta DISPLAY=:10.0 y asegúrate de dependencias.

FAQ y resumen

Playwright funciona con BotBrowser sin cambios en el código de automatización; basta con instalar playwright-core y especificar el binario.

title: "Primeros pasos con BotBrowser y Playwright" description: "Guia rapida para ejecutar BotBrowser con Playwright para automatizacion de navegador con perfiles de huella digital consistentes." date: "2025-02-18" locale: es category: getting-started tags: ["playwright", "automation", "getting-started", "tutorial"] published: true

Descripcion general

Playwright gestiona la logica de automatizacion. BotBrowser gestiona la capa de identidad del navegador. Juntos proporcionan automatizacion de navegador con salida de huella digital consistente controlada por archivos de perfil.

Requisitos previos

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

Inicio rapido

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 logica de automatizacion aqui

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

Configuracion clave

Usa playwright-core, no playwright. El paquete completo playwright incluye su propio Chromium. Usa playwright-core para lanzar el binario de BotBrowser.

Establece defaultViewport: null para evitar que Playwright sobreescriba las dimensiones de pantalla definidas en tu perfil.

Ejemplo con perfil + proxy

const browser = await chromium.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
    '--proxy-server=socks5://user:pass@proxy:1080',
    '--bot-config-timezone=America/New_York',
    '--bot-config-locale=en-US',
    '--bot-config-languages=en-US,en',
  ],
  headless: true,
});

Problemas comunes

El navegador no se inicia: Asegurate de que el binario tiene permisos de ejecucion (chmod +x chrome).

Perfil no cargado: Usa rutas absolutas para --bot-profile.

Tamano de pantalla incorrecto: Establece defaultViewport: null en las opciones de lanzamiento.

Siguientes pasos

• Recetas CLI para mas combinaciones de flags
• Primeros pasos con Puppeteer para integracion con Puppeteer
• Gestion de perfiles para organizar perfiles