Template: Framework Cypress - [template-cypress]

Authors: TAEs LATAM

• Evans Ladera

Tecnologías

Lista de tecnologías utilizadas en este proyecto:

• Node.js: Version >= 20.3.0
• npm: Version >= 9.6.7
• Cypress: Version >= 14.0.3
• Mochawesome: Para reportes de pruebas.
• Rimraf: Para limpieza de archivos temporales.

Descripción

El template-cypress es un framework de pruebas automatizadas basado en el framework de pruebas frontend Cypress. Está diseñado para simplificar la escritura y ejecución de pruebas automatizadas E2E (end-to-end) y se encuentra configurado para integrarse con pipelines CI/CD en GitLab. Este proyecto permite a los equipos de desarrollo y calidad automatizar casos de prueba de extremo a extremo (E2E), proporcionar informes detallados y cumplir con los altos estándares de calidad en sus entregas.

Funcionalidades clave

El template-cypress ofrece las siguientes características principales:

1. Integración con Cypress: Permite escribir pruebas automatizadas de frontend.
2. Pruebas E2E configurables por entorno: Soporte para entornos dev, intg, y cert.
3. Linter para código Cypress: Utiliza eslint para garantizar la calidad de código.
4. Reportes automáticos con Mochawesome: Generación y fusión de informes de prueba.
5. Scripts de gestión: Simplifica tareas como limpieza, ejecución en diferentes entornos y debugging.
6. Integración CI/CD con GitLab: Soporte para pipelines automatizados.

Instalación

Clonar el repositorio y navega al directorio del proyecto:

  git clone https://gitlab.com/latamairlines/oper/emx/emx-tmpl/template_cypress.git
  cd template_cypress

Instala las dependencias del proyecto:

  npm install

Scripts disponibles

El archivo package.json contiene los siguientes scripts para ejecutar y gestionar las pruebas:

Limpieza

1. Eliminar resultados y archivos temporales:

  npm run cy:clean

Informaciones y verificaciones

2. Info Cypress (verificar instalación y compatibilidad):

  npm run cypress:info

3. Verificar instalación de Cypress:

  npm run cypress:verify

Ejecución de pruebas Cypress

4. Abrir Cypress (en modo GUI) en diferentes entornos:
   • Entorno dev:

  npm run cy:open:dev

• Entorno intg:

  npm run cy:open:intg

• Entorno cert:

  npm run cy:open:cert

5. Ejecutar todas las pruebas de manera "headless":

  npm run cypress:run

6. Ejecutar pruebas Cypress en un entorno específico con reporter Mochawesome:
   • Entorno dev:

  npm run cy:run:dev

• Entorno intg:

  npm run cy:run:intg

• Entorno cert:

  npm run cy:run:cert

Debugging

7. Modo Debug con Cypress:

  npm run cypress:debug

Linter

8. Eslint para garantizar calidad de código Cypress:

  npm run lint

Configuración

Variables de entorno

El framework utiliza la variable CYPRESS_ENV para identificar el entorno en el que estás ejecutando las pruebas (dev, intg, cert). Puedes configurarla directamente en el comando o en un archivo .env (si está configurado en tu entorno).

Archivos esenciales

• Directorio cypress/: Contiene todo el setup de las pruebas, incluyendo:
  • cypress/e2e/: Pruebas E2E.
  • cypress/fixtures/: Datos de prueba estáticos.
  • cypress/plugins/: Plugins de Cypress.
  • cypress/support/: Archivos de configuración global.
• package.json: Contiene los scripts automatizados mencionados anteriormente.
• Reportes: Los resultados se generan en cypress/results/.

Ejecución en CI/CD

El framework está preconfigurado para ejecutarse en pipelines de GitLab CI/CD, utilizando el archivo .gitlab-ci.yml. Este archivo incluye:

1. Instalación del entorno Node.js.
2. Ejecución de pruebas Cypress E2E en modo "headless".
3. Generación de reportes con Mochawesome.

Generación de reportes

Cypress está configurado para generar reportes usando el reporter mochawesome. Los resultados se ubican en el directorio cypress/results/ y se combinan en un único reporte visual utilizando:

  marge cypress/results/output.json --reportDir cypress/results --inline

Ejecución con Docker

El proyecto incluye un archivo Dockerfile configurado para ejecutar las pruebas de Cypress en un entorno contenedor. La imagen base utiliza cypress/browsers:latest e incluye las herramientas necesarias para ejecutar las pruebas, como jq.

Construir la imagen Docker

Puedes construir la imagen Docker utilizando el siguiente comando:

  docker build -t template-cypress .

Ejecutar las pruebas con Docker

1. Ejecutar las pruebas en el navegador por defecto (Chrome) y ambiente dev:

  docker run --rm -v $(pwd):/app -w /app template-cypress

2. Especificar un entorno y navegador en el comando de ejecución:

   Puedes personalizar las pruebas especificando el valor de los argumentos CYPRESS_ENV y BROWSER. Por ejemplo:

  docker run --rm -v $(pwd):/app -w /app \
    -e CYPRESS_ENV=intg \
    -e BROWSER=firefox \
    template-cypress

Parámetros:

• CYPRESS_ENV: Define el entorno donde se ejecutan las pruebas (dev, intg, cert, etc.).
• BROWSER: Permite elegir el navegador (chrome, firefox, edge, etc.).

3. Comando personalizado para integrarlo en pipelines:

   En entornos CI, puedes integrar esta ejecución como parte de las etapas de prueba:

  docker run --rm -v $(pwd):/app -w /app template-cypress

Notas importantes

• El directorio actual ($(pwd)) se monta en el contenedor en el directorio de trabajo /app.
• Asegúrate de que los resultados de las pruebas y otros archivos importantes sean accesibles en el host (puedes configurarlo con volúmenes adicionales si necesario).
• Utiliza la variable CYPRESS_ENV para cambiar entre entornos de prueba.
• El navegador especificado en el argumento BROWSER debe estar soportado por la imagen base.

Versionado del Template

Este template sigue estándares de Semantic Versioning, y su versión actual es 1.0.0.

1. MAJOR: Cambios incompatibles.
2. MINOR: Nuevas funcionalidades compatibles.
3. PATCH: Correcciones de errores compatibles.

Referencias

• Cypress Documentation: Cypress.io
• Mochawesome Reporter: Mochawesome
• Cypress Docker Images: Cypress Docker
• Node.js Documentation: Node.js