🧪 Testing Automation - Cypress 👨🏻‍🚀 CI/CD

Este repositorio contiene un marco de automatización de pruebas para el proyecto Cypress. El marco está diseñado para ejecutar pruebas de regresión, pruebas de humo y pruebas de integración en un entorno de CI/CD. El marco de automatización está construido con las mejores prácticas y patrones de diseño para garantizar la escalabilidad, mantenibilidad y reutilización del código de prueba.

Requisitos para Usar el Repositorio

Antes de comenzar a trabajar con el repositorio, asegúrate de cumplir con los siguientes requisitos de software. Estos son esenciales para garantizar un entorno de trabajo fluido y compatible con los estándares de UPEX.

Instalar el Controlador de Versiones y la Terminal
- Git: Instala Git para la gestión de versiones y colaboración en el repositorio. Es fundamental para clonar, ramificar y contribuir al proyecto.
  - Instalar Git
- Terminal de Git (Git Bash): Recomendado para usuarios de Windows. Ofrece una experiencia de terminal similar a Unix, facilitando la ejecución de comandos.
  - Instalar Git Bash
Instalar el Entorno de Desarrollo
- Visual Studio Code (VSCode): El workspace ideal para trabajar localmente en proyectos de automatización de pruebas. VSCode ofrece una integración perfecta con Git, depuración avanzada y un ecosistema robusto de extensiones.
  - Instalar VSCode
Instalar el Gestor de Paquetes y Dependencias

Dependiendo del framework de automatización utilizado en el repositorio, asegúrate de instalar el Package Manager adecuado para lenguaje de programación y framework de pruebas:
- Para Frameworks con JavaScript/TypeScript:
  - Node.js: Requerido si el proyecto utiliza frameworks como WebdriverIO, Cypress, Playwright o SeleniumJS. Instalando Node.js, obtendrás automáticamente npm como gestor de paquetes y JavaScript runtime.
    - Instalar Node.js (Versión LTS)
  - Gestor de Paquetes Node: Identifica cuál es el gestor de paquetes adecuado para el repositorio inspeccionando el archivo de bloqueo (.lock) en el directorio raíz. Esto te indicará si debes usar npm, pnpm o yarn para ejecutar los scripts del proyecto.
    - yarn: Si ves yarn.lock, usas yarn.
      - Instalación: npm install -g yarn
    - Ver una Comparación entre estos Gestores
CLI del Framework de Automatización Por último, asegúrate de instalar la CLI específica del framework de automatización utilizado en el proyecto (preferiblemente de forma global porque podrías necesitarla en diferentes proyectos):
- Cypress: npm install -g cypress

Getting Started

Pasos generales para comenzar a trabajar con el repositorio:

Clona este repositorio:
```
git clone {{REPO_URL}}
```
Navega hasta el directorio del proyecto:
```
cd {{REPO_FOLDER}}
```
[!TIP] Puedes arrastrar la carpeta del repo hacia dentro del Editor de VsCode para hacer lo mismo
Instala las dependencias con el CLI del package manager:
```
{{package}} install
```
Crear el archivo .env para guardar tus Variables de Environment: Si el proyecto necesita variables de Ambiente, crea tu archivo .env en la directorio root del proyecto para guardar las variables de environment (revisa el el archivo de config del framework para ver qué necesitas) y agregarlo al .gitignore.
Conoce y ejecuta scripts del package.json:

Cada repositorio tiene scripts predefinidos para ejecutar pruebas, suites, y reportes. Revisa el archivo package.json para ver los scripts disponibles para ejecutar en la terminal.

📝 Plan de Repositorio QA Automation

A continuación se presenta el Plan completo de uso del Repositorio de UPEX. Es fundamental seguir todas las directrices y lineamientos establecidos en este documento para garantizar un trabajo eficiente y de calidad en el ámbito de QA Automation. El cumplimiento de estos lineamientos es esencial para el éxito de los proyectos y la mejora continua de los procesos de automatización de pruebas. ¡Tu compromiso y dedicación en seguir estas pautas son clave para el logro de los objetivos establecidos!

🛠️ Proceso de Contribución al Repositorio (Flujo de Git)

Crea una Nueva Rama (Nomenclatura de Branching)

Antes de comenzar a trabajar, crea una nueva rama para tu tarea o funcionalidad. Puedes crear la rama con el comandos git branch (para crearlo sin moverte) o git checkout -b (para crearlo y moverte a la rama). Recuerda crear la rama de tarea siguiendo las Buenas Prácticas y Nomenclaturas de Git bajo el siguiente formato de Nombre de Branch:
- Tipo de Branch (type):
  - feature: tarea de nueva funcionalidad
  - fix: tarea de corrección de errores
  - docs: tarea de documentación
  - style: tarea de estilos
  - refactor: tarea de refactorización
  - test: tarea de pruebas
  - chore: tarea de mantenimiento
