Primeros pasos con automatización de navegador: mapa inicial

La primera ejecución de automatización decide si el resto del proyecto es reproducible. Este hub conecta el grupo de primeros pasos y añade un registro acotado que nombra la instalación, el lanzamiento, el límite de contexto y la evidencia, empezando por Playwright con identidad respaldada por perfil.

BotBrowser soporta lanzar un perfil autorizado desde un driver como Playwright o Puppeteer y mantiene los valores visibles del navegador alineados con ese perfil; no puede instalar tu driver, elegir tu perfil ni garantizar que un sitio de terceros acepte la sesión, y no sustituye la documentación del driver.

Resumen

• Instala el navegador y el driver, y demuestra que ambos arrancan antes de escribir automatización.
• Lanza con un perfil explícito y registra qué archivo de perfil usó la ejecución.
• Da a cada tarea su propio contexto y ciérralo en la misma ejecución.
• Guarda un registro corto de la primera ejecución para comparar la segunda.

Contenido

• Las cuatro superficies de primeros pasos
• Recorrer el grupo de primeros pasos
• Ejecutar la primera sesión
• Planificar el primer proyecto
• Hacer repetible la ejecución
• Corregir el primer fallo
• Conclusión práctica

Las cuatro superficies de primeros pasos

Una primera ejecución tiene cuatro superficies. La instalación cubre el paquete del navegador, el driver y la alineación de versión entre ambos. El lanzamiento cubre cómo arranca el proceso: qué ejecutable, qué indicador de perfil y qué modo sin interfaz o con interfaz. El aislamiento de contexto cubre qué posee cada tarea: su propio contexto de navegador, sus páginas y la limpieza que los cierra. La evidencia cubre lo que deja la ejecución: la salida de consola, las cadenas de versión y el resultado de la comprobación propia.

Estas superficies fallan en un orden que facilita el diagnóstico si lo respetas. Un problema de instalación aparece antes de que nada arranque. Un problema de lanzamiento aparece como un navegador que arranca sin el perfil declarado. Un problema de contexto aparece como estado que se filtra entre dos tareas que debían ser independientes. Un problema de evidencia aparece después, cuando nadie puede decir qué compilación produjo un resultado.

El papel de BotBrowser en una primera ejecución es estrecho: carga el perfil que nombraste y mantiene los valores visibles del navegador coherentes con él. Todo lo demás, la versión del driver, la estructura del script y la limpieza, pertenece a tu código de automatización.

Recorrer el grupo de primeros pasos

• Playwright con identidad de perfil es la ruta de lanzamiento de Playwright y sus trampas.
• Lanzamiento y trampas de perfil en Puppeteer cubre el equivalente en Puppeteer.
• Integración de perfiles con Selenium cubre la propiedad de sesión en Selenium.
• Perfiles de navegador: formatos y rotación explica el archivo de perfil que vas a pasar.
• La guía del lanzador cubre perfiles, proxies y configuración.
• Recetas de CLI reúne ejemplos de comandos concretos.
• Automatización ligera con el protocolo DevTools cubre la ruta sin framework.
• Fixtures y aislamiento en automatización cubre lo que debe poseer una primera ejecución.
• Informes de errores reproducibles cubre qué registrar cuando falla la primera ejecución.
• Verificar una huella de navegador cubre una comprobación acotada de lo que ve la página.

El hub posee el orden y la forma del registro. Cada artículo enlazado posee el detalle de su superficie y el fallo que puede producir.

Ejecutar la primera sesión

Escribe las entradas antes de la primera petición: el driver y su versión, el paquete del navegador, el archivo de perfil y la comprobación que piensas ejecutar. Después ejecuta una sesión que ejercite cada superficie una vez y registra el resultado.

{
  "runId": "first-run-20261019-01",
  "declared": {
    "driver": "[email protected]",
    "browserPackage": "standard-linux-x64",
    "profile": "fresh-temporary.enc",
    "mode": "headless"
  },
  "observed": {
    "install": "executable-started",
    "launch": "profile-loaded",
    "context": "closed-after-task",
    "evidence": "console-and-check-recorded"
  },
  "firstFailure": null,
  "testedOn": "2026-10-19"
}

El registro son datos, no un informe. Debe ser lo bastante corto para pegarlo en un hilo de soporte y lo bastante explícito para repetir las mismas cuatro filas con el driver y el perfil registrados. La instalación y el lanzamiento son comandos directos que se pueden pegar en una terminal.

Demuestra la instalación antes de escribir automatización. Arranca el navegador con una página trivial y confirma que inicia, después ejecuta el comando de versión del propio driver. Un driver que no puede arrancar el navegador produce un error que parece un problema de perfil, y un navegador que arranca sin driver produce un error que parece un problema de script. Separar las dos comprobaciones lleva un minuto y ahorra una tarde.

Lanza con una ruta de perfil explícita. Una primera ejecución que depende de un perfil por defecto prueba algo que no es tu automatización. Pasa el archivo de perfil explícitamente y después lee un valor visible que el perfil declare, como la plataforma o la zona horaria, y regístralo. Si el valor no coincide, la superficie que falla es el lanzamiento, no el script.

