Comenzando con Allure Cypress

Genera hermosos informes HTML utilizando Allure Report y tus pruebas de Cypress.

Configuración

1. Prepara tu proyecto

1. Asegúrate de que Node.js esté instalado.

   Allure Cypress se prueba con Node.js 18 y versiones superiores. Las versiones anteriores pueden funcionar, pero no podemos garantizarlo.

2. Abre una terminal y ve al directorio del proyecto. Por ejemplo:

   cd /home/user/myproject

3. Asegúrate de que Allure Report esté instalado. Si no lo está, sigue las instrucciones de instalación. Ten en cuenta que Allure Report requiere Java.

4. Instala el adaptador Allure Cypress.

   npm

   npm install --save-dev allure-cypress

   yarn

   yarn add --dev allure-cypress

   pnpm

   pnpm install --dev allure-cypress

5. En la sección e2e de tu script de configuración de Cypress, define una función setupNodeEvents() que llame a allureCypress(), como se muestra en el ejemplo.

   Pasa las opciones de configuración si es necesario; consulta Configuración de Allure Cypress.

   import { allureCypress } from "allure-cypress/reporter";
   
   export default {
     e2e: {
       setupNodeEvents(on, config) {
         allureCypress(on, config, {
           resultsDir: "allure-results",
         });
         return config;
       },
     },
   };

   TIP

   Si usas controladores de eventos personalizados o complementos de terceros para Cypress que puedan depender del manejo de eventos, sigue las recomendaciones en Uso de Allure Cypress con controladores de eventos personalizados o Uso de Allure Cypress con otros complementos de Cypress.

6. En tu archivo de soporte de E2E, importa la biblioteca de Allure Cypress.

   import "allure-cypress";

2. Ejecuta las pruebas

Ejecuta tus pruebas de Cypress de la misma manera que lo harías normalmente. Por ejemplo:

npm

npx cypress run

yarn

yarn run cypress run

pnpm

pnpx cypress run

Esto guardará los datos necesarios en el directorio allure-results u otro, según la configuración. Si el directorio ya existe, los nuevos archivos se añadirán a los existentes, de modo que un informe futuro se basará en todos ellos.

3. Genera un informe

Finalmente, ejecuta Allure para convertir los resultados de las pruebas en un informe HTML. Esto abrirá automáticamente tu navegador para ver el informe.

allure serve allure-results

Si es necesario, reemplaza allure-results con la ruta al directorio especificado en la configuración.

Hay algunas opciones que pueden afectar cómo se genera el informe. Ejecuta allure --help para ver la lista completa de opciones.

Escribiendo pruebas

El adaptador Allure Cypress amplía las funciones estándar de generación de informes de Cypress al proporcionar capacidades adicionales para crear pruebas más informativas y estructuradas. Esta sección resalta las mejoras clave que se pueden utilizar:

• Anotación de Metadatos: Mejora los informes de prueba con descripciones, enlaces y otros metadatos.
• Organización de Pruebas: Estructura tus pruebas en jerarquías claras para una mejor legibilidad y organización organizar pruebas.
• División en Pasos: Divide las pruebas en pasos más pequeños para facilitar su comprensión y mantenimiento.
• Pruebas Parametrizadas: Describe claramente los parámetros para pruebas parametrizadas para especificar diferentes escenarios.
• Configura etiquetas globalmente: Usa variables de entorno para establecer metadatos y otras etiquetas.
• Adjuntos: Captura automáticamente capturas de pantalla y otros archivos durante la ejecución de las pruebas.
• Selección de Pruebas: Usa un archivo de plan de pruebas para seleccionar qué pruebas ejecutar, permitiendo una ejecución flexible.
• Detalles del Entorno: Incluye información detallada del entorno junto con el informe de prueba.

En la mayoría de los casos, Allure Cypress ofrece dos formas diferentes de usar una función: la API de Runtime y la API de Metadatos.

• API de Runtime: utiliza las funciones de Allure para agregar ciertos datos al resultado de la prueba durante su ejecución. Este enfoque permite construir los datos dinámicamente.

  Ten en cuenta que se recomienda llamar a las funciones de Allure lo más cerca posible del inicio de la prueba. De esta manera, los datos se agregarán incluso si la prueba falla al principio.

• API de Metadatos: agrega una etiqueta de metadatos (que comienza con @) en el nombre de la prueba. Allure Cypress la extraerá y actualizará los datos del resultado de la prueba en consecuencia. Al usar este enfoque, se garantiza que los datos se agreguen independientemente de cómo se ejecute la prueba.

Agregar metadatos

Allure te permite enriquecer tus informes con una variedad de metadatos. Esta información adicional proporciona contexto y detalles para cada prueba, mejorando la utilidad del informe. Consulta la sección de referencia de metadatos para obtener una lista exhaustiva de lo que se puede agregar.

Runtime API

import * as allure from "allure-js-commons";

it("Authentication", () => {
  allure.description("This test attempts to log into the website.");
  allure.displayName("Test Authentication");
  allure.owner("John Doe");
  allure.tags("Web interface", "Authentication");
  allure.severity("critical");
  // ...
});

Metadata API

it(
  "Authentication" +
    " @allure.label.owner:JohnDoe" +
    " @allure.label.tag:WebInterface" +
    " @allure.label.tag:Authentication" +
    " @allure.label.severity:critical",
  () => {
    // ...
  },
);

Organizar pruebas

