Primeros pasos con Allure Node.js Test Runner

Genera reportes HTML atractivos usando Allure Report y tus pruebas de Node.js test runner (node:test).

Configuración

1. Prepara tu proyecto

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

   La funcionalidad completa, incluyendo la API de Runtime con los imports de node:test sin cambios, requiere Node.js 26.1 o posterior. En versiones anteriores de Node.js, comenzando desde Node.js 20, la integración funciona solo en modo de reporter; consulta la nota de versión abajo.

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 la integración de Allure Node.js Test Runner:

   npm

   npm install --save-dev allure-node-test allure-js-commons

   yarn

   yarn add --dev allure-node-test allure-js-commons

   pnpm

   pnpm add -D allure-node-test allure-js-commons

   Mantén allure-node-test y allure-js-commons en la misma versión.

   No se necesitan archivos de configuración — la integración se activa completamente desde la línea de comandos cuando ejecutas las pruebas. Tus archivos de prueba no requieren ningún cambio — sigue usando node:test como de costumbre.

2. Ejecuta pruebas

Ejecuta tus pruebas de Node.js con el reporter de Allure y el preload de setup:

node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter

Las dos opciones de línea de comandos cumplen roles diferentes:

• --test-reporter allure-node-test/reporter recopila eventos de prueba y escribe los archivos de resultados de Allure. Esta es la única parte obligatoria.
• --import allure-node-test/setup habilita la API de Runtime (llamadas a allure-js-commons dentro de las pruebas) y el filtrado por plan de pruebas. Sin esto, las llamadas a la API de Runtime muestran una advertencia y no afectan el reporte (los cuerpos de las llamadas a step() siguen ejecutándose).

Para mayor comodidad, agrega los comandos como scripts en tu package.json:

{
  "scripts": {
    "test:allure": "node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter"
  }
}

Esto guardará los datos necesarios en allure-results o en otro directorio, según la configuración. Si el directorio ya existe, se agregarán nuevos archivos a los existentes para que un futuro reporte se base en todos ellos.

Requisitos de versión de Node.js

WARNING

El preload allure-node-test/setup requiere Node.js 26.1 o posterior y falla rápidamente con un error descriptivo en versiones anteriores. En versiones anteriores de Node.js (20 o posterior), ejecuta el reporter sin el preload:

node --test --test-reporter allure-node-test/reporter

En este modo solo de reporter, solo la API de Runtime y el filtrado por plan de pruebas no están disponibles. Todo lo demás sigue funcionando: los estados de las pruebas, la API de metadatos (tags en los nombres de prueba), jerarquías de suites, adjuntos automáticos de salida y todas las opciones de configuración.

Hay una excepción: cuando la variable de entorno ALLURE_TESTPLAN_PATH apunta a un archivo de plan de pruebas, el preload puede usarse incluso en versiones de Node.js anteriores a 26.1. En ese caso, solo filtra la ejecución de pruebas; las llamadas a la API de Runtime siguen requiriendo Node.js 26.1 o posterior.

Mantener la salida de consola

Cuando se especifica un reporter personalizado, Node.js ya no imprime su salida de consola predeterminada. Para mantener un reporter de consola junto a Allure, lista varios reporters y asigna a cada uno un destino:

node --test \
  --test-reporter spec --test-reporter-destination stdout \
  --test-reporter allure-node-test/reporter --test-reporter-destination stdout

El reporter de Allure escribe sus datos en el directorio de resultados y no imprime nada, por lo que el valor de destino no tiene efecto visible — solo se requiere porque Node.js espera un destino por cada reporter.

3. Genera un reporte

Finalmente, convierte los resultados de prueba en un reporte HTML. Esto puede hacerse con uno de dos comandos:

• allure generate procesa los resultados de prueba y guarda un reporte HTML en el directorio allure-report. Para ver el reporte, usa el comando allure open.

• allure serve crea el mismo reporte que allure generate, y luego abre automáticamente la página principal del reporte en un navegador web.