Da a cada tarea su propio contexto. Una ejecución que reutiliza un contexto entre tareas no relacionadas acabará filtrando cookies, almacenamiento o permisos entre ellas. Crea un contexto por tarea, ejecuta la tarea y cierra el contexto en la misma función. Registra si el cierre ocurrió, porque un contexto filtrado es invisible hasta que la máquina se queda sin memoria.

Mantén la primera comprobación propia y pequeña. Usa una página que controle tu equipo, con versión fijada, y afirma una sola cosa: el perfil cargó, la página renderizó o la interacción se completó. Una primera ejecución contra un sitio de terceros mide también la política de ese sitio, y su fallo no dice cuál de tus cuatro superficies está mal.

Registra las versiones en ambos lados. La versión del driver y la del paquete del navegador van en el mismo registro que el resultado, porque una configuración compartida falla en una capa distinta a la de una actualización del driver. Cuando la siguiente ejecución se comporte distinto, los dos registros muestran qué lado se movió.

Elige el modo sin interfaz de forma deliberada. Una primera ejecución sin interfaz es más fácil de automatizar y de llevar a CI, y una con interfaz es más fácil de depurar cuando la página renderiza distinto. Registra el modo usado, porque cambiar de modo entre ejecuciones es otro experimento, y una diferencia de renderizado sin interfaz no es evidencia del comportamiento con interfaz.

Limpia incluso cuando la ejecución falla. Envuelve la sesión para que el contexto y el navegador se cierren tanto en éxito como en excepción. Una primera ejecución que dejó un proceso de navegador vivo hace que la segunda mida el estado residual, que es cómo una configuración simple se convierte en un fallo intermitente.

Planificar el primer proyecto

Lo que hay que decidir justo después de la primera ejecución es la forma del proyecto. Mantén tres cosas separadas desde el principio: el código de lanzamiento que conoce el navegador y el perfil, el código de tarea que conoce la página bajo prueba, y el código de fixture que comparten ambos. Cuando se mezclan, cada tarea nueva copia los detalles de lanzamiento y un cambio de perfil hay que aplicarlo en una docena de lugares.

Pon la ruta del perfil en un valor de configuración y no en un literal dentro de un script. La primera ejecución suele usar un perfil y la segunda necesita otro, ya sea para probar rotación o para aislar un equipo; el artículo sobre formatos de perfil explica qué archivo pasar. Un valor de configuración convierte eso en un cambio de una línea y hace que el perfil sea una entrada registrada en lugar de una constante invisible.

Haz que el lanzamiento sea una función como createSession({ profile, headless }) que devuelve un objeto de sesión. El objeto de sesión posee el navegador, el contexto y un método de cierre. La tarea recibe la sesión y nunca ve los indicadores de lanzamiento. Esto refleja cómo describen la propiedad de contexto Playwright y Puppeteer, y significa que una tarea escrita para un driver se puede adaptar a otro sin reescribir la lógica de página.

Mantén la página de fixture versionada junto al código. Un fixture que cambia sin subir versión hace incomparables dos ejecuciones, y el primer síntoma es una diferencia que parece una regresión del navegador. Una cadena de versión en el fixture y en el registro basta para distinguir ambas cosas.

Elegir el driver por el trabajo, no por la demo

Playwright, Puppeteer, Selenium y un cliente directo del protocolo DevTools conducen el mismo navegador, y cada uno plantea un compromiso distinto. Playwright ofrece una API de contextos madura y un visor de trazas, Puppeteer tiene una superficie más pequeña y una larga historia en automatización de Chrome, Selenium corresponde a un estándar más amplio entre navegadores, y un cliente de protocolo elimina el framework a cambio de hacer tú la fontanería.

Para una primera ejecución, elige el driver que tu equipo ya usa en otras páginas. La ruta de lanzamiento es la parte que estás probando, y un driver desconocido añade un segundo desconocido. El grupo enlazado arriba cubre el lanzamiento con perfil para cada driver principal y la ruta de protocolo sin framework.

Sea cual sea el driver, deja el indicador de perfil en las opciones de lanzamiento y no en un script a nivel de página. Un apaño a nivel de página que fija un valor tras la carga prueba algo que el navegador no proporcionó, y discrepará del perfil declarado en la siguiente navegación.

Decidir qué debe probar la primera ejecución

Una primera ejecución es una comprobación con una sola pregunta, y la pregunta debe estar escrita antes que el script. «¿Arranca el navegador con este perfil?» es una buena primera pregunta. «¿Renderiza la página en la plataforma declarada?» es una buena segunda. «¿Acepta el sitio la sesión?» es una pregunta sobre el sitio y llega más tarde, en una prueba propia.

Escribe el resultado esperado como un valor, no como una sensación. Por ejemplo, espera que navigator.platform informe el valor declarado en el perfil, o espera que el fixture propio devuelva un objeto de estado con forma fija. Un valor se puede comparar entre ejecuciones; una sensación no.

Registra el resultado real junto al esperado. Una primera ejecución que solo pasa es menos útil que una que anota lo observado, porque la siguiente comparación necesita ambos lados. Cuando el valor observado cambia tras una actualización del driver, el registro muestra exactamente qué campo se movió.

