Browser

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

El paquete Browser automatiza un navegador web como lo haría una persona: abre Chrome o Edge, 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 dos conceptos que se repiten en casi todas las actividades de este paquete: la sesión de página (el parámetro page) y los selectores (cómo le dices al bot en qué elemento actuar). Los explicamos aquí abajo una vez; las páginas de cada actividad asumen que ya los conoces.

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.

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 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.

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	Reutiliza una sesión de navegador ya existente
New Page	browser-new-page	ZoanPageSession	Abre una nueva pestaña en la sesión actual
Close Page	page-close	—	Cierra una pestaña
Close Browser	browser-close	—	Cierra (o desconecta) la sesión del navegador

Navegar e interactuar

Actividad	Tipo	Salida	Qué hace
Navigate	page-navigate	—	Va a una URL
Click	page-click	—	Hace clic en un elemento
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	boolean	¿Existe y es visible el elemento?
Extract Table	page-extract-table	DataTable	Extrae una tabla HTML 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
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.cliente.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 Table  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.