Browser

Versión: 1.0.10  ·  ID: zoan-packages-browser  ·  Autor: Zoan Software

El paquete Browser automatiza un navegador web como lo haría una persona: abre Chrome, Edge, Firefox o Chromium, navega a una página, hace clic, llena formularios, lee texto y extrae tablas. Por debajo usa Playwright, un motor de automatización web moderno y robusto, pero tú no necesitas saber nada de eso: trabajas con actividades visuales.

Es uno de los paquetes más usados, porque gran parte de los sistemas empresariales (ERP, portales, banca, gobierno) se operan desde el navegador.

¿Navegador o escritorio?

La regla es directa: ¿la aplicación vive en una página web o en una ventana instalada?

Usa Browser (este paquete) si…	Usa Desktop si…
El sistema se abre en Chrome/Edge (una URL)	El programa está instalado en Windows (un .exe con su ventana)
Portales web, banca en línea, SaaS, intranets	ERP de escritorio, sistemas contables clásicos, apps de terminal
Ves https://... en la barra de direcciones	Lo abres desde el menú Inicio o un acceso directo

Si un mismo proceso toca las dos cosas (por ejemplo, lee un dato de un programa de escritorio y lo carga en un portal web), no hay problema: usa ambos paquetes en el mismo playbook. Para hojas de cálculo, PDF o correo no uses ninguno de los dos: hay paquetes dedicados (Excel, PDF, Outlook…).

Antes de empezar

Conviene entender tres conceptos que se repiten en casi todas las actividades de este paquete: la sesión de página (el parámetro page), los selectores (cómo le dices al bot en qué elemento actuar) y las esperas (cuánto aguarda cada actividad antes de fallar). Los explicamos aquí abajo una vez; las páginas de cada actividad asumen que ya los conoces.

Navegadores compatibles

Open Browser abre el navegador que elijas en su parámetro browser (o el navegador predeterminado de la configuración del proyecto):

Valor	Navegador	Cómo lo encuentra
chrome (predeterminado)	Google Chrome instalado en el equipo	C:\Program Files\Google\Chrome\Application\chrome.exe, la misma ruta en Program Files (x86) o %LOCALAPPDATA%\Google\Chrome\Application\chrome.exe
edge	Microsoft Edge instalado en el equipo	C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe o la misma ruta en Program Files
firefox	Mozilla Firefox instalado en el equipo	C:\Program Files\Mozilla Firefox\firefox.exe o la misma ruta en Program Files (x86)
chromium	El Chromium que trae el paquete	No necesita nada instalado

• Si nadie eligió navegador (ni la actividad ni el proyecto) y Chrome no está instalado, se usa el Chromium incluido automáticamente. Si eliges un navegador a propósito y no está, la actividad falla con un mensaje claro.
• Con executablePath puedes indicar la ruta exacta de otro navegador basado en Chromium (.exe, .bat o .cmd).
• Chrome y Edge se abren con un perfil temporal limpio (sin las cookies de la persona) que se borra al cerrar, con las descargas automáticas activadas y los PDF configurados para descargarse en lugar de abrirse en el visor. Para usar el perfil real de la persona, indica userDataDir.

Concepto 1: la sesión de página (page)

Cuando abres un navegador con Open Browser, obtienes una sesión de página (tipo ZoanPageSession): un objeto que representa esa pestaña abierta. Todas las actividades de página (clic, llenar, leer…) necesitan saber sobre qué pestaña actuar — eso es el parámetro page.

Hay dos formas de trabajar:

Opción A — Con body (la más simple)

Open Browser (y Attach Browser) tienen un sub-flujo body. Las actividades que pongas dentro heredan la sesión automáticamente: no necesitas configurar el parámetro page en ninguna. Al terminar el body, el navegador se cierra solo.