- ID de Jira (jiraID): puede ser el ID de la Tarea o Story (si aplica la trazabilidad), colocándolo después del type, ejemplo test/GX3-123/
- Nombre de la Rama (branch-name): debería ser el mismo nombre de la Tarea o Story (resumido si es largo), en minúsculas y separado por guiones, ejemplo buy-product
- Formato del Branch: "type/jiraID/branch-name" (cada parte debería estar separada por una barra /)
- Ejemplo:
```
git checkout -b test/GX3-123/buy-product
```
Realiza Cambios (Git Add) y Comitea (Nomenclatura de Commiting)

Realiza los cambios necesarios en tu rama y añade los archivos modificados al staging area:
```
git add .
```
Realiza un commit con un mensaje claro y descriptivo siguiendo las Buenas Prácticas y Nomenclaturas de Git bajo el siguiente formato de mensaje de commit:
- Tipo de Commit (type):
  - feat: Nuevas features o módulos
  - fix: Corrección de errores
  - docs: Cambios en la documentación
  - style: Cambios en el estilo del código
  - refactor: Refactorización del código
  - test: Añadir o modificar pruebas
  - chore: Tareas de mantenimiento
- ID de Jira (jiraID): Puede ser el ID de la Tarea o Story (si aplica la trazabilidad), encerrado con paréntesis, ejemplo (GX3-123)
- Descripción (Desc): Verbo en infinitivo + objeto del cambio
- Formato del Mensaje: "tipo: (jiraID) Desc"
- Ejemplo:
```
git commit -m "test: (GX3-123) add 2 test cases for the login page"
```

Tip

Recomandamos leer Conventional Commits)

Actualiza tu Rama (Git Pull)

Asegúrate de que tu rama esté actualizada con la rama de integración principal (QA):
```
git pull origin QA
```

Tip

Esto te permitirá resolver cualquier conflicto que pueda surgir antes de subir tus cambios. Es importante mantener tu rama actualizada con la rama principal para evitar conflictos y asegurar una integración fluida.

Sube tu Rama al Repositorio Remoto (Git Push)

Pushea tu rama al repositorio remoto:
```
git push origin nombre-de-la-rama
```

Note

Recuerda que es importante subir tu rama al repositorio remoto para que el equipo pueda revisar tus cambios y realizar la integración.

Crea un Pull Request (PR)

Una vez que hayas subido tu rama, crea un Pull Request (PR) en GitHub usando el Template predefinido.
- Importante: Cuando crees un PR, se generará automáticamente un template predefinido. Asegúrate de completar todos los campos requeridos en el template para una correcta revisión del PR (El mismo template de Pull Request está disponible en cada repositorio)

Tip

Si quieres saber cómo es el template del PR, lo puedes ver en docs/pull_request_template.md en el Repo. Sin embargo, no es necesario copiarlo, ya que se generará automáticamente en tu PR. [!NOTE] Recuerda agregar una evidencia de tus resultados de prueba en la sección de "Test Results" del PR. Puedes incluir capturas de pantalla o un enlace al reporte de Pruebas o al pipeline de SanityTest.

Revisión y Merge

El equipo revisará tu PR. Es posible que recibas comentarios o solicitudes de cambio. Una vez que el PR sea aprobado, se integrará a la rama QA siguiendo el flujo de trabajo establecido.

🧪 Estrategia para Continuous Integration (CI/CD): GitHub Actions

Este repositorio está configurado para ejecutar pruebas automatizadas mediante diferentes estrategias de ejecución de pruebas utilizando GitHub Actions:

Ejecutar las pruebas de Sanity (cualquier directorio de pruebas o una suite de pruebas específica) con el pipeline sanity.yml (puedes importar los resultados de las pruebas a XRay con este).
Ejecutar las pruebas de Smoke y Regression con el pipeline regression.yml.

> PIPELINES:

SanityTest (Activación manual):
- Esta es una estrategia de ejecución de pruebas para verificar una suite de pruebas específica. Por ejemplo, si solo quieres validar que el conjunto de pruebas para un Módulo de la App funcione como se espera.
- Ejecutar: cualquier tipo de prueba o suite para verificar módulos específicos de la aplicación.
- Cuándo:
  - Se puede activar manualmente desde la interfaz "Run Workflow" de GitHub Actions.
