Introducción a Allure Cucumber.js

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

INFO

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

Configuración

1. Prepara tu proyecto

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

   Allure Cucumber.js se ha probado con Node.js 18 y versiones posteriores. Las versiones más antiguas pueden funcionar, pero no lo podemos garantizar.

2. Abre un terminal y dirígete al directorio de tu 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 Cucumber.js y asegúrate de que todos los paquetes necesarios estén instalados.

   npm

   npm install --save-dev @cucumber/cucumber @cucumber/messages allure-cucumberjs

   yarn

   yarn add --dev @cucumber/cucumber @cucumber/messages allure-cucumberjs allure-js-commons

   pnpm

   pnpm install --dev @cucumber/cucumber @cucumber/messages allure-cucumberjs

5. Habilita el formateador de Allure para Cucumber.js. Consulta la Configuración para más detalles y opciones.

   export default {
     format: ["allure-cucumberjs/reporter"],
     formatOptions: {
       resultsDir: "allure-results",
     },
   };

   WARNING

   En Yarn PnP, la configuración no funcionará con los ajustes predeterminados. Consulta una nota para usuarios de Yarn PnP.

6. Escribe tus pruebas, siguiendo la documentación oficial de Cucumber.js y, opcionalmente, utilizando algunas características extendidas proporcionadas por Allure Cucumber.js. Consulta Escribir pruebas.

2. Ejecuta las pruebas

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

npm

npx cucumber-js

yarn

yarn run cucumber-js

pnpm

pnpx cucumber-js

Esto guardará los datos necesarios en el directorio allure-results u otro especificado, 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 al directorio especificado en la configuración.

Hay 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 Cucumber.js amplía las características estándar de informes de Cucumber.js al proporcionar capacidades adicionales para crear pruebas más informativas y estructuradas. Esta sección destaca las principales mejoras que puedes utilizar:

• Anotación de metadatos: Mejora los informes de prueba con descripciones, enlaces y otros metadatos.
• Organización de pruebas: Estructura tus pruebas en jerarquías claras para una mejor legibilidad y organización organiza pruebas.
• División en pasos: Divide las pruebas en pasos 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.
• Configurar 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 pruebas.
• Detalles del entorno: Incluye información completa del entorno para acompañar el informe de pruebas.

En la mayoría de los casos, Allure Cucumber.js proporciona dos formas diferentes de utilizar una función: la API Runtime y las etiquetas Gherkin.

• API Runtime: Usa las funciones de Allure para agregar ciertos datos al resultado de la prueba durante su ejecución. Este enfoque permite construir los datos de manera 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.

• Etiquetas Gherkin: Agrega una etiqueta Gherkin con un formato específico (puede configurarse a través de las opciones labels y links). Al usar este enfoque, los datos se garantizan independientemente de 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 una lista exhaustiva de lo que se puede agregar.

Runtime API

import { Then } from "@cucumber/cucumber";
import * as allure from "allure-js-commons";

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

Gherkin tags

Feature: MyFeature

  @allure.label.owner:JohnDoe
  @allure.label.severity:critical
  @WebInterface
  @Authentication
  Scenario: MyTest
    When something should be done
    Then do something

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 { Then } from "@cucumber/cucumber";
import * as allure from "allure-js-commons";

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

Gherkin tags

Feature: MyFeature

  @allure.label.epic:WebInterface
  @allure.label.feature:EssentialFeatures
  @allure.label.story:Authentication
  Scenario: MyTest
    When something should be done
    Then do something

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

Runtime API

import { Then } from "@cucumber/cucumber";
import * as allure from "allure-js-commons";

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

Gherkin tags

Feature: MyFeature

  @allure.label.parentSuite:TestsForWebInterface
  @allure.label.suite:TestsForEssentialFeatures
  @allure.label.subSuite:TestsForAuthentication
  Scenario: MyTest
    When something should be done
    Then do something

Divide una prueba en pasos

Allure Cucumber.js te permite crear sub-pasos dentro de un paso de prueba en Gherkin. Para hacerlo, utiliza la función allure.step().

Los sub-pasos son útiles en situaciones en las que tienes una secuencia de acciones que es:

• lo suficientemente monolítica como para presentarse como un solo paso en un archivo Gherkin;
• lo suficientemente compleja como para tener múltiples puntos potenciales de falla.

import { Then } from "@cucumber/cucumber";
import * as allure from "allure-js-commons";
import { Status } from "allure-js-commons";

Then("do something", 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);
});

Describe pruebas parametrizadas

Con Cucumber.js, puedes implementar el patrón de pruebas parametrizadas utilizando las palabras clave Scenario Outline y Examples.

Existen dos enfoques para indicar qué parámetros se utilizaron en una prueba:

• Utilizar la sintaxis de los corchetes angulares para insertar los valores de los parámetros directamente en el título de un paso.
• Utilizar allure.parameter() para mostrar los valores a nivel de la prueba.

En el siguiente ejemplo:

1. El bloque Examples define dos valores para la variable login: “johndoe” y “[email protected]”.
2. Para cada valor, Cucumber.js lo utiliza en lugar del marcador de posición en el título del escenario y en los títulos de los pasos, por ejemplo, authorize as "johndoe".
3. Luego, Cucumber.js usa el título para seleccionar y ejecutar la función de JavaScript. El valor (por ejemplo, “johndoe”) se pasa a la función como un argumento de tipo string.
4. La función llama a allure.parameter() para mostrar los valores a nivel de la prueba en el informe.

Scenario Outline: test authorization as "<login>"
  Then authorize as "<login>"

  Examples:
    | login               |
    | johndoe             |
    | [email protected] |

import { Then } from "@cucumber/cucumber";
import * as allure from "allure-js-commons";

Then(`authorize as {string}`, async (login) => {
  await allure.parameter("auth_method", "password");
  await allure.parameter("login", login);
  // ...
});

Establecer etiquetas globalmente

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

MacOS/Linux

export ALLURE_LABEL_epic=WebInterface
npx cucumber-js

Windows

$Env:ALLURE_LABEL_epic = "WebInterface"
npx cucumber-js

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

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

import { Then } from "@cucumber/cucumber";
import * as allure from "allure-js-commons";
import { ContentType } from "allure-js-commons";

Then("do something", 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, Cucumber.js 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 gestor de paquetes npm):

MacOS/Linux

export ALLURE_TESTPLAN_PATH=testplan.json
npx cucumber-js

Windows

$Env:ALLURE_TESTPLAN_PATH = "testplan.json"
npx cucumber-js

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

import * as os from "node:os";
import * as process from "node:process";

export default {
  format: ["allure-cucumberjs/reporter"],
  formatOptions: {
    environmentInfo: {
      os_platform: os.platform(),
      os_release: os.release(),
      os_version: os.version(),
      node_version: process.version,
    },
  },
};

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