Introducción a Allure Jest

Genera hermosos informes HTML con Allure Report y tus pruebas de Jest. Se admiten tanto los entornos de Node.js como de jsdom.

La integración funciona con Jest 24.8 o superior. Sin embargo, depende del corredor Circus (que es el predeterminado en Jest 27 o superior). Si tu proyecto utiliza el corredor Jasmine y no puedes cambiar a Circus, utiliza la integración de Allure Jasmine en su lugar.

INFO

Consulta los proyectos de ejemplo en github.com/allure-examples para ver Allure Jest en acción.

Configuración

1. Prepara tu proyecto

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

   Allure Jest se prueba con Node.js 18 y superior. 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 Jest.

   npm

   npm install --save-dev allure-jest

   yarn

   yarn add --dev allure-jest allure-js-commons

   pnpm

   pnpm install --dev allure-jest

5. Allure Jest admite dos entornos de Jest: jest-environment-node y jest-environment-jsdom. Asegúrate de instalar el que planeas usar. Por ejemplo:

   npm

   npm install --save-dev jest-environment-node

   yarn

   yarn add --dev jest-environment-node

   pnpm

   pnpm install --dev jest-environment-node

   WARNING

   La versión del paquete jest-environment-node o jest-environment-jsdom debe coincidir con la versión del paquete jest, de lo contrario, la integración puede no funcionar.

   Si eres un usuario de Yarn PnP, no omitas este paso, incluso si usas jest-environment-node (que se instala automáticamente con Jest). De lo contrario, observarás el siguiente error:

   allure-jest intentó acceder a jest-environment-node (una dependencia de pares), pero tu aplicación no la proporciona; esto hace que la llamada require sea ambigua e inválida.

6. Si la versión de Jest es inferior a la 27, instala Circus y configura Jest para usarlo como el ejecutor de pruebas.

   npm

   npm install --save-dev jest-circus

   yarn

   yarn add --dev jest-circus

   pnpm

   pnpm install --dev jest-circus

   const config = {
     testRunner: "jest-circus/runner",
   };

   WARNING

   La versión del paquete jest-circus debe coincidir con la versión del paquete jest, de lo contrario, la integración puede no funcionar.

7. En el archivo de configuración de Jest, por ejemplo, jest.config.js, configura el entorno de prueba apropiado.

   For client-side tests

   const config = {
     testEnvironment: "allure-jest/jsdom",
   };

   For server-side tests

   const config = {
     testEnvironment: "allure-jest/node",
   };

2. Ejecuta las pruebas

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

npm

npm test

yarn

yarn test

pnpm

pnpm test

Esto guardará los datos necesarios en el directorio allure-results u otro, de acuerdo con la configuración. Si el directorio ya existe, los nuevos archivos se añadirán a los ya 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 visualizar el informe.

allure serve allure-results

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

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

Escribir pruebas

El adaptador Allure Jest amplía las características estándar de generación de informes de Jest proporcionando capacidades adicionales para crear pruebas más informativas y estructuradas. Esta sección destaca las mejoras clave que se pueden utilizar:

• Anotación de metadatos: Mejora los informes de pruebas 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 de pasos: Divide las pruebas en pasos de prueba 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.
• Establecer etiquetas globalmente: Utiliza 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 de pruebas flexible.
• Detalles del entorno: Incluye información completa del entorno para acompañar el informe de pruebas.

En la mayoría de los casos, Allure Jest proporciona dos formas diferentes de usar una función: la API de tiempo de ejecución y la API de metadatos.

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

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

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

Añadir 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 añadir.

Runtime API

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

it("Test Authentication", async () => {
  await allure.owner("John Doe");
  await allure.tags("Web interface", "Authentication");
  await allure.severity("critical");
  // ...
});

Metadata API

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

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 el comportamiento:

Runtime API

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

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

Metadata API

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

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("Test Authentication", async () => {
  await allure.parentSuite("Tests for web interface");
  await allure.suite("Tests for essential features");
  await allure.subSuite("Tests for authentication");
  // ...
});

Metadata API

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

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("Test Authentication", async () => {
  await allure.step("Step 1", async () => {
    await allure.step("Sub-step 1", async (ctx) => {
      await ctx.parameter("foo", "1");
      // ...
    });
    await allure.step("Sub-step 2", async (ctx) => {
      await ctx.parameter("foo", "2");
      // ...
    });
  });
  await allure.logStep("Step 2", Status.SKIPPED);
});

Describir pruebas parametrizadas

Una forma típica de implementar el patrón de pruebas parametrizadas en Jest es mediante la función test.each().

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";

test.each([["johndoe"], ["[email protected]"]])("Test Authentication as %s", async (login) => {
  await allure.parameter("login", login);
  await allure.parameter("time", new Date().toUTCString(), { excluded: true });
  // ...
});

Configurar etiquetas globalmente

Cualquier etiqueta, incluidas las personalizadas, se puede configurar a través de las variables de entorno en tu sistema operativo. Aquí tienes un ejemplo (asumiendo que usas el gestor de paquetes npm):

MacOS/Linux

export ALLURE_LABEL_epic=WebInterface
npm test

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
npm test

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 reflejen el estado de la interfaz de usuario en momentos específicos durante la ejecución de las pruebas.

Para obtener instrucciones detalladas sobre cómo implementar adjuntos, consulta la sección de adjuntos en la referencia de Allure Jest.

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

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

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

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

Seleccionar pruebas mediante un archivo de plan de pruebas

Si la variable de entorno ALLURE_TESTPLAN_PATH está definida y apunta a un archivo existente, Jest solo ejecutará las pruebas listadas en ese archivo.

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

MacOS/Linux

export ALLURE_TESTPLAN_PATH=testplan.json
npm test

Windows

$Env:ALLURE_TESTPLAN_PATH = "testplan.json"
npm test

Información del entorno

En la página principal del informe, puedes recopilar diversa información 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 registrar la versión del sistema operativo y la versión de Node.js obtenidas de los objetos os y process. Esto puede ayudar al lector futuro a investigar errores reproducibles solo en ciertos entornos.

import { Status } from "allure-js-commons";
import os from "node:os";

export default {
  testEnvironment: "allure-jest/node",
  testEnvironmentOptions: {
    environmentInfo: {
      os_platform: os.platform(),
      os_release: os.release(),
      os_version: os.version(),
      node_version: process.version,
    },
  },
};

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