SmokeTest (Activación manual o verificación de Pull-Request):
- Esta es una estrategia de ejecución de pruebas para verificar los módulos principales de la aplicación. Por ejemplo, antes de ejecutar las pruebas de regresión, queremos asegurarnos de que los módulos principales funcionen como se espera (las principales características de la aplicación deberían funcionar).
- Ejecutar: Pruebas de API o pruebas E2E para verificar los módulos principales de la aplicación.
- Cuándo:
  - Se puede activar manualmente desde la interfaz "Run Workflow" de GitHub Actions.
  - Se puede configurar para que se active automáticamente después de un Deploy de Dev.
RegressionTesting (Activación manual o recomendado después de Smoke):
- Esta es una estrategia de ejecución de pruebas para verificar todos los módulos de la aplicación. Por ejemplo, después de ejecutar las pruebas de Smoke (los módulos principales funcionan), queremos validar que el resto de las módulos y funcionalidades funcionen como se espera (todos los componentes deberían funcionar).
- Ejecutar: Todas las pruebas candidatas para verificar la mayoría de las características de la aplicación.
- Cuándo:
  - Se puede activar manualmente desde la interfaz "Run Workflow" de GitHub Actions.
    - Comienza siempre luego de un Job de SmokeTest exitoso en el mismo Pipeline de Regresión
  - Se puede configurar para que se active automáticamente cuando se abra un Pull-Request para verificar los nuevos cambios antes del merge.
  - Se puede configurar para que se active automáticamente después de que se hiciera merge los nuevos cambios en la rama principal.
  - Se puede configurar para ejecutarse en un horario específico.

> Manual Trigger de los PIPELINES

Directamente en GitHub Actions, puedes activar manualmente el pipeline de Sanity especificando ciertos valores en la interfaz "Run Workflow".
Para ejecutar manualmente los pipelines, sigue estos pasos:
1. Navega a la pestaña "Actions" en GitHub.
2. Selecciona el pipeline que deseas ejecutar (SanityTest, RegressionTesting).
3. Haz clic en "Run workflow" y configura los parámetros requeridos:
  - Branch: Selecciona la rama desde donde quieres ejecutar las pruebas.
  - OS: Selecciona el sistema operativo.
  - Environment: Elige el ambiente de pruebas (QA, staging, etc.).
  - Test Suite: Especifica la suite que deseas ejecutar colocando el path del archivo.
  - Test Execution ID: Especifica el id del TX de Jira para importar resultados a Jira Xray
  - Project Key: Elige el proyecto de tu TX como requisito final (GX3 es casi siempre)

Run Workflow Config:

 inputs:
 system:
    description: 🚀Select the OS
    required: true
    default: 'ubuntu-latest'
    type: choice
    options:
    - ubuntu-latest
    - ubuntu-22.04
    - macos-latest
    - windows-latest
 environment:
    description: 🚀Select the Test Environment
    required: true
    default: 'QA'
    type: choice
    options: #? Orden de Deployments...
    - DEV #? donde los developers work
    - SANDBOX #? donde los QA realizan smoke y exploratory testing.
    - QA #? donde los QA realizan smoke, sanity y regression testing.
    - STAGING #? donde los QA realizan smoke, sanity o regression testing.
    - UAT #? donde los beta testers realizan acceptance testing.
    - PROD #? donde los usuarios finales usan la App.
 test_run:
    description: 🚀Select the Test Suite to Run
    required: true
    default: 'test/specs/another.e2e.ts' #! Example.
    type: string
 xray_tx:
    description: 🚀Enter the Test Execution ID
    required: true
    default: 'GX3-1526' #! Example.
    type: string
 xray_project:
    description: 🚀Select the Project Key
    required: true
    default: 'GX3' #! Example.
    type: choice
    options:
    - GX1
    - GX2
    - GX3
    - GX4

Note

No necesitas cambiar el archivo yml en el repositorio, simplemente utiliza la interfaz "Run Workflow" de GitHub Actions para seleccionar la Suite de Pruebas y el ID de Ejecución de Pruebas de XRay para importarlo a Jira.

> Acciones Extras de los PIPELINES:

Guardar capturas de pantalla de las pruebas fallidas y subirlas como artefacto de CI
Guardar cada archivo de log en una carpeta y subirlo como artefacto de CI
Importar automáticamente los resultados de las pruebas a XRay con los argumentos dados.
Desplegar el Report de Mochawesome en la rama de GitHubPages (para que puedas ver los resultados en vivo).
Enviar una notificación de Slack (de UPEX) para mostrar un resumen general en el canal de GitHub.