Como se describe en Mejorando la navegación en tu informe de pruebas, Allure admite múltiples formas de organizar las pruebas en estructuras jerárquicas.

Para especificar la ubicación de una prueba en la jerarquía basada en comportamiento:

Runtime API

import * as allure from "allure-js-commons";

it("Authentication", () => {
  allure.epic("Web interface");
  allure.feature("Essential features");
  allure.story("Authentication");
  // ...
});

Metadata API

it(
  "Authentication" +
    " @allure.label.epic:WebInterface" +
    " @allure.label.feature:EssentialFeatures" +
    " @allure.label.story:Authentication",
  () => {
    // ...
  },
);

Para especificar la ubicación de una prueba en la jerarquía basada en suites:

Runtime API

import * as allure from "allure-js-commons";

it("Authentication", () => {
  allure.parentSuite("Tests for web interface");
  allure.suite("Tests for essential features");
  allure.subSuite("Tests for authentication");
  // ...
});

Metadata API

it(
  "Authentication" +
    " @allure.label.parentSuite:TestsForWebInterface" +
    " @allure.label.suite:TestsForEssentialFeatures" +
    " @allure.label.subSuite:TestsForAuthentication",
  () => {
    // ...
  },
);

Dividir una prueba en pasos

Para crear pasos y sub-pasos, puedes usar la función step(), consulta la referencia.

import * as allure from "allure-js-commons";
import { Status } from "allure-js-commons";

it("Authentication", () => {
  allure.step("Step 1", () => {
    allure.step("Sub-step 1", (ctx) => {
      ctx.parameter("foo", "1");
      // ...
    });
    allure.step("Sub-step 2", (ctx) => {
      ctx.parameter("foo", "2");
      // ...
    });
  });
  allure.logStep("Step 2", Status.SKIPPED);
});

Describir pruebas parametrizadas

Una forma típica de implementar el patrón de pruebas parametrizadas en Cypress es definir la prueba en un bucle y usar la variable del bucle en el título y el cuerpo de la prueba.

Para mostrar un valor de parámetro en el informe de pruebas, pásalo a la función parameter().

import * as allure from "allure-js-commons";

for (const login of ["johndoe", "[email protected]"]) {
  it(`Authentication as ${login}`, () => {
    allure.parameter("login", login);
    allure.parameter("time", new Date().toUTCString(), { excluded: true });
    // ...
  });
}

Configurar etiquetas globalmente

Cualquier etiqueta, incluidas las personalizadas, se puede configurar mediante variables de entorno en tu sistema operativo. Aquí tienes un ejemplo (suponiendo que usas el administrador de paquetes npm):

MacOS/Linux

export ALLURE_LABEL_epic=WebInterface
npx cypress run

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
npx cypress run

Adjuntar capturas de pantalla y otros archivos

En los informes de Allure, tienes la capacidad de adjuntar varios tipos de archivos, lo que puede mejorar significativamente la comprensión del informe. Una práctica común es adjuntar capturas de pantalla que capturen el estado de la interfaz de usuario en momentos específicos durante la ejecución de las pruebas.

Si tu prueba llama a cy.screenshot() o si la grabación de video está habilitada en la configuración de Cypress, las imágenes y los archivos de video resultantes se adjuntarán automáticamente a los resultados de la prueba.

Es posible adjuntar otros archivos utilizando las funciones allure.attachment() y allure.attachmentPath(), consulta la referencia.

import * as allure from "allure-js-commons";
import { ContentType } from "allure-js-commons";

it("Authentication", () => {
  // ...

  allure.attachment("Text file", "This is the file content.", ContentType.TEXT);

  allure.attachmentPath("Screenshot", "/path/to/image.png", {
    contentType: ContentType.PNG,
    fileExtension: "png",
  });
});

Seleccionar pruebas mediante un archivo de plan de pruebas

WARNING

Para que esta función funcione, asegúrate de que el objeto config se pase de Cypress a Allure Cypress, como se muestra en el ejemplo de configuración.

Si la variable de entorno ALLURE_TESTPLAN_PATH está definida y apunta a un archivo existente, Cypress solo ejecutará las pruebas enumeradas en este archivo.

Aquí tienes un ejemplo de cómo ejecutar pruebas según un archivo llamado testplan.json (suponiendo que uses el administrador de paquetes npm):

MacOS/Linux

export ALLURE_TESTPLAN_PATH=testplan.json
npx cypress run

Windows

$Env:ALLURE_TESTPLAN_PATH = "testplan.json"
npx cypress run

Información del entorno

Para la página principal del informe, puedes recopilar información diversa sobre el entorno en el que se ejecutaron las pruebas. Para hacerlo, edita el objeto environmentInfo en la configuración.

Por ejemplo, es una buena idea usar esto para recordar la versión del sistema operativo y la versión de Node.js obtenidas de los objetos os y process. Esto puede ayudar a futuros lectores a investigar errores reproducibles solo en algunos entornos.

import { allureCypress } from "allure-cypress/reporter";
import * as os from "node:os";

export default {
  e2e: {
    setupNodeEvents(on, config) {
      allureCypress(on, config, {
        environmentInfo: {
          os_platform: os.platform(),
          os_release: os.release(),
          os_version: os.version(),
          node_version: process.version,
        },
      });
      return config;
    },
  },
};

Ten en cuenta que si tu ejecución incluye múltiples ejecuciones de Cypress (consulta Cómo funciona), Allure Cypress solo guardará la información del entorno de la última ejecución.