Empezando con Allure Vitest

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

INFO

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

Configuración

1. Prepara tu proyecto

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

   Allure Vitest 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 la integración Allure Vitest y asegúrate de que todos los paquetes que necesita estén instalados.

   npm

   npm install --save-dev vitest @vitest/runner allure-vitest

   yarn

   yarn add --dev vitest @vitest/runner allure-vitest allure-js-commons

   pnpm

   pnpm install --dev vitest @vitest/runner allure-vitest

   WARNING

   Si ejecutas las pruebas y ves el error "no vitest context is detected", asegúrate de que los paquetes vitest y @vitest/runner estén ambos listados en las devDependencies de tu proyecto y tengan la misma versión.

   Si planeas ejecutar pruebas en un navegador real usando Vitest Browser Mode, instala también @vitest/browser y un proveedor de navegador. Allure Vitest es compatible con el proveedor de Playwright:

   npm

   npm install --save-dev @vitest/browser @vitest/browser-playwright playwright
   npx playwright install chromium

   yarn

   yarn add --dev @vitest/browser @vitest/browser-playwright playwright
   yarn playwright install chromium

   pnpm

   pnpm install --dev @vitest/browser @vitest/browser-playwright playwright
   pnpm playwright install chromium

5. Modifica tu archivo de configuración de Vitest, por ejemplo, vitest.config.ts.

   • En la lista de archivos de configuración, agrega "allure-vitest/setup" (para la mayoría de los administradores de paquetes) o require.resolve("allure-vitest/setup") (para Yarn PnP).

   • En la lista de reporteros, agrega "allure-vitest/reporter".

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

   Normal configuration

   import AllureReporter from "allure-vitest/reporter";
   import { defineConfig } from "vitest/config";
   
   export default defineConfig({
     test: {
       setupFiles: ["allure-vitest/setup"],
       reporters: [
         "verbose",
         [
           "allure-vitest/reporter",
           {
             resultsDir: "allure-results",
           },
         ],
       ],
     },
   });

   Configuration for Yarn PnP

   import AllureReporter from "allure-vitest/reporter";
   import { defineConfig } from "vitest/config";
   
   const require = createRequire(import.meta.url);
   
   export default defineConfig({
     test: {
       setupFiles: [require.resolve("allure-vitest/setup")],
       reporters: [
         "verbose",
         [
           "allure-vitest/reporter",
           {
             resultsDir: "allure-results",
           },
         ],
       ],
     },
   });

2. Ejecuta las pruebas

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

npm

npm test

yarn

yarn test

pnpm

pnpm 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 reporte futuro se base en todos ellos.

3. Genera un reporte

Finalmente, convierte los resultados de las pruebas en un reporte HTML. Esto se puede hacer con uno de dos comandos:

• allure generate procesa los resultados de las pruebas 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 Allure Vitest extiende las características estándar de reportes de Vitest al proporcionar capacidades adicionales para crear pruebas más informativas y estructuradas. Esta sección resalta las mejoras clave que pueden ser utilizadas:

• Anotación de Metadatos: Mejora los reportes 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 en 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 las 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, permitiendo una ejecución flexible de las pruebas.
• Detalles del Entorno: Incluye información completa del entorno para acompañar el reporte de la prueba.

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

• API en tiempo de ejecución: 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 temprano.

• API de metadatos: agrega una etiqueta de metadatos (comenzando con @) en el nombre de la prueba. Allure Vitest la extraerá y actualizará los datos del resultado de la prueba en consecuencia. Al usar este enfoque, 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 { test } from "vitest";

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 { test } from "vitest";

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 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";
import { test } from "vitest";

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

Metadata API

import { test } from "vitest";

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 { test } from "vitest";

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 { test } from "vitest";

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 sub-pasos, 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 "vitest";

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

Dado que las pruebas en Vitest, a diferencia de otros marcos, se escriben como funciones anónimas, es muy fácil implementar el patrón de pruebas parametrizadas, es decir, ejecutar la misma lógica de prueba con diferentes datos de prueba. Para hacerlo, simplemente escribe la prueba dentro de un bucle y usa los parámetros de la variable tanto en su título como en su cuerpo.

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

Using test()

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

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 { test } from "vitest";

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 las 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
npm test

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
npm test

Adjuntar capturas de pantalla y otros archivos

En los reportes de Allure, tienes la capacidad de adjuntar varios tipos de archivos, lo que puede mejorar significativamente la comprensión del reporte. 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 los adjuntos, consulta la sección de adjuntos en la referencia de Allure Vitest.

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

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, Vitest solo ejecutará las pruebas listadas 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
npm test

Windows

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

Información del entorno

En la página principal del reporte, 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 lector futuro a investigar errores que solo son reproducibles en algunos entornos.

import { createRequire } from "node:module";
import * as os from "node:os";
import { defineConfig } from "vitest/config";

const require = createRequire(import.meta.url);

export default defineConfig({
  test: {
    setupFiles: [require.resolve("allure-vitest/setup")],
    reporters: [
      "verbose",
      [
        "allure-vitest/reporter",
        {
          environmentInfo: {
            os_platform: os.platform(),
            os_release: os.release(),
            os_version: os.version(),
            node_version: process.version,
          },
        },
      ],
    ],
  },
});

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

Usar el modo navegador

Vitest Browser Mode ejecuta tus pruebas dentro de un navegador real en lugar de un entorno DOM simulado.

INFO

La compatibilidad con el modo navegador requiere Vitest 4 o posterior.

Para habilitar el modo navegador, agrega un bloque browser a tu configuración de Vitest. En Vitest 4, el proveedor de navegador se importa como una factory desde su propio paquete:

import { playwright } from "@vitest/browser-playwright";
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    setupFiles: ["allure-vitest/browser/setup"],
    reporters: [
      "verbose",
      [
        "allure-vitest/reporter",
        {
          resultsDir: "allure-results",
        },
      ],
    ],
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: "chromium" }],
    },
  },
});

WARNING

allure-vitest/browser/setup no es intercambiable con allure-vitest/setup. El archivo de configuración del navegador está diseñado para ejecutarse en un contexto de navegador y registra comandos adicionales requeridos para el filtrado del plan de pruebas. Si tu proyecto tiene tanto pruebas unitarias como pruebas de navegador, usa un archivo de configuración de Vitest separado para cada uno, apuntando al archivo de configuración apropiado.

Todas las características estándar de Allure Vitest — metadatos, pasos, adjuntos, etc. — funcionan de la misma manera en el modo navegador. Además, puedes capturar capturas de pantalla de la página del navegador y adjuntarlas al resultado de la prueba usando el objeto page de vitest/browser:

import * as allure from "allure-js-commons";
import { ContentType } from "allure-js-commons";
import { test } from "vitest";
import { page } from "vitest/browser";

test("Renders the login form", async () => {
  // ... renderizar e interactuar con la página ...

  const screenshotPath = await page.screenshot();
  await allure.attachmentPath("Page screenshot", screenshotPath, {
    contentType: ContentType.PNG,
    fileExtension: "png",
  });
});

Para más detalles sobre cómo adjuntar capturas de pantalla y otros archivos, consulta la sección de adjuntos en la referencia de Allure Vitest.