🧪 Estrategia para Reporte de Pruebas: "Mochawesome"

Este repositorio utiliza Mochawesome Report para generar reportes detallados de las pruebas ejecutadas. Los reportes de Mochawesome se generan y se despliegan automáticamente en GitHub Pages después de cada Pipeline.

> Dónde ver el Reporte de Mochawesome en GitHub Pages

Los reportes se pueden visualizar directamente desde el GitHub Pages del Repo:
- Para ver el Reporte de Regresión: Debes ir a la URL de GitHub Pages, en la url principal, disponible cuando termine el Pipeline de RegressionTesting y se ejecute el Deploy.
- Para ver el Reporte de SanityTest de tu XRay Test Execution (TX): Debes ir al endpoint sanity/{{xray_tx_id}} de la URL de GitHub Pages, disponible cuando termine el Pipeline de SanityTest y se ejecute el Deploy.

🧪 Estrategias y Nomenclaturas para Desarrollo de Pruebas (Archivos)

Para mantener la consistencia y claridad en los repositorios de UPEX, sigue estas guías de estructura y nomenclatura (Los ejemplos pueden variar dependiendo del Lenguaje de Programación y Framework)

> Estructura: Page Object Model (POM) (Patrón de Diseño):

Directorio: .../pageobjects o .../pages

Nomenclatura: PascalCase o snake_case según el lenguaje:

Para Node (JS/TS): **Page.js / **Page.ts - ejemplo: LoginPage.ts

Estructura básica de POM en Cypress con Typescript:

export class LoginPage {
  // Tipado de Elementos de la Página
  loginButton: () => Cypress.Chainable<JQuery<HTMLButtonElement>>;
  constructor() {
      // Elementos de la Página
      this.loginButton = () => cy.get('[form=login]').contains('button', 'Log in');
  }
  submitLogin() { // Método de Acción
      this.loginButton().click();
  }
}

Tip

Propiedades de la Clase son equivalentes a Elementos y Atributos del Page: Procura usar métodos de localización estratégicos para simplificar el uso de selectores del Framework. Apoya tu POM con los métodos de Test Utility (Locators) para mantener un código limpio y reutilizable.
Métodos de la Clase son equivalentes a Métodos de Acción del Page: Manten una nomenclatura clara y descriptiva para los métodos de acción en el POM. Usa verbos en infinitivo para describir las acciones que realiza el método como si fuera una instrucción.
Técnica Shortcut: Puedes crear un método que realice varias acciones en una sola llamada para simplificar el uso del POM. Por ejemplo, un método login que realice el llenado de credenciales y el envío del formulario de login.

> Estructura: API Modules (Patrón de Diseño):

Directorio: test/api
Carpeta de Interfaces Typescript: test/api/types
Nomenclatura: PascalCase con sufijo .Api.ts (ejemplo: Subscriptions.Api.ts)
La Estructura es similar a un Page Object, pero con métodos para realizar peticiones HTTP.

> Estructura: Test Utility Modules (Locators, Actions, Assertions):

Directorio: test/utils
Definición de cada Módulo de Utilidad de Prueba: - Locators: Métodos para localizar elementos de la página. - Actions: Métodos para realizar acciones en la página. - Assertions: Métodos para validar resultados y estados de la página.

Note

Los Frameworks modernos como Cypress, Playwright y WebdriverIO tienen métodos y funciones integradas para realizar estas acciones y validaciones, por lo que no es necesario crear módulos de utilidad personalizados a menos que sea necesario para métodos específicos que no estén disponibles en el Framework o requiera más personalización situacional.

> Estructura: Técnicas de Test Management (TestBase, TestPlan):

Técnica "TestBase":
- Definición: Es una técnica común en los frameworks de automatización de pruebas, que consiste en tener un archivo que contiene todos los PageObjects y funciones de utilidad para importarlo en cada archivo de prueba y acceder a los POM y utilidades con mayor facilidad.
- Directorio: Este archivo se puede ubicar en cualquier directorio específico, pero se recomienda en el directorio raíz de pruebas.
- Para Node (JS/TS): /TestBase.ts (Playwright/WebdriverIO) o /commands.ts (Cypress)
  - Ejemplo TestBase en Cypress con Typescript:
    - En Cypress se usa el módulo de Commands.ts como el TestBase.