Escribir pruebas

La integración de Allure Node.js Test Runner amplía las funciones estándar de reporte del test runner de Node.js proporcionando capacidades adicionales para crear pruebas más informativas y estructuradas. Esta sección destaca las mejoras clave que puedes utilizar:

• Anotación de metadatos: Enriquecer los reportes de prueba con descripciones, enlaces y otros metadatos.
• Organización de pruebas: Estructura tus pruebas en jerarquías claras para mejorar la legibilidad y organización, consulta organizar pruebas.
• División en pasos: Divide las pruebas en pasos de prueba más pequeños para facilitar la comprensión y el mantenimiento.
• Pruebas parametrizadas: Describe claramente los parámetros para pruebas parametrizadas y especifica diferentes escenarios.
• Establecer etiquetas globalmente: Usa variables de entorno para establecer metadatos y otras etiquetas.
• Adjuntos: Captura archivos y otros contenidos durante la ejecución de 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 completa del entorno para acompañar el reporte de prueba.

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

• API de Runtime: usa las funciones de Allure para agregar ciertos datos al resultado de 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. Así, los datos se agregarán incluso si la prueba falla temprano.

  La API de Runtime requiere ejecutar con --import allure-node-test/setup en Node.js 26.1 o posterior.

• API de Metadatos: agrega un tag de metadatos (que comienza con @) en el nombre de la prueba. La integración lo extraerá y actualizará los datos del resultado de prueba en consecuencia. Al usar este enfoque, los datos se agregan siempre, independientemente de cómo se ejecute la prueba. La API de Metadatos funciona en cualquier versión de Node.js soportada (20 o posterior), incluyendo el modo solo de reporter.

Tus archivos de prueba mantienen sus imports nativos — allure-js-commons solo se usa para las funciones de reporte:

import { label, step } from "allure-js-commons";
import assert from "node:assert/strict";
import test from "node:test";

test("signing in", async () => {
  await label("severity", "critical");
  await step("submit form", async () => {});

  assert.equal(1 + 1, 2);
});

Se soportan todas las formas habituales de organizar pruebas con node:test: las suites describe() se mapean a etiquetas de suite de Allure, y los subtests nativos t.test() se reportan como resultados de prueba separados.

Otras funciones estándar de node:test se reportan como se espera:

• Las pruebas marcadas con skip o todo aparecen en el reporte como Omitido.
• Si un hook nativo before(), beforeEach(), afterEach() o after() falla, el hook fallido se conserva en el reporte como un fixture adjunto a las pruebas afectadas, y la falla también se registra como un error de la ejecución de prueba en general. Las pruebas canceladas por un hook before() fallido aparecen como Omitido, una falla en un hook beforeEach() o afterEach() se reporta como el propio estado de la prueba afectada, y un hook after() fallido cambia los estados de las pruebas en su suite solo si la falla del hook es más severa que sus propios resultados.

Agregar metadatos

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

API de Runtime

import * as allure from "allure-js-commons";
import test from "node:test";

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

API de Metadatos

import test from "node:test";

