Primeros pasos con Allure Bun

Genera hermosos reportes HTML usando Allure Report y tus pruebas de Bun.

INFO

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

Configuración

1. Prepara tu proyecto {#_1-prepare-your-project}

1. Asegúrate de que Bun esté instalado.

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 Bun:

   npm

   npm install --save-dev allure-bun allure-js-commons

   yarn

   yarn add --dev allure-bun allure-js-commons

   pnpm

   pnpm install --dev allure-bun allure-js-commons

   bun

   bun add --dev allure-bun allure-js-commons

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

5. Agrega la entrada de precarga a tu bunfig.toml:

   [test]
   preload = ["allure-bun/setup"]

   Esto registra la integración antes de que se carguen los archivos de prueba. Los archivos de prueba en sí no necesitan ningún cambio — sigue usando bun:test como de costumbre.

   Opcionalmente, especifica resultsDir y otras opciones. Consulta la configuración de Allure Bun para más detalles.

2. Ejecutar pruebas {#_2-run-tests}

Ejecuta tus pruebas de Bun de la misma manera que lo harías normalmente:

bun test

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

WARNING

Ejecutar pruebas con --concurrent o --randomize no está soportado. Allure Bun fallará rápido con un error descriptivo si se detecta cualquiera de estos indicadores.

Todos los modificadores estándar de bun:test funcionan como de costumbre: .skip, .todo, .if(), .skipIf(), .todoIf() y .each() — tanto en test como en describe; además de .failing y .serial solo en test. Dos excepciones: test.concurrent lanza un error, y .only (tanto en test como en describe) no está soportado — provoca el mismo error de orden de cola descrito en la advertencia a continuación.

3. Generar un reporte {#_3-generate-a-report}

Finalmente, convierte los resultados de prueba en un reporte HTML. Esto se puede hacer 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, luego abre automáticamente la página principal del reporte en un navegador web.

Escribir pruebas

La integración de Allure Bun extiende las funciones de reporte estándar de Bun proporcionando capacidades adicionales para elaborar pruebas más informativas y estructuradas. Esta sección destaca las mejoras clave que se pueden utilizar:

• Anotación de metadatos: Enriquece los reportes de prueba con descripciones, enlaces y otros metadatos.
• Organización de pruebas: Estructura tus pruebas en jerarquías claras para mejor 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 para especificar diferentes escenarios.
• Establecer etiquetas globalmente: Usa variables de entorno para establecer metadatos y otras etiquetas.
• Adjuntos: Captura archivos y otro contenido 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 de pruebas flexible.
• Detalles del entorno: Incluye información completa del entorno junto con el reporte de pruebas.

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

Limitación conocida: usa siempre describe()

Coloca siempre las pruebas dentro de bloques describe(). Mezclar llamadas test() a nivel raíz con bloques describe() en el mismo archivo produce el error allure-bun does not support concurrent tests. Esta es una limitación conocida: Bun difiere los callbacks de describe(), lo que hace que la cola de registro de allure-bun diverja del orden de ejecución — el mismo mecanismo de orden que usa para evitar la ejecución concurrente de pruebas. test.skip y test.todo están exentos. Los archivos que contienen solo pruebas a nivel raíz sin bloques describe() tampoco se ven afectados.

• 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 de forma dinámica.

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

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

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 obtener una lista exhaustiva de lo que se puede agregar.

Runtime API

import * as allure from "allure-js-commons";
import { describe, test } from "bun:test";

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

Metadata API

import { describe, test } from "bun:test";

describe("authentication", () => {
  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 admite 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:

Runtime API

import * as allure from "allure-js-commons";
import { describe, test } from "bun:test";

describe("authentication", () => {
  test("Test Authentication", async () => {
    await allure.epic("Web interface");
    await allure.feature("Authentication");
    await allure.story("Login with username");
    // ...
  });
});

Metadata API

import { describe, test } from "bun:test";

describe("authentication", () => {
  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 suites:

Runtime API

import * as allure from "allure-js-commons";
import { describe, test } from "bun:test";

describe("authentication", () => {
  test("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

import { describe, test } from "bun:test";

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

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 { describe, test } from "bun:test";

describe("authentication", () => {
  test("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

El test.each() incorporado de Bun hace que sea sencillo implementar el patrón de pruebas parametrizadas. Cada fila de la tabla se trata como una ejecución de prueba separada por Allure Report.

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

Using test()

import * as allure from "allure-js-commons";
import { describe, test } from "bun:test";

describe("authentication", () => {
  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 });
      // ...
    });
  }
});

Using test.each()

import * as allure from "allure-js-commons";
import { describe, test } from "bun:test";

describe("authentication", () => {
  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 });
    // ...
  });
});

Establecer etiquetas globalmente

Cualquier etiqueta, incluidas las personalizadas, se puede establecer mediante variables de entorno en tu sistema operativo. A continuación se muestra un ejemplo:

MacOS/Linux

export ALLURE_LABEL_epic=WebInterface
bun test

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
bun test

Adjuntar archivos

En los reportes de Allure, tienes la capacidad de adjuntar varios tipos de archivos, lo que puede mejorar enormemente la comprensibilidad del reporte.

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

import * as allure from "allure-js-commons";
import { ContentType } from "allure-js-commons";
import { describe, test } from "bun:test";

describe("authentication", () => {
  test("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, Bun solo ejecutará las pruebas listadas en este archivo.

A continuación se muestra un ejemplo de ejecución de pruebas según un archivo llamado testplan.json:

MacOS/Linux

export ALLURE_TESTPLAN_PATH=testplan.json
bun test

Windows

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

Información del entorno

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

Por ejemplo, es una buena idea registrar la versión del sistema operativo y la versión del runtime de Bun. Esto puede ayudar al lector futuro a investigar errores que solo son reproducibles en algunos entornos.

// preload.ts
import type { ReporterConfig } from "allure-js-commons/sdk/reporter";
import * as os from "node:os";

globalThis.allureBunConfig = {
  environmentInfo: {
    os_platform: os.platform(),
    os_release: os.release(),
    os_version: os.version(),
    bun_version: Bun.version,
  },
} satisfies ReporterConfig;

await import("allure-bun/setup");

# bunfig.toml
[test]
preload = ["./preload.ts"]