Open Browser   browser = chrome   url = "https://example.com"
 └─ body:
      Page Fill    selector = (#usuario)    value = "ana"
      Page Click   selector = (#entrar)
      Page Get Text  selector = (.bienvenida)  → output: saludo

Opción B — Con variable de salida (control explícito)

Open Browser guarda la sesión en una variable de salida (ej. page). Luego cada actividad recibe page = page, y al final cierras con Close Browser. Útil cuando el navegador debe seguir abierto entre varias secciones del playbook.

Open Browser   browser = chrome   → output: page
Page Navigate  page = page   url = "https://example.com"
Page Click     page = page   selector = (#entrar)
Close Browser  session = page

¿Cuál uso?

Si toda tu lógica de navegador ocurre seguida, usa body (Opción A): es más limpio y cierra el navegador por ti. Si necesitas el navegador abierto a lo largo de un flujo más complejo (con bucles, sub-playbooks, etc.), usa la variable de salida (Opción B). En la Opción A puedes activar keepOpen para conservar la sesión después del body.

De dónde sale la página de cada actividad

Las actividades de página (page-*) usan, en este orden:

1. La sesión que pongas en su parámetro page.
2. Si lo dejas vacío, la página del body de Open Browser o Attach Browser que las contiene.
3. Si no hay ninguna de las dos, fallan con 'page' debe ser una ZoanPageSession.

Una ZoanPageSession representa una pestaña y recuerda a qué navegador pertenece, así que cualquier sesión de página sirve también para Close Browser, New Page y Switch Page. Obtienes sesiones de otras pestañas con New Page, con Switch Page y con Click cuando activas expectNewTab (la pestaña que abre el clic).

Concepto 2: los selectores

Un selector le dice al bot qué elemento de la página usar (este botón, aquel campo). La forma recomendada de crearlos es apuntando con el mouse con UI Discover: Zoan Automation captura una referencia robusta que combina varias estrategias (primero id, luego name, aria-label, texto… y como último recurso CSS/XPath), de modo que sobrevive mejor a los cambios de la página. También puedes escribir un selector CSS a mano (#usuario, input[name="email"]).

Lee esto primero

Los selectores son el concepto central de este paquete. Hay dos páginas dedicadas que conviene leer:

• Selectores — qué son, sus atributos, los comodines y expresiones para que no se rompan, y las anclas.
• UI Discover — cómo capturarlos apuntando con el mouse, validarlos y ajustarlos.

En esta documentación, cuando escribimos selector = (#usuario) nos referimos a “el campo de usuario”, que tú habrás capturado con UI Discover o escrito como CSS.

Qué acepta el parámetro selector

Forma	Ejemplo	Cómo se resuelve
Selector capturado (el que crea UI Discover)	(#usuario) en esta documentación	Prueba sus atributos de lo más estable a lo más frágil: id, data-testid, name, aria-label, placeholder, texto o nombre accesible (aaname), role, CSS del nodo y, como último recurso, el CSS de respaldo y el XPath. Admite comodines *, expresiones regulares /patrón/, nodos de iframe y anclas.
Texto escrito a mano	#usuario, input[name="email"], text=Guardar, xpath=//table//tr[2], #menu >> text=Salir	Se pasa tal cual al motor de Playwright: CSS, text=, xpath= (o una ruta que empiece por //) y pasos encadenados con >>.

• Un solo elemento: las acciones (clic, llenar, leer…) exigen que el selector señale un único elemento. Si coincide con varios, la actividad falla indicando cuántos encontró; afina el selector con un índice (idx), un ancla o un atributo más específico. Element Exists y el contenedor de Extract Structured Data toman el primero sin fallar.
• Atributos que cambian solos: los id que genera el framework de la página (mat-input-0, ember123, :r1:…), las clases con hash y las clases de estado (active, is-focused…) se usan solo como pista cuando el selector tiene algo estable al lado. Así un selector grabado sigue funcionando aunque esos valores cambien entre ejecuciones.
• Con anclas, los candidatos se evalúan en el instante en que empieza la actividad: si todavía no hay ninguno, falla de inmediato con Ningún elemento coincide con el selector, así que no se pueden aplicar las anclas. Antes, espera con Wait For a un elemento de la misma pantalla que no use anclas.

Concepto 3: esperas automáticas y tiempos de espera

No necesitas pausas fijas antes de cada paso: las actividades que actúan sobre un elemento esperan solas a que esté listo.

Actividad	Antes de actuar espera a que el elemento…
Click, Check / Uncheck	exista, sea visible, esté quieto (sin animación), esté habilitado y no lo tape otro elemento; si hace falta, lo desplaza a la vista
Fill Field	exista, sea visible, esté habilitado y sea editable
Type Text, Key Press con selector	exista en la página (luego lo enfoca)
Hover	exista, sea visible, esté quieto y no lo tape otro elemento
Select Option	exista, sea visible y esté habilitado
Get Text, Get Value, Get Attribute	exista en la página
Wait For	llegue al estado pedido (visible, hidden, attached o detached)

Cuánto esperan antes de fallar:

Actividad	Tiempo de espera predeterminado
Actividades de página con parámetro timeout (Click, Fill Field, Type Text, Check / Uncheck, Hover, Select Option, Key Press con selector, Get Text, Get Value, Get Attribute, Wait For, Navigate, Extract Structured Data)	El timeout de la actividad. Vacío, 0 o negativo: el tiempo de espera para encontrar un elemento de la configuración del proyecto; si el proyecto no lo define, 30000 ms.
Element Exists	0: comprobación inmediata (no usa el del proyecto).
Open Browser	90000 ms para arrancar el navegador y cargar la url.
Switch Page	10000 ms buscando la pestaña.
Click con expectNewTab	newTabTimeout: 15000 ms esperando la pestaña nueva.
Download File, Wait for Download	30000 ms (la solicitud, o que empiece la descarga).
New Page con url, Screenshot de un elemento, Scroll a un elemento	Sin parámetro: 30000 ms.

Los retardos antes y después de cada acción que defina la configuración del proyecto se aplican también a las actividades de este paquete.

Cuando una acción falla

Click, Fill Field, Type Text, Check / Uncheck, Hover, Select Option y Wait For explican el fallo en el propio mensaje, sin capturas ni datos de la página:

Click falló: Timeout 30000ms exceeded. … | selector: <button> #guardar | coincidencias: 0 (elemento no encontrado: puede que la página no haya cargado, que el elemento esté dentro de un iframe o que el selector esté desactualizado)

coincidencias	Qué significa
0	El elemento no está: la página no terminó de cargar, está dentro de un iframe que el selector no incluye o el selector quedó desactualizado.
1	El elemento está, pero la acción no se completó: está oculto, deshabilitado, tapado por otro elemento o fuera de la vista.
2 o más	El selector es ambiguo: agrega un índice o un ancla para desambiguar.

Antes de empezar, el motor también comprueba los parámetros: si falta uno requerido, falla con [page-click] Required parameter 'selector' not found.; si un parámetro de opciones tiene un valor fijo fuera de su lista, con [page-wait-for] Invalid value '…' for 'state'. Allowed: visible, hidden, attached, detached.

Todas las actividades del paquete fallan con un error normal del playbook, así que puedes envolverlas en Try / Catch o reintentarlas con Retry.

Actividades

Abrir y cerrar

Actividad	Tipo	Salida	Qué hace
Open Browser	browser-open	ZoanPageSession	Abre el navegador y devuelve una sesión de página
Attach Browser	browser-attach	ZoanPageSession	Retoma una sesión de página que ya tienes en una variable
New Page	browser-new-page	ZoanPageSession	Abre una pestaña nueva en el mismo navegador
Switch Page	browser-switch-page	ZoanPageSession	Toma una pestaña ya abierta por URL, título o posición
Close Page	page-close	—	Cierra una pestaña
Close Browser	browser-close	—	Cierra el navegador con todas sus pestañas

Navegar e interactuar

Actividad	Tipo	Salida	Qué hace
Navigate	page-navigate	—	Va a una URL
Click	page-click	ZoanPageSession	Hace clic en un elemento; con expectNewTab, devuelve la pestaña que abre
Fill Field	page-fill	—	Escribe un valor en un campo (rápido)
Type Text	page-type	—	Teclea texto carácter por carácter
Select Option	page-select	—	Elige una opción en un <select>
Check / Uncheck	page-check	—	Marca/desmarca un checkbox o radio
Hover	page-hover	—	Pasa el mouse por encima de un elemento
Key Press	page-key-press	—	Envía una tecla o combinación
Scroll	page-scroll	—	Desplaza la página o un elemento

Leer datos

Actividad	Tipo	Salida	Qué hace
Get Text	page-get-text	string	Texto visible de un elemento
Get Value	page-get-value	string	Valor de un input/select/textarea
Get Attribute	page-get-attribute	string	Valor de un atributo HTML
Element Exists	page-element-exists	bool	¿Existe y es visible el elemento?
Extract Structured Data	page-extract-table	DataTable	Extrae una tabla HTML, o cualquier cuadrícula visual, a una DataTable

Esperar, capturar y avanzado

Actividad	Tipo	Salida	Qué hace
Wait For	page-wait-for	—	Espera a que un elemento alcance un estado
Wait for Download	page-wait-for-download	string	Espera a que termine una descarga
Download File	page-download-file	string	Descarga un archivo desde una URL con la sesión del navegador
Screenshot	page-screenshot	string	Captura de pantalla a un archivo
Evaluate JS	page-evaluate	object	Ejecuta JavaScript en la página

Un flujo típico

Open Browser   browser = chrome   url = "https://portal.example.com"
 └─ body:
      Page Wait For  selector = (#usuario)   state = visible
      Page Fill      selector = (#usuario)   value = credential("portal")["user"]
      Page Fill      selector = (#clave)     value = credential("portal")["password"]
      Page Click     selector = (#entrar)
      Page Wait For  selector = (.dashboard) state = visible
      Extract Structured Data   selector = (#tablaMovimientos)   → output: movimientos

Siguientes pasos

• Open Browser — el punto de partida de toda automatización web.
• Primeros pasos — un tutorial guiado que automatiza una página real.
• Expresiones — construir URLs y valores dinámicos.