flows: Flujos de testing E2E resilientes y declarativos

En Lab34, a menudo construimos sistemas que manejan procesos complejos de múltiples pasos. Piensa en un registro de usuario típico, un proceso de checkout de comercio electrónico, o un dispositivo IoT respondiendo a un comando. Cada proceso involucra múltiples servicios - desde APIs y transacciones de base de datos hasta protocolos asíncronos o conexiones lentas a internet. Cada paso tiene sus propias peculiaridades. Cada paso depende del anterior. Cualquiera de ellos podría fallar.

Probar y gestionar estos procesos de extremo a extremo puede ser desafiante. Podrías escribir pruebas de integración complejas, pero estas a menudo se vuelven frágiles, difíciles de entender qué acciones realmente realizan, y podrían terminar dando poco o ningún espacio para el (fuzzing)[https://es.wikipedia.org/wiki/Fuzzing].

Y lo más molesto para los desarrolladores, en algunas circunstancias no pasan en entornos locales o no ofrecen ayuda para validar escenarios OK/NOK localmente.

Queríamos una mejor manera—una solución que nos permitiera definir estos procesos de manera clara, resiliente y declarativa, sin necesidad de escribir código de prueba complejo. Por eso creamos y ahora estamos liberando como código abierto lab34-flows, un poderoso orquestador para definir y ejecutar flujos de trabajo usando archivos YAML simples.

¿Qué es lab34-flows?

lab34-flows es una herramienta de orquestación que ejecuta flujos de trabajo de múltiples pasos definidos en YAML. En lugar de escribir código para unir servicios, describes la secuencia de operaciones en un formato legible para casi cualquier humano. Esto lo convierte en una herramienta ideal para pruebas de extremo a extremo (E2E), automatización de procesos y definición de lógica de negocio compleja.

Aunque los flujos se definen en YAML, el motor principal y los pasos en sí están construidos con JavaScript (nodejs), brindándote los beneficios subyacentes de robustez sin exponer esa complejidad al usuario que escribe el flujo de trabajo.

La Arquitectura: Entendiendo los Componentes Clave

Para entender cómo funciona lab34-flows, ayuda desglosarlo en tres conceptos principales: la herramienta, el contexto y las credenciales.

La Herramienta (lab34-flows): Este es el motor principal (un comando cli) del que acabas de leer. Es el orquestador que lee y ejecuta los archivos de flujo de trabajo YAML. Su trabajo principal es analizar los pasos, llamar a los métodos de aplicación apropiados, gestionar el flujo de datos y ejecutar las pruebas definidas.

El “Contexto” de la Organización: Esta es una carpeta o repositorio compartido donde los desarrolladores definen las integraciones. Actúa como un puente entre los archivos YAML simples y tus servicios reales. Aquí, los desarrolladores escriben el código que implementa lo que realmente hacen una aplicación y un método. Por ejemplo, la aplicación stripe_gateway y su método tokenize_card se definen en el contexto. Esto permite que cualquier persona en la organización—incluyendo QA, DevOps o gerentes de producto—escriba y revise escenarios de prueba en YAML simple sin necesidad de conocer los detalles de implementación subyacentes.

Las “Credenciales” (archivos .env): Estos son archivos .env estándar donde se almacenan configuraciones específicas del entorno como URLs, credenciales de base de datos y claves API. Esta práctica mantiene la información sensible fuera de los archivos YAML y del repositorio de contexto. Simplemente intercambiando el archivo .env, puedes ejecutar exactamente el mismo flujo de trabajo contra un mock local, un entorno de staging, o incluso producción, asegurando consistencia en todo tu pipeline.

Los Conceptos Principales: Un Enfoque YAML-First

Los flujos de trabajo en lab34-flows se definen con una estructura YAML directa:

• title & description: Información de alto nivel sobre lo que hace el flujo o caso de prueba.
• steps: Una lista ordenada de acciones a ejecutar. Cada paso en la lista es una operación autocontenida.
• application: El nombre del servicio o componente con el que quieres interactuar (ej., lrs, iot_locker, stripe_gateway).
  • method: La acción o función específica a llamar en esa aplicación (ej., reservation, login).
  • parameters: Los datos requeridos por el método, como cuerpos de solicitud o IDs.
  • test: Estas son las reglas que deben coincidir (si las hay) para considerar un paso exitoso.

Aquí hay un ejemplo de cómo podría verse un caso de prueba:

title: Verificar stock de producto.
description: Alguna descripción opcional.

steps:
  - application: product_catalog
    method: api_create_product
    # Los parámetros son a menudo opcionales.
    # Si no se proporcionan, se generan aleatoriamente.
    parameters:
      body:
        name: Coche R/C
        
  - application: product_catalog
    method: database_searh_ean
    # no se necesitan parámetros, ya que los flujos pueden mantener "memoria" de los
    # resultados de otros pasos
    # parameters:
    #   body:
    #     ean_code: "{{ steps.product_catalog.database_searh_ean.result.body.ean }}"
    test:
      body:
        stock_amount: 0       # validar que el stock inicial está presente
      retry:                  # Esto podría ser un proceso asíncrono, así que:
        delay: 5000           #   realizar la verificación cada 5 segundos
        times: 10             #   hasta 10 veces

Como puedes ver, el flujo se define declarativamente (tanto como necesites). No hay código, solo una descripción clara de las aplicaciones involucradas y las acciones a realizar. lab34-flows toma este archivo y ejecuta los pasos en orden, manejando el estado y el flujo de datos entre ellos.

Definiendo Pruebas dentro de los Flujos

Más allá de la simple ejecución, lab34-flows es una poderosa herramienta de pruebas. Puedes definir aserciones directamente dentro de un paso usando la clave test (comparaciones directas, pero también evaluaciones). Esto te permite validar el resultado de cada acción, convirtiendo tu flujo de trabajo en un robusto caso de prueba E2E.

Tus pruebas pueden incluir:

• Validación de Código de Estado: Asegurar que una llamada API devuelve el estado HTTP esperado.
• Headers: para asegurar que ciertos datos están presentes en los headers de respuesta HTTP.
• Aserciones del Cuerpo de Respuesta: Verificar el contenido de una respuesta, desde coincidencia de valores simples hasta expresiones complejas.
• Lógica de Reintentos: Reintentar automáticamente un paso por un número configurable de veces, lo cual es esencial para probar procesos asíncronos donde los resultados no son inmediatos.

Un Ejemplo Más Práctico: Procesamiento de Pagos en Línea

Veamos un proceso más complejo: manejar un pago en una plataforma de comercio electrónico. Con lab34-flows, toda la prueba E2E, incluyendo validaciones y manejo de trabajos asíncronos, puede definirse en YAML.

title: Procesar Pago de Nuevo Cliente
description: Este flujo prueba todo el proceso de pago, desde el registro del usuario hasta el reporte de transacciones.

steps:
  - application: user_service
    method: signup
    description: Crea un registro de usuario si no existe
    parameters:
      body:
        userEmail: "cliente@ejemplo.com"
        name: "Jane Doe"
    test:
      status: [201] # Afirmar que el usuario fue creado exitosamente

  - application: stripe_gateway
    method: tokenize_card
    description: Obtiene de forma segura un token para los detalles de la tarjeta
    parameters:
      body:
        cardNumber: "4242..."
        # ... otros detalles de la tarjeta

  - application: payment_db
    method: create_record
    description: Crea registros internos de BD para la transacción
    parameters:
      body:
        amount: 1000
        currency: "USD"
        # El flujo puede pasar el ID de usuario y el token de stripe de pasos anteriores

  - application: reporting_service
    method: trigger_report_generation
    description: Inicia un trabajo asíncrono de generación de reportes

  - application: reporting_service
    method: get_report_by_transaction
    description: Verifica que el reporte ha sido generado exitosamente
    test:
      body:
        status: "COMPLETED"
      retry:
        times: 10
        delay: 5000 # Consultar hasta 50 segundos para que el reporte asíncrono se complete

Este archivo YAML proporciona una definición limpia, expresiva y robusta de toda la transacción. Si el user_service devuelve un estado diferente a 201, el flujo se detiene inmediatamente. También maneja elegantemente el retraso en el servicio de reportes consultando hasta que el trabajo esté completo.

Desarrollo Local y Pruebas de Extremo a Extremo

Uno de los mayores desafíos en el desarrollo de sistemas complejos es lidiar con dependencias externas. ¿Cómo ejecutas una prueba E2E de tu flujo de pago sin hacer llamadas API reales a Stripe o tu banco? O cuando estás detrás de un firewall corporativo: ¿Cómo pruebas contra la API de otras aplicaciones?

lab34-flows está diseñado para resolver esto. Debido a que cada aplicación es un componente modular definido en el Contexto, puedes configurar el ejecutor de flujos para sustituir un servicio real con un mock local. Por ejemplo, en un entorno local o CI, puedes configurar lab34-flows para que la aplicación stripe_gateway apunte a un servidor mock que controlas, el cual puede simular escenarios de éxito o falla dinámicamente.

Esto te ayuda a probar un escenario donde se espera que la tarjeta de crédito “1234-1234-1234-1234” funcione, pero “1111-1111-1111-1111” se espera que falle. Desde la comodidad de tu localhost.

Esto permite que tus equipos de desarrollo y QA ejecuten flujos E2E completos en sus máquinas locales, incluso sin acceso a todos los servicios de producción, acelerando dramáticamente los ciclos de desarrollo y pruebas.

Comienza con lab34-flows

Construimos lab34-flows para resolver nuestros propios desafíos de pruebas y orquestación, y creemos que puede ayudar a otros a construir aplicaciones más confiables y mantenibles.

El proyecto es de código abierto y está disponible en GitHub. Te animamos a probarlo en tu próximo proyecto.

• Repositorio de GitHub: https://github.com/lab34-es/lab34-flows

Sumérgete en la documentación, explora los ejemplos y déjanos saber qué piensas. ¡Damos la bienvenida a contribuciones, comentarios e ideas de la comunidad!

Características Clave de un Vistazo

• Flujos de Trabajo YAML Declarativos: Define pruebas y procesos complejos en un formato simple y legible para humanos. No se requiere codificación para los autores de pruebas.
• Contexto de Aplicación Compartido: Un repositorio central y versionado para definir integraciones de servicios, permitiendo la colaboración entre desarrolladores y testers.
• Credenciales Basadas en Entorno: Gestiona de forma segura claves API, URLs y otros secretos para diferentes entornos (local, staging, prod) usando archivos .env.
• Aserciones y Reintentos Integrados: Valida resultados directamente en tu YAML con verificaciones de estado, cuerpo y reintentos, perfecto para flujos de trabajo asíncronos.
• Manejo Automático de Errores: El manejo de errores fail-fast detiene el flujo ante cualquier excepción, previniendo estados inconsistentes y proporcionando reportes claros.
• Testabilidad Mejorada: Simula fácilmente cualquier aplicación para permitir pruebas E2E robustas y rápidas en entornos locales y CI.
• Pasos Componibles y Reutilizables: Construye flujos a partir de una biblioteca de pasos predefinidos y robustos que pueden reutilizarse en toda tu aplicación.
• Motor Principal Robusto: Construido con TypeScript para un entorno de ejecución confiable y con tipado seguro bajo el capó.