test(
  "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 Mejorar la navegación en tu reporte de pruebas, Allure soporta múltiples formas de organizar pruebas en estructuras jerárquicas.

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

API de Runtime

import * as allure from "allure-js-commons";
import test from "node:test";

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

API de Metadatos

import test from "node:test";

test(
  "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 suite:

API de Runtime

import * as allure from "allure-js-commons";
import test from "node:test";

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

API de Metadatos

import test from "node:test";

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

Por defecto, la jerarquía de suite se construye a partir de los bloques describe() en los que está anidada la prueba. Para los subtests nativos t.test(), el nombre de la prueba padre también se usa como etiqueta de suite. Las etiquetas de suite establecidas mediante la API de Runtime o la API de Metadatos sobrescriben las generadas automáticamente.

Dividir una prueba en pasos

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

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

test("Test Authentication", async () => {
  await allure.step("Paso 1", async () => {
    await allure.step("Subpaso 1", async (ctx) => {
      await ctx.parameter("foo", "1");
      // ...
    });
    await allure.step("Subpaso 2", async (ctx) => {
      await ctx.parameter("foo", "2");
      // ...
    });
  });
  await allure.logStep("Paso 2", Status.SKIPPED);
});

Describir pruebas parametrizadas

Para implementar el patrón de pruebas parametrizadas con el test runner de Node.js, escribe la prueba dentro de un bucle y usa los parámetros variables tanto en el título como en el cuerpo. Cada iteración se trata como una ejecución de prueba separada por Allure Report.

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

import * as allure from "allure-js-commons";
import test from "node:test";

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

Establecer etiquetas globalmente

Cualquier etiqueta, incluyendo las personalizadas, puede establecerse mediante variables de entorno en tu sistema operativo. Aquí tienes un ejemplo:

MacOS/Linux

export ALLURE_LABEL_epic=WebInterface
node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter

Adjuntar archivos

En los reportes de Allure, tienes la capacidad de adjuntar varios tipos de archivos, lo que puede mejorar considerablemente la comprensión del reporte.

Para instrucciones detalladas sobre cómo implementar adjuntos, consulta la sección de adjuntos en la referencia de Allure Node.js Test Runner.

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

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

  await allure.attachment("Archivo de texto", "Este es el contenido del archivo.", ContentType.TEXT);

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

Además, todo lo que se escriba en la salida estándar o el flujo de error estándar durante una ejecución de prueba se captura y se agrega como adjuntos de texto llamados "stdout" y "stderr", y los mensajes registrados con el t.diagnostic() incorporado se agregan como un adjunto de texto llamado "diagnostics". Estos adjuntos se agregan a la ejecución de prueba en general y no a pruebas individuales, porque Node.js actualmente no incluye un identificador de prueba en sus eventos de salida.

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, solo se ejecutarán las pruebas listadas en ese archivo.

El filtrado por plan de pruebas requiere el preload --import allure-node-test/setup: omite las pruebas fuera del plan antes de que se ejecute su cuerpo, y esos omitidos no aparecen en el reporte. En modo solo de reporter (sin el preload), el plan de pruebas no se aplica — si las pruebas se ejecutan, se reportan.

Cuando ALLURE_TESTPLAN_PATH está configurado, el preload puede usarse incluso en versiones de Node.js anteriores a 26.1: solo filtra la ejecución de pruebas, mientras que las llamadas a la API de Runtime siguen requiriendo Node.js 26.1 o posterior.

Aquí tienes un ejemplo de ejecución de pruebas según un archivo llamado testplan.json:

MacOS/Linux

export ALLURE_TESTPLAN_PATH=testplan.json
node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter

Windows

$Env:ALLURE_TESTPLAN_PATH = "testplan.json"
node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter

Ten en cuenta que los subtests nativos t.test() solo existen mientras su prueba padre se está ejecutando, por lo que no pueden filtrarse individualmente. Si un selector de plan de pruebas apunta a un subtest, la prueba padre se ejecuta completa, y cada prueba y subtest que realmente se ejecuta se reporta. Para que esto funcione, una entrada de plan de pruebas que apunte a un subtest debe incluir un selector, no solo un Allure ID.

Información del entorno

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

Por ejemplo, es buena idea registrar la versión del sistema operativo y la versión de Node.js. Esto puede ayudar al lector futuro a investigar errores que solo se reproducen en ciertos entornos.

MacOS/Linux

export ALLURE_NODE_TEST_CONFIG='{"environmentInfo":{"os_platform":"linux","node_version":"26.1.0"}}'
node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter

Windows

$Env:ALLURE_NODE_TEST_CONFIG = '{"environmentInfo":{"os_platform":"windows","node_version":"26.1.0"}}'
node --test --import allure-node-test/setup --test-reporter allure-node-test/reporter