Hacer repetible la ejecución

El valor de una primera ejecución es que convierte la segunda en una comparación en lugar de una investigación. Eso solo ocurre si la segunda repite las mismas entradas declaradas y produce el mismo registro. Mantén el identificador de ejecución, la versión del driver, el paquete y el perfil en el registro, y repite la misma comprobación antes de cambiar cualquiera de ellos.

Pon toda la secuencia detrás de un comando, por ejemplo npm run first-run, que sale con código distinto de cero al fallar. Una configuración documentada como cinco pasos manuales se convierte en una configuración que nadie ejecuta. Un comando que no instala nada, lanza el navegador con el perfil configurado, ejecuta la comprobación propia y escribe el registro es una configuración que puede correr en integración continua y en el checkout de un compañero nuevo el mismo día.

Trata la primera ejecución correcta como una prueba de regresión y no como un hito. La comprobación que probó que la configuración funciona debe seguir corriendo para que una actualización posterior del driver o del paquete la detecte la misma prueba. Una primera ejecución que solo existe en una captura de chat no protege nada.

Mantener el perfil y la limpieza juntos

El archivo de perfil y la ruta de limpieza son los dos extremos de la misma decisión. Un perfil que nunca se elimina se acumula en la máquina, y un contexto que nunca se cierra mantiene vivo su estado. Ambos problemas aparecen como presión de memoria en vez de como un error obvio, y ambos son fáciles de evitar cuando la primera ejecución registra de dónde vino el perfil y qué contextos cerró.

Prefiere un perfil temporal nuevo (profileClass: "fresh-temporary") para la primera ejecución, y registra la clase en lugar de la ruta si el perfil contiene algo sensible. Un perfil nuevo mantiene la primera ejecución independiente de la actividad previa y hace significativa la comparación con la segunda. Un perfil de larga vida es un paso posterior legítimo y debe ser deliberado.

Cuando la ejecución usa un perfil de un almacén compartido, registra el almacén y la regla de selección en lugar del nombre de archivo completo, así un revisor ve cómo se eligió el perfil sin recibir el perfil.

Automatizar las comprobaciones que ya hiciste a mano

Una vez registrada la primera ejecución, la mayoría de sus filas se pueden automatizar. La comprobación de instalación se vuelve una aserción de versión. La de lanzamiento, una lectura de un valor declarado. La de contexto, una aserción de cierre. La de evidencia, el propio archivo de registro. Automatizarlas no cambia lo que prueban; las hace lo bastante baratas para correr en cada cambio.

Mantén la automatización honesta sobre sus límites. Que el navegador arrancara no prueba que una página se comporte correctamente, y que la página renderizara no prueba que un servicio aceptara la sesión. Cada fila automatizada debe afirmar una cosa y reportar un resultado, así un fallo apunta a una superficie y no a toda la configuración.

Ejecuta la primera ejecución automatizada (npm run first-run) antes de fusionar cualquier cambio al código de lanzamiento. Ese código es pequeño y central, y un cambio ahí afecta a todas las tareas, así que la prueba de regresión más barata es la que ya existe.

Documentar el único comando que el equipo va a escribir

Una documentación que enumera cada indicador que un usuario nuevo podría necesitar es menos útil que un comando que funciona. Pon el comando arriba, la explicación debajo, y asegúrate de que el comando del documento es el mismo que ejecuta la automatización. Un comando documentado que se desvió del código es peor que ningún comando, porque enseña una configuración que nadie usa.

Incluye la salida esperada en la documentación, no solo el comando. Quien llega por primera vez necesita saber cómo se ve el éxito, y un archivo de registro con las cuatro filas rellenas es un objetivo más claro que una frase diciendo que funcionó.

Revisa el comando cuando cambien el driver o el paquete. La primera ejecución es la parte del proyecto más propensa a quedar obsoleta, porque es la parte que todos configuran una vez y después dejan de mirar.

Corregir el primer fallo

Si nada arranca, revisa primero la superficie de instalación: el ejecutable, sus permisos y la capacidad del driver para alcanzarlo. Si el navegador arranca pero el valor del perfil no coincide, revisa el lanzamiento: el nombre del indicador, la ruta y el formato del perfil. Si dos tareas comparten estado, revisa la superficie de contexto: dónde se creó y dónde se cerró. Si el resultado no se puede reproducir, revisa la evidencia: qué versiones y entradas se registraron.

Corrige una superficie por ejecución y conserva el registro. Una primera ejecución que termina con una superficie nombrada está lista para convertirse en plantilla del resto del proyecto.

Conclusión práctica

Una primera ejecución repetible son cuatro registros: instalación, lanzamiento, contexto y evidencia. Usa este hub para ordenarlos y el grupo para el detalle, y limita cada conclusión al driver, paquete y perfil que la produjeron.

Fuentes

• Playwright: contextos de navegador
• Puppeteer: gestión del navegador
• MDN: WebDriver
• Documentación de BotBrowser: primeros pasos
• Documentación de BotBrowser: gestión de perfiles