Empezando con Allure Mocha

Genera hermosos informes HTML usando Allure Report y tus pruebas de Mocha.

INFO

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

Configuración

1. Prepara tu proyecto

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

   Allure Mocha está probado 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 Mocha y asegúrate de que el framework Mocha también esté listado en las dependencias del proyecto.

   npm

   npm install --save-dev mocha allure-mocha

   yarn

   yarn add --dev mocha allure-mocha allure-js-commons

   pnpm

   pnpm install --dev mocha allure-mocha

5. Establece allure-mocha como el reporter de Mocha y especifica el directorio de resultados. La forma exacta depende de cómo configures y ejecutes Mocha. Aquí tienes algunos ejemplos:

   runner.mjs

   import { glob } from "glob";
   import Mocha from "mocha";
   
   const mocha = new Mocha({
     reporter: "allure-mocha",
     reporterOptions: {
       resultsDir: "allure-results",
     },
   });
   
   glob.sync("test/**/*.spec.{m,c,}js").forEach((file) => mocha.addFile(file));
   await mocha.loadFilesAsync();
   mocha.run((failures) => process.exit(failures));

   .mocharc.json

   {
     "reporter": "allure-mocha",
     "reporterOptions": ["resultsDir=allure-results"]
   }

   CLI

   npx mocha -R allure-mocha -O "resultsDir=allure-results"

   TIP

   Si deseas mantener la salida por consola predeterminada, establece la opción del reporter extraReporters a spec. Consulta también la configuración de Allure Mocha.

2. Ejecuta las pruebas

Ejecuta tus pruebas de Mocha de la misma manera en que las ejecutarías normalmente. Por ejemplo:

npm

npx mocha

yarn

yarn run mocha

pnpm

pnpx mocha

O, si usas un script de ejecución (suponiendo que se llame runner.js):

npm, pnpm

node runner.js

yarn

yarn node runner.js

Esto guardará los datos necesarios en allure-results o en otro directorio, según la configuración. Si el directorio ya existe, los nuevos archivos se agregará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 del directorio especificado en la configuración.

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

Escribir pruebas

El adaptador Allure Mocha amplía las características estándar de informes de Mocha 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 las 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 de prueba más pequeños para una comprensión y mantenimiento más fáciles.
• Pruebas parametrizadas: Describe claramente los parámetros para pruebas parametrizadas para especificar diferentes escenarios.
• Establecer 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, lo que permite una ejecución de pruebas flexible.
• Detalles del entorno: Incluye información completa del entorno para acompañar el informe de la prueba.

En la mayoría de los casos, Allure Mocha proporciona dos formas diferentes de usar una característica: la API en tiempo de ejecución (Runtime API) y la API de Metadatos (Metadata API).

• API en tiempo de ejecución (Runtime API): usa 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 (Metadata API): agrega una etiqueta de metadatos (que comienza con @) en el nombre de la prueba. Allure Mocha la extraerá y actualizará los datos del resultado de la prueba en consecuencia. Al usar este enfoque, se garantiza que los datos se agreguen sin importar 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("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 Mocha es definir la prueba en un bucle y usar la variable del bucle en el título y cuerpo de la prueba.

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

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

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

Establecer etiquetas globalmente

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

MacOS/Linux

export ALLURE_LABEL_epic=WebInterface
npx mocha

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
npx mocha

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 considerablemente 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.

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

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 a través de un archivo de plan de pruebas

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

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

MacOS/Linux

export ALLURE_TESTPLAN_PATH=testplan.json
npx mocha

Windows

$Env:ALLURE_TESTPLAN_PATH = "testplan.json"
npx mocha

Información del entorno

Para 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 recordar la versión del sistema operativo y la versión de Node.js obtenidas de los objetos os y process. Esto puede ayudar al futuro lector a investigar errores que solo se reproducen en algunos entornos.

import { glob } from "glob";
import Mocha from "mocha";
import * as os from "node:os";

const mocha = new Mocha({
  reporter: "allure-mocha",
  reporterOptions: {
    environmentInfo: {
      os_platform: os.platform(),
      os_release: os.release(),
      os_version: os.version(),
      node_version: process.version,
    },
  },
});

glob.sync("test/**/*.spec.{m,c,}js").forEach((file) => mocha.addFile(file));
await mocha.loadFilesAsync();
mocha.run((failures) => process.exit(failures));

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