Depuración

Depurar es ejecutar tu playbook para ver qué hace realmente, encontrar dónde falla y corregirlo. El Designer te deja ejecutar el playbook en tu propia máquina todas las veces que quieras antes de publicarlo a Nexus — así detectas los problemas mientras los puedes ver con tus propios ojos.

Prueba local antes de publicar

Un bot en producción se ejecuta solo y, a menudo, sin pantalla. Cualquier problema es más difícil de diagnosticar ahí. La regla de oro: que el playbook funcione de forma estable en el Designer antes de publicarlo.

Ejecutar localmente

La ejecución local usa el Agent instalado en tu misma máquina, así que primero asegúrate de que esté ejecutándose.

1. Verifica que el Zoan Agent esté activo (su ícono aparece en la bandeja del sistema, junto al reloj).
2. En la toolbar del Designer, haz clic en Ejecutar (botón con ícono de play).
3. El playbook empieza a ejecutarse y el panel de logs (parte inferior) muestra los mensajes en tiempo real.

Mientras se ejecuta, el Designer resalta la actividad en curso, de modo que ves exactamente por dónde va el flujo.

Leer el panel de logs

Durante y después de la ejecución, el panel de logs te muestra:

• Los mensajes que tú emites con la actividad Log.
• La actividad que se está ejecutando en cada momento.
• Los errores y su detalle (stack trace) cuando algo falla.
• El tiempo de ejecución.

Localizar la actividad que falla

Cada actividad del canvas tiene un número global (#N) que no se reinicia dentro de los lanes: es único en todo el playbook, en orden de ejecución. Cuando una actividad falla, el panel de logs muestra un chip #N · etiqueta en el que puedes hacer clic para seleccionar y centrar la actividad culpable en el canvas — mucho más rápido que buscarla por su id.

[INFO] Iniciando ejecución
[INFO] browser-open: chrome → erp.cliente.com
[INFO] page-fill: #usuario
[WARN] page-wait-for: reintentando (1/3)
[ERROR] page-click: selector "#guardar" no encontrado tras 10000ms
[FAIL]  Ejecución detenida — 8.7s

Niveles de log

La actividad Log te deja escribir mensajes con un nivel de severidad. Úsalos para dejar “huellas” que expliquen qué está pasando:

Nivel	Cuándo usarlo
debug	Detalle fino para diagnóstico profundo
info	Hitos normales del proceso (“10 facturas leídas”)
warning	Algo inesperado pero no fatal (“cliente sin correo, se omite”)
error	Un fallo que impide continuar

Loggea con intención

Agregar actividades Log en puntos clave (después de leer datos, antes de una acción crítica, dentro de un catch) convierte un fallo opaco en un problema fácil de ubicar. En producción, estos mismos mensajes aparecen en los logs de ejecución de Nexus.

Inspeccionar variables

Al terminar una ejecución —haya tenido éxito o no— el panel de variables muestra el valor final de cada variable. Esto es clave para depurar: si el playbook falló al escribir un Excel, revisa qué tenía realmente la variable con la tabla; quizá llegó vacía o con un dato inesperado.

Manejar errores sin detener el bot

No todos los errores deben tumbar la ejecución. Para los que esperas (un correo sin adjunto, una página que a veces tarda), usa estas dos actividades del paquete Core:

Try / Catch

Ejecuta las actividades del lane try; si alguna falla, el flujo salta al lane catch, donde puedes registrar el error y continuar con un plan B en lugar de detenerte. Ver Try / Catch.

Try/Catch   errorVariable = error
├─ try:
│    Excel Read Range   → tabla
├─ catch:
│    Log   level = error   message = = "No se pudo leer el Excel: " + error

errorVariable guarda el mensaje del error como texto, así que se lee directamente con = error (no error.Message).

Retry

Reintenta un grupo de actividades varias veces antes de rendirse. Ideal para acciones que fallan de forma intermitente (la red, una página lenta). Ver Retry.

Retry   attempts = 3   delay = 2000
└─ body:
     Page Click   selector = "#guardar"

Atendido vs desatendido

Reproducir un error que solo ocurre en producción muchas veces se debe a diferencias de entorno: el bot se ejecuta headless (sin ventana), con otra resolución de pantalla, otra sesión de Windows o sin la aplicación abierta. Si algo funciona en el Designer pero falla publicado, prueba en local con las mismas condiciones (por ejemplo, headless = true en Open Browser).

Errores frecuentes

Error	Causa probable	Solución
Agent no disponible	El Agent no está ejecutándose	Ábrelo desde el menú de inicio y espera a que conecte
Paquete no instalado	La actividad usa un paquete ausente en el Agent	Instálalo desde Nexus → Paquetes
Variable no declarada	Se usó una variable sin declararla	Decláralo en el panel o corrige el nombre
Tipo incompatible	El resultado de una actividad no es del tipo que espera la siguiente	Revisa los tipos en el panel de variables; convierte con toNumber, toString, etc.
Selector no encontrado	La página/app cambió, o no había terminado de cargar	Agrega un Page Wait For antes, o ajusta el selector
Timeout	La acción tardó más que el tiempo límite	Sube el parámetro timeout o espera una condición previa

Siguientes pasos

• Expresiones — corregir fórmulas que devuelven valores inesperados.
• Logs de ejecución — depurar lo que ya se ejecuta en producción.
• Estados y ciclo de vida — entender por qué una ejecución queda en failed.