```
import { LoginPage } from '@pages/LoginPage';
import { HomePage } from '@pages/HomePage';

Cypress.Commands.add('page', () => {
    const page = {
        // Se instancian los PageObjects como propiedades de objeto
        loginPage: new LoginPage(),
        homePage: new HomePage()
    };
    return cy.wrap(page); // Se envuelve como un objeto Cypress
});
// ---- Uso en archivo de prueba ----: 
it('test case name', () => {
    cy.page().loginPage.submitLogin();
});
```

Note

Este archivo se importa en cada archivo de prueba para acceder a todos los PageObjects (o funciones de utilidad) con mayor facilidad. Además, la creación de cada TestBase para cada framework es diferente, por lo que se debe ajustar según el framework. En Playwright, por ejemplo, se usa la técnica Fixture para armar el TestBase. En Cypress, se usa el Commands.js como el TestBase. Y así sucesivamente.

> Estructura: Archivos de Prueba (E2E o Integration):

Nomenclatura de Sufijos de Pruebas para E2E o Integration:
- para pruebas generales: **.cy.{js,ts}
- para pruebas de E2E: **.e2e.cy.{js,ts}
- para pruebas de Integration: **.api.cy.{js,ts}
Path de Pruebas:
- Cypress(TS): cypress/e2e/specs/<component-name>/*.ts (ejemplo: cypress/e2e/specs/payment/payByDebit.cy.ts)
Nomenclatura del Suite de Prueba (describe/class) debería ser:
- Jira Story ID + Story title
  - Ejemplo: GX3-123: Login Page
Nomenclatura del Caso de Prueba (it/test/def) debería ser:
- Jira Test Set ID + TC# + TC Title
  - Ejemplo: GX3-234 TC1: Should not login with invalid credentials

> Estructura Matriz de Prueba Automatizada con modelo (Arrange - Act - Assert):

Definición: Es la forma de organizar y estructurar el código de prueba automatizada para mantener un código limpio y fácil de mantener. La estructura de la prueba se divide en tres secciones principales

Patrón de Diseño: Arrange - Act - Assert

Arrange: Es la primera sección de la prueba y se utiliza para declarar datos y variables, y configurar el estado inicial de la prueba.
- Ejemplo con Cypress:
```
it('GX3-234 TC1: {{Test_title}}', () => {
    const username = 'user1';
    const password = 'password1';
    // ...
});
```

Act: Es la segunda sección de la prueba y se utiliza para realizar acciones y operaciones en la aplicación bajo prueba.

Ejemplo con Cypress:

// ...
   loginPage.open();
   loginPage.fillUsername(username);
   loginPage.fillPassword(password);
   loginPage.submitLogin();
// ...

Assert: Es la última sección de la prueba y se utiliza para realizar validaciones y comprobaciones con los expect.
- Ejemplo con Cypress:
```
// ...
loginPage.getErrorMessage().should('have.text', 'Invalid credentials');
```

Ejemplo Completo de la Estructura de Prueba:

import { loginPage } from '@pages/LoginPage';
describe('GX3-123: Login Page', () => {
   beforeEach(() => {
         // acciones de precondición de prueba
   });
   it('GX3-234 TC1: Should not login with invalid credentials', () => {
         // Arrange
         const username = 'user1';
         const password = 'password1';
         // Act
         loginPage.open();
         loginPage.fillUsername(username);
         loginPage.fillPassword(password);
         loginPage.submitLogin();
         // Assert
         loginPage.getErrorMessage().should('have.text', 'Invalid credentials');
   });
});

upex-galaxy/upex-cypress-demo

🧪 Testing Automation - Cypress 👨🏻‍🚀 CI/CD

Requisitos para Usar el Repositorio

Getting Started

📝 Plan de Repositorio QA Automation

🛠️ Proceso de Contribución al Repositorio (Flujo de Git)

🧪 Estrategia para Continuous Integration (CI/CD): GitHub Actions

> PIPELINES:

> Manual Trigger de los PIPELINES

> Acciones Extras de los PIPELINES:

🧪 Estrategia para Reporte de Pruebas: "Mochawesome"

> Dónde ver el Reporte de Mochawesome en GitHub Pages

🧪 Estrategias y Nomenclaturas para Desarrollo de Pruebas (Archivos)

> Estructura: Page Object Model (POM) (Patrón de Diseño):

> Estructura: API Modules (Patrón de Diseño):

> Estructura: Test Utility Modules (Locators, Actions, Assertions):

> Estructura: Técnicas de Test Management (TestBase, TestPlan):

> Estructura: Archivos de Prueba (E2E o Integration):

> Estructura Matriz de Prueba Automatizada con modelo (Arrange - Act - Assert):