Skip to content

Guía de Uso de Pruebas Cypress – LPSmart

Proposito:

Este apartado explica cómo se deben usar, ejecutar y mantener las pruebas automáticas de Cypress implementadas en el sistema LPSmart. El objetivo es garantizar la correcta validación de las funcionalidades críticas mediante un flujo automatizado e integrado con GitHub Actions y notificación por correo electrónico.

Estructura del proyecto de pruebas

.github/
├── wofflows/
│   ├── Ci_Cypress.yml/

cypress/
├── e2e/
│   ├── Ingresos/
|   ├── Egresos/
│   ├── Productos/
│   ├── Terceros/
│   └── Reportes
├── fixtures/
├── support/
│   ├── commands.js
│   └── e2e.js
├── cypress.config.js
  • cypress/e2e/: Contiene las pruebas separadas por módulos.
  • support/commands.js: Define comandos personalizados (por ejemplo, cy.login()).
  • support/e2e.js: Configuraciones globales de Cypress

  • cypress.config.js: Archivo de configuración principal de Cypress

  • .github/workflows/CI_Cypress.yml: Archivo que automatiza la ejecución y envío del reporte por correo.

Ejecución automática CI

Las pruebas Cypress se ejecutan automáticamente mediante el flujo definido en:

.github/workflows/CI_Cypress.yml

Este workflow se activa en los siguientes casos:

| Cuando se realiza un push a las ramas:

  • main
  • Practicante_Anderson
  • Pre_Produccion

Flujo de trabajo automatizado

%%{init: {'theme': 'default', 'flowchart': { 'curve': 'basis' }, 'themeVariables': { 'fontSize': '30px', 'primaryColor': '#dbeafe' }}}%%
flowchart LR
    A[ Commit en GitHub] --> B[ Detección de módulos según el mensaje]
    B --> C[ Ejecución de pruebas Cypress]
    C --> D[ Generación del reporte Mochawesome]
    D --> E[ Publicación en GitHub Pages]
    E --> F[ Envío de correo con resultados]

1. Preparación del entorno

  • Se instala Node.js (v20).
  • Se ejecuta npm ci para instalar dependencias.
  • Se limpia cualquier reporte anterior.

2. Detección inteligente de módulos

El sistema analiza el mensaje del commit para decidir qué pruebas ejecutar:

  • Si el mensaje incluye “terceros”, solo ejecutará cypress/e2e/terceros.
  • Si no detecta módulos, ejecuta todas las pruebas.

3. Ejecución de pruebas

Ejecuta los tests Cypress en modo headless Chrome:

npx cypress run --spec "cypress/e2e/terceros/**/*.cy.js" --browser chrome

4. Generación y despliegue del reporte

El reporte HTML se genera con Mochawesome y se publica automáticamente en:

Reporte Mochawesome

5. Notificación por correo electrónico

Tras cada ejecución, se envía un correo con:

  • Repositorio
  • Rama
  • Commit ejecutado
  • Módulos probados
  • Estado final (éxito o fallo)
  • Enlaces al reporte y al log de ejecución

Ejemplo de correo automático

Asunto:

REPORTES CYPRESS - LPSMART 'Actualización módulo Cotizaciones' #57

Cuerpo del mensaje:

Hola,

Se ha ejecutado el flujo de pruebas Cypress:

Repositorio: Lpconsultoresempresariales/LPSmart
Rama: main
Commit: Actualización módulo Cotizaciones
Módulos probados: Cotizaciones

Reporte completo:
https://lpconsultoresempresariales.github.io/Report-Cypress/

Detalles:
https://github.com/Lpconsultoresempresariales/LPSmart/actions/runs/xxxxxx

Estado:  Success

Mantenimiento del flujo CI

Si se actualiza el repositorio de reportes o los correos de destino, se deben modificar las siguientes variables en GitHub Secrets:

Variable Descripción
EMAIL_SERVER Servidor SMTP utilizado para el envío de reportes.
EMAIL_USER Correo emisor (usado por el bot de GitHub).
EMAIL_PASS Contraseña del correo emisor.
EMAIL_TO Dirección o lista de correos que recibirán el reporte.
GH_TOKEN Token de acceso con permisos de escritura al repositorio de reportes.

Importante: No modificar estos valores directamente en el workflow. Todas las credenciales deben manejarse únicamente mediante GitHub Secrets para garantizar la seguridad del proceso.

Ejecución manual (para desarrollo local)

Los desarrolladores pueden ejecutar las pruebas de forma local antes de subir cambios al repositorio.

Ejecutar todas las pruebas

npx cypress run

Ejecutar un módulo específico

npx cypress run --spec "cypress/e2e/terceros/**/*.cy.js" --browser chrome

Ejecución con interfaz gráfica (modo interactivo)

Para visualizar paso a paso la ejecución de las pruebas:

npx cypress open

Esto abrirá la interfaz de Cypress, desde donde se pueden:

  • Seleccionar las pruebas por módulo o archivo.
  • Observar en tiempo real las acciones del navegador.
  • Revisar los comandos ejecutados y los resultados visuales.

Recomendación: Usar este modo durante el desarrollo o mantenimiento de las pruebas, ya que facilita la detección de errores visuales o de flujo antes de hacer push al repositorio.

Recordatorio

Los reportes Cypress no se generan localmente. El flujo está diseñado para ejecutarse únicamente en GitHub Actions, que se encarga de:

  • Ejecutar las pruebas.
  • Generar los reportes.
  • Publicarlos en GitHub Pages.
  • Enviar la notificación por correo.

Consideraciones Generales

  • Cypress está diseñado para validar la experiencia del usuario en el navegador, no procesos del servidor.
  • Antes de hacer push, ejecutar las pruebas localmente para validar que todo funcione.
  • Manténer los selectores actualizados conforme cambien las vistas o componentes.

Buenas prácticas y mantenimiento

Esta sección establece las recomendaciones que deben seguirse para asegurar la calidad, escalabilidad y mantenibilidad de las pruebas

Estructura y organización

  • Mantener las pruebas agrupadas por módulos funcionales (Terceros, Productos, Reportes, etc.).
  • Nombrar los archivos de forma descriptiva:
RegistroTercero.cy.js
EditarTercero.cy.js
EliminarTercer.cy.js
  • Cada archivo debe validar una funcionalidad o flujo específico.

Nomenclatura y descripciones

  • Usar descripciones claras en describe() e it():
describe("Terceros - Crear nuevo cliente", () => {
    it("Debe registrar un nuevo cliente con datos válidos", () => {
        ...
    });
});
  • Evitar nombres genéricos como “Prueba 1” o “Validación básica”.

Sesiones y autenticación

  • Centralizar el inicio de sesión en commands.js como actualmente esta, usando cy.session() para optimizar tiempos y reducir redundancia.

Mantenimiento y actualización

  • Revisar y actualizar los selectores después de cada cambio en la interfaz.
  • Eliminar pruebas obsoletas o redundantes.
  • Documentar nuevas pruebas siguiendo la misma estructura establecida.