Template Cypress E2E Tests

Propósito y Alcance

Este proyecto proporciona una plantilla base para la creación de pruebas End-to-End (E2E) utilizando Cypress y Cucumber (Gherkin) para aplicaciones web. Su objetivo principal es facilitar la configuración inicial de un entorno de pruebas automatizadas, incluyendo la integración con Azure Active Directory (AAD) para la autenticación, y la generación de reportes de prueba detallados.

Problema que resuelve:

Estandariza la creación de proyectos de pruebas E2E con Cypress.
Proporciona una solución preconfigurada para la autenticación AAD en pruebas Cypress.
Facilita la ejecución de pruebas en diferentes entornos (dev, intg, cert, prod).
Integra la generación de reportes con Mochawesome.

Alcance:

Configuración y ejecución de pruebas E2E para interfaces de usuario (UI).
Configuración y ejecución de pruebas para APIs.
Integración con Cucumber para Behavior-Driven Development (BDD).
Manejo de configuraciones específicas por entorno.
Autenticación con Azure AD.
Generación de reportes de prueba.
Integración con pipeline de CI/CD (Jenkins).

Arquitectura

El proyecto se centra en la automatización de pruebas con Cypress. La arquitectura es la siguiente:

Cypress Test Runner: El motor principal que ejecuta los scripts de prueba.
Application Under Test (AUT): La aplicación web o API externa que se está probando (ej. strategic-planning.dev.appslatam.com).
Cucumber (Gherkin): Permite escribir casos de prueba en un lenguaje natural (.feature files) que se mapean a código JavaScript/TypeScript (step definitions).
Azure Active Directory (AAD): Para pruebas que requieren autenticación, el proyecto incluye un flujo personalizado para manejar el login con AAD.
Mochawesome: Generador de reportes HTML para visualizar los resultados de las pruebas.
Node.js Environment: Cypress y sus dependencias se ejecutan sobre Node.js.
Jenkins CI/CD: El Jenkinsfile define el pipeline para la ejecución automatizada de las pruebas en entornos de integración continua.

No se requiere un diagrama de arquitectura complejo, ya que es un proyecto de pruebas. La interacción principal es Cypress comunicándose con el AUT a través de HTTP/HTTPS y manipulando el DOM del navegador.

Tecnologías y Dependencias

Las principales tecnologías y dependencias del proyecto se encuentran definidas en el archivo package.json:

Framework de Pruebas: Cypress (^13.14.1)
BDD (Behavior-Driven Development):
- @badeball/cypress-cucumber-preprocessor: (^20.1.2) para integrar Cucumber con Cypress.
Preprocesador de Archivos:
- @bahmutov/cypress-esbuild-preprocessor: (^2.2.2) para usar ESBuild con Cypress.
- esbuild: (^0.23.1) bundler rápido para JavaScript/TypeScript.
Reportería:
- mochawesome: (^7.1.3) para generar reportes HTML.
- mochawesome-merge: (^4.3.0) para unir múltiples reportes JSON de Mochawesome.
- mochawesome-report-generator: (^6.2.0) generador de reportes base para Mochawesome.
Gestión de Variables de Entorno:
- dotenv: (^16.4.5) para cargar variables de entorno desde un archivo .env.
Utilitarios:
- fs-extra: (^11.2.0) para operaciones extendidas del sistema de archivos.
Entorno de Ejecución: Node.js (versión recomendada >=16)

Configuración Local

Prerrequisitos

Node.js (v16 o superior recomendado)
npm (generalmente viene con Node.js) o Yarn
Un editor de código (ej. VSCode)
Git

Pasos de Configuración

Clonar el repositorio: Sigue los siguientes pasos
Instalar dependencias:
```
npm install
```
o si usas Yarn:
```
yarn install
```
Configurar variables de entorno: Crea un archivo .env en la raíz del proyecto. Este archivo es ignorado por Git (.gitignore). Basado en cypress.config.js y cypress/support/e2e.js, las siguientes variables son necesarias para la autenticación AAD:
```
# Credenciales para el usuario con rol editor (ejemplo)
AUTH0_USERNAME="tu_usuario_editor_aad@example.com"
AUTH0_PASSWORD="tu_password_editor_aad"

# Credenciales para el usuario con rol lector (ejemplo)
AUTH1_USERNAME="tu_usuario_lector_aad@example.com"
AUTH1_PASSWORD="tu_password_lector_aad"
```
Reemplaza los valores con las credenciales correspondientes para tus entornos de prueba.
Verificar la instalación de Cypress (opcional):
```
npm run cypress:verify
# o
npx cypress verify
```

Ejecutar Pruebas Localmente

El archivo package.json contiene varios scripts para ejecutar las pruebas:

Abrir Cypress Test Runner (UI):
```
npm run cy:open
```
Esto abrirá la interfaz de Cypress donde puedes seleccionar y ejecutar pruebas individualmente.
Ejecutar todas las pruebas en consola (headless, por defecto en Chrome):
```
npm run cy:run
```
Ejecutar pruebas UI con reporte Mochawesome:
```
npm run cy:ui
```
Ejecutar pruebas API con reporte Mochawesome:
```
npm run cy:api
```
Ejecutar pruebas para un entorno específico: El proyecto está configurado para cargar diferentes baseUrl según el entorno.
```
npm run cy:run:dev   # Para entorno de desarrollo
npm run cy:run:intg  # Para entorno de integración
npm run cy:run:cert  # Para entorno de certificación
npm run cy:run:prod  # Para entorno de producción
```
Estos scripts utilizan los archivos de configuración en cypress/config/cypress.[entorno].config.json.
Generar Reporte Consolidado: Después de ejecutar pruebas con Mochawesome (ej. npm run cy:run:dev), puedes generar un reporte HTML consolidado:
```
npm run cy:report
```
Esto creará un archivo merged-report.json y abrirá el reporte HTML en mochawesome-report/merged-report.html.

Despliegue

El despliegue de este proyecto de pruebas se refiere a su ejecución en un entorno de Integración Continua (CI), típicamente Jenkins.

Jenkins

El proyecto incluye un Jenkinsfile:

#!groovy
pipelineLatamEMX("cypress-e2e")

Esto indica que utiliza una pipeline compartida llamada pipelineLatamEMX con el perfil cypress-e2e. Esta pipeline se encargará de:

Clonar el repositorio.
Instalar dependencias.
Ejecutar las pruebas Cypress (probablemente usando uno de los scripts de package.json).
Publicar los artefactos de prueba (reportes Mochawesome, videos, screenshots).

Configuración de Entornos en CI

La configuración para diferentes entornos (dev, intg, cert, prod) en CI se gestiona a través de archivos YAML en el directorio deploy/env/:

deploy/env/dev.yaml
deploy/env/cert.yaml
deploy/env/intg.yaml
deploy/env/feature.yaml

Estos archivos pueden contener variables específicas del entorno, como las credenciales de AAD:

# Ejemplo de deploy/env/dev.yaml
### ---> # OAuth Credentials - AAD
auth0_username: "test_emx_stplanng_ehvypln_editor@latam.com"
auth1_username: "test_emx_stplanng_ehvypln_reader@latam.com"

Configuración de Runtime (Cloud Run - si aplica a la ejecución de los tests, no al AUT)

Los archivos ERB (.yaml.erb) en deploy/run/ sugieren una configuración para Google Cloud Run, aunque esto podría ser para una infraestructura que soporta la ejecución de las pruebas o servicios relacionados, no directamente el proyecto Cypress en sí como una aplicación desplegada.

deploy/run/runtime-config.yaml.erb:

# min-instances: 0
# max-instances: 5
# execution-environment: gen2
# ingress: all
# concurrency: 5
# timeout: 600
# update-secrets: AUTH0_PASSWORD=auth0_password,AUTH1_PASSWORD=auth1_password
# set-secrets: "DATABASE_PASSWORD=projects/831702928814/secrets/tmpl_arq_dev_lataminit-dev-cloudsql_passwd:latest"

La directiva update-secrets es crucial para la gestión de contraseñas AAD (AUTH0_PASSWORD, AUTH1_PASSWORD) en el entorno de CI/CD.

deploy/run/environment.yaml.erb:
```
### ---> OAuth Credentials - AAD
AUTH0_USERNAME: "<%= auth0_username %>"
AUTH1_USERNAME: "<%= auth1_username %>"
```
Este archivo plantilla se utiliza para inyectar los nombres de usuario AAD como variables de entorno en el runtime.

Endpoints de la API

Este proyecto se enfoca principalmente en pruebas E2E de UI, pero también incluye un ejemplo de prueba de API.

Pokémon GO API (Ejemplo)

Se utiliza como ejemplo para demostrar la capacidad de pruebas de API con Cypress.

Archivo Feature: cypress/e2e/features/api/api-PokemonGo.feature

Feature: Pokemon GO API
    """
    Pokemon GO API
    """

  Scenario: Testing API - METHOD: GET -  Endpoint: Abilities by ID
    When I send "ability/1"
    Then I validate answers you want to receive

Archivo Step Definition: cypress/e2e/step_definitions/api/api-PokemonGo.cy.js

/// <reference types="cypress" />

import { When, Then } from "@badeball/cypress-cucumber-preprocessor";

const url = "https://pokeapi.co/api/v2/";

When("I send {string}", (endpoint) => {
  cy.request("GET", url + endpoint).as("response");
});

Then("I validate answers you want to receive", () => {
  cy.get("@response").its("status").should("equal", 200);

  cy.get("@response").its("body").should("have.property", "name", "stench"); // Ejemplo de aserción
});

Método	Endpoint Base	Ruta de Ejemplo	Parámetros	Autenticación	Ejemplo de Respuesta (Status 200)
GET	`https://pokeapi.co/api/v2/`	`ability/1`	ID de habilidad	No requerida	JSON con detalles de la habilidad (ej. `{ "name": "stench", ... }`)

Componentes Específicos

Cypress

Configuración Principal: cypress.config.js

Define el preprocesador para Cucumber (@badeball/cypress-cucumber-preprocessor y @bahmutov/cypress-esbuild-preprocessor).
Configura el reportero Mochawesome (reporter: 'mochawesome').
Maneja variables de entorno (env).
Establece patrones para los archivos de especificación (specPattern).
Carga configuraciones de baseUrl específicas del entorno desde cypress/config/[entorno].config.json.
Filtra navegadores para usar solo los basados en Chromium.

// Ejemplo de cypress.config.js (extracto)
module.exports = {
  reporter: "mochawesome",
  // ... otras configuraciones ...
  e2e: {
    env: {
      auth0_username: process.env.AUTH0_USERNAME,
      auth0_password: process.env.AUTH0_PASSWORD,
      // ...
    },
    specPattern: "cypress/e2e/features/*/*.feature",
    async setupNodeEvents(on, config) {
      // ... configuración del preprocesador y entornos ...
      const environmentName = config.env.environmentName || "cypress.dev";
      const environmentFileName = `./cypress/config/${environmentName}.config.json`;
      const settings = require(environmentFileName);
      if (settings.baseUrl) {
        config.baseUrl = settings.baseUrl;
      }
      return config;
    },
  },
};

Configuración de Cucumber: .cypress-cucumber-preprocessorrc.json
- Define las rutas donde se encuentran los archivos de step definitions.
```
{
  "stepDefinitions": ["[filepath]/**/*/*.{js,ts}", "[filepath].{js,ts}", "cypress/e2e/step_definitions/*/*.{js,ts}"]
}
```

Autenticación Azure Active Directory (AAD)

Implementación: cypress/support/e2e.js

Define un comando personalizado cy.loginToAAD(username, password).
Este comando maneja el flujo de inicio de sesión de Microsoft, interactuando con login.microsoftonline.com.
Utiliza cy.session() para cachear la sesión de autenticación y evitar logins repetitivos entre pruebas.
Intercepta las peticiones para añadir un header custom eMantto-Custom-Header.

// cypress/support/e2e.js (extracto)
function loginViaAAD(username, password) {
  // ... lógica de login con AAD ...
  cy.origin("login.microsoftonline.com" /* ... */);
}

Cypress.Commands.add("loginToAAD", (username, password) => {
  cy.session(
    `aad-${username}`,
    () => {
      /* ... */
    },
    {
      validate: () => {
        cy.getCookie("eMantto").should("exist");
      },
      cacheAcrossSpecs: true,
    }
  );
});

Uso: En los archivos de step definitions (ej. cypress/e2e/step_definitions/ui/LoginPage.cy.js):

import LoginAadPage from "../../../support/pages/login-aad-page";
// ...
Given("Previous authentication with AAD", () => {
  LoginAadPage.authADD; // Llama a cy.loginToAAD con credenciales del .env
  cy.visit("/");
});

El login-aad-page.js abstrae el uso de las credenciales del .env:

// cypress/support/pages/login-aad-page.js
class LoginAAD {
  get authADD() {
    cy.loginToAAD(Cypress.env("auth0_username"), Cypress.env("auth0_password"));
  }
  get authADD1() {
    // Para otro rol/usuario
    cy.loginToAAD(Cypress.env("auth1_username"), Cypress.env("auth1_password"));
  }
}
export default new LoginAAD();

Page Object Model (POM)

El proyecto utiliza el patrón Page Object Model para organizar los selectores y acciones de la UI. Los archivos de Page Objects se encuentran en cypress/support/pages/.

principal-page.js: Define elementos y métodos para la página principal de la aplicación.
login-page.js: Podría ser para un login no-AAD o elementos genéricos de login.
login-aad-page.js: Proporciona métodos para invocar el login AAD con diferentes usuarios/roles.

Mochawesome Reporter

Configuración: En cypress.config.js, se especifica reporter: 'mochawesome' y reporterOptions.

// cypress.config.js (extracto)
reporterOptions: {
    html: true,
    json: true,
    charts: true,
    overwrite: true,
    inlineAssets: true,
    embeddedScreenshots: true,
    reportDir: 'cypress/results',
    reportFilename: '[name].json',
},

Generación: Las pruebas ejecutadas con el flag -r mochawesome (o si es el reporter por defecto) generan archivos JSON en cypress/results/. El script npm run cy:report luego los fusiona (mochawesome-merge) y genera un reporte HTML (marge). Screenshots y videos de las fallas también son capturados y pueden ser enlazados en el reporte.

Pruebas

Este proyecto está dedicado enteramente a la creación y ejecución de pruebas automatizadas.

Tipos de Pruebas

Pruebas de UI (End-to-End): Verifican el flujo completo de la aplicación desde la perspectiva del usuario, interactuando con la interfaz gráfica. Ejemplo: cypress/e2e/features/ui/LoginAAD.feature
Pruebas de API: Verifican endpoints específicos de servicios backend.
- Ejemplo: cypress/e2e/features/api/api-PokemonGo.feature

Estructura de las Pruebas

Features: Archivos .feature escritos en Gherkin, ubicados en cypress/e2e/features/. Describen el comportamiento esperado del sistema.
Step Definitions: Archivos JavaScript (.cy.js) ubicados en cypress/e2e/step_definitions/. Mapean los pasos de Gherkin a código Cypress ejecutable.
Support Files:
- cypress/support/commands.js: Para definir comandos Cypress personalizados (aunque loginToAAD está en e2e.js).
- cypress/support/e2e.js: Archivo principal de soporte, donde se importa commands.js y se pueden definir configuraciones globales o listeners. Aquí se encuentra la lógica de loginToAAD.
- cypress/support/pages/: Contiene los Page Objects.
Fixtures: Datos de prueba estáticos en formato JSON, ubicados en cypress/fixtures/ (ej. example.json).

Cómo Ejecutar Pruebas

Consulta la sección "Ejecutar Pruebas Localmente" dentro de "Configuración Local" para ver los comandos npm run ....

Reportes de Pruebas

Las pruebas generan reportes JSON individuales por Mochawesome en cypress/results/.
Videos de las ejecuciones se guardan en cypress/videos/ (si video: true).
Screenshots de fallos se guardan en cypress/screenshots/ (si screenshotOnRunFailure: true).
Utiliza npm run cy:report para generar un reporte HTML consolidado, que incluirá estos artefactos.

Consideraciones de Seguridad

Gestión de Credenciales:
- Local: Las credenciales sensibles (como contraseñas de AAD) deben almacenarse en un archivo .env en la raíz del proyecto. Este archivo está incluido en .gitignore para evitar que se suba al repositorio.
- CI/CD (Jenkins/Cloud Run): Las credenciales NO deben estar hardcodeadas en el código ni en los archivos de configuración de entorno versionados (deploy/env/*.yaml). Se deben gestionar como secretos en el sistema de CI/CD. - El archivo deploy/run/runtime-config.yaml.erb muestra cómo se pueden pasar secretos: update-secrets: AUTH0_PASSWORD=auth0_password,AUTH1_PASSWORD=auth1_password. El CI/CD debe proveer los valores reales para auth0_password y auth1_password.
Exposición de Información: Asegúrate de que los reportes y logs generados no expongan información sensible. Mochawesome reporter options están configuradas para inlineAssets: true and embeddedScreenshots: true, lo cual es conveniente pero empaqueta todo en el HTML. Considera las políticas de compartición de estos reportes.
Headers Personalizados: El comando loginToAAD añade eMantto-Custom-Header: eMx-e2e-testing-Cypress. Asegúrate de que este header es esperado y manejado adecuadamente por la aplicación bajo prueba y no introduce vulnerabilidades.

Propósito y Alcance​

Arquitectura​

Tecnologías y Dependencias​

Configuración Local​

Prerrequisitos​

Pasos de Configuración​

Ejecutar Pruebas Localmente​

Despliegue​

Jenkins​

Configuración de Entornos en CI​

Configuración de Runtime (Cloud Run - si aplica a la ejecución de los tests, no al AUT)​

Endpoints de la API​

Pokémon GO API (Ejemplo)​

Componentes Específicos​

Cypress​

Autenticación Azure Active Directory (AAD)​

Page Object Model (POM)​

Mochawesome Reporter​

Pruebas​

Tipos de Pruebas​

Estructura de las Pruebas​

Cómo Ejecutar Pruebas​

Reportes de Pruebas​

Consideraciones de Seguridad​