@qa-team-unisys/utilidades (Postman Utilities Library)

Este paquete NPM proporciona un conjunto de funciones de utilidad diseñadas para simplificar tareas comunes dentro de los scripts de Pre-request y Tests en Postman. Actualmente, incluye funcionalidades para:

• Gestión de tokens de autenticación con Azure AD (Microsoft) y Enaire.
• Validación del tiempo de respuesta de las peticiones.
• Inicialización de esquemas de error estándar.

Instalación y Uso en Postman

Para utilizar esta librería en tus colecciones de Postman:

1. Asegúrate de tener Node.js y NPM instalados si quieres probar o desarrollar la librería localmente. Para usarla en Postman, esto no es estrictamente necesario si solo la consumes.

2. En tus scripts de Postman (Pre-request o Tests), importa la librería usando pm.require():

   const utilidades = pm.require('npm:@qa-team-unisys/utilidades@<version>');
   // Reemplaza <version> con la versión específica que deseas usar, ej: @1.0.4

Funcionalidades

1. Gestión de Tokens

Este módulo permite gestionar la autenticación con Azure AD (Microsoft) y un sistema personalizado (Enaire). Se encarga de obtener, guardar y validar tokens automáticamente.

Variables Necesarias por Escenario de Autenticación

A. Microsoft con grant_type = "password" (ROPC - Resource Owner Password Credentials)

• Variables de Entorno (Environment Variables):
  • client_id_general: Client ID de la aplicación registrada en Azure AD.
  • client_secret_general: Client Secret de la aplicación registrada en Azure AD.
  • username: Nombre de usuario del directorio activo.
  • password: Contraseña del usuario.
  • scope: Scope(s) autorizados para el recurso (API) que se va a consumir (ej. api://<client_id>/User.Read).
• Variables de Colección (Collection Variables):
  • tenant_id: ID del tenant de Azure AD (el GUID, no el nombre de dominio).

B. Microsoft con grant_type = "client_credentials"

• Variables de Entorno (Environment Variables):
  • client_id_general: Client ID de la aplicación registrada en Azure AD.
  • client_secret_general: Client Secret de la aplicación registrada en Azure AD.
  • scope: Scope del API (ej. https://graph.microsoft.com/.default o api://<client_id>/.default).
• Variables de Colección (Collection Variables):
  • tenant_id: ID del tenant de Azure AD.

C. Enaire (Autenticación Personalizada)

• Variables de Entorno (Environment Variables):
  • test_user: Nombre de usuario para el sistema Enaire.
  • test_password: Contraseña del usuario para el sistema Enaire.
• Variables de Colección (Collection Variables):
  • enaire_auth_url: URL del endpoint de autenticación de Enaire. (Nota: Esta variable fue inferida, asegúrate de que es el nombre correcto que usas).

Variables Guardadas por el Script (en el Entorno de Postman)

Las siguientes variables de entorno son gestionadas automáticamente por las funciones de token:

• currentAccessToken: El token de acceso actual para ser usado en las cabeceras de autorización de tus peticiones (ej. Bearer {{currentAccessToken}}).
• accessTokenExpiry: Timestamp (en milisegundos) que indica cuándo expira el token actual.
• currentTokenScope: El scope con el que se obtuvo el currentAccessToken.

Funciones de Gestión de Tokens

• utilidades.generateToken(pm, tokenType, grantType, callback)

  • Obtiene un nuevo token.
  • pm: El objeto pm de Postman.
  • tokenType (string): Tipo de token a generar. Valores posibles: "microsoft", "enaire".
  • grantType (string): Requerido solo si tokenType es "microsoft". Valores posibles: "password", "client_credentials".
  • callback (function, opcional): Función a ejecutar después de que el token se haya obtenido y guardado (o si hubo un error). Recibe un argumento de error si algo falla.

• utilidades.saveToken(pm, token, token_type, expiresInSeconds = null)

  • Guarda el token proporcionado y su información de expiración en las variables de entorno.
  • Automáticamente elimina el prefijo "Bearer " si está presente.
  • Calcula la fecha de expiración. Si expiresInSeconds no se proporciona, asume una duración por defecto (actualmente 55 minutos).

• utilidades.isTokenExpired(pm)

  • Verifica si el currentAccessToken almacenado está ausente, expirado o si su scope ha cambiado respecto al scope configurado en las variables de entorno/colección.
  • Retorna true si el token necesita ser regenerado, false en caso contrario.

Ejemplo de Uso (Pre-request Script para obtener token automáticamente)

const utilidades = pm.require('npm:@qa-team-unisys/utilidades@<version>');

// Configuración para este ejemplo
const TOKEN_TYPE = "microsoft"; // o "enaire"
const GRANT_TYPE = "password";  // o "client_credentials" si es Microsoft

if (utilidades.isTokenExpired(pm)) {
    console.log("Token expirado o inválido. Generando uno nuevo...");
    utilidades.generateToken(pm, TOKEN_TYPE, GRANT_TYPE, function(err) {
        if (err) {
            console.error("Error al generar el token:", err);
            // Considera detener la ejecución si el token es esencial
            // postman.setNextRequest(null);
        } else {
            console.log("Nuevo token generado y guardado exitosamente.");
        }
    });
} else {
    console.log("El token actual es válido.");
}