Referencia del Test Runner de Node.js de Allure
Estas son las funciones que puedes usar para integrar tus pruebas del test runner de Node.js con Allure.
En la mayoría de los casos, Allure Node.js Test Runner ofrece dos formas diferentes de usar una funcionalidad: la API de Runtime y la API de Metadatos.
API de Runtime: utiliza 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 comienza con
@) en el nombre de la prueba. La integración la extraerá y actualizará los datos del resultado de prueba en consecuencia. Al usar este enfoque, se garantiza que los datos se agreguen independientemente de cómo se ejecute la prueba.
Requisitos de la API de Runtime
La API de Runtime solo funciona cuando las pruebas se ejecutan con el preload --import allure-node-test/setup en Node.js 26.1 o posterior. Sin el preload, las llamadas a la API de Runtime muestran una advertencia y no tienen efecto en el reporte (los cuerpos de las llamadas a step() siguen ejecutándose). La API de Metadatos funciona en cualquier versión de Node.js soportada (20 o posterior), incluyendo el modo solo reporter. Consulta Requisitos de versión de Node.js.
API síncrona
Todas las funciones en esta referencia son asincrónicas y devuelven un PromiseLike. Si tu prueba utiliza helpers síncronos o integraciones de matchers que no soportan async, importa desde allure-js-commons/sync en su lugar:
import * as allure from "allure-js-commons/sync";
import test from "node:test";
test("Test Authentication", () => {
allure.step("check result", () => {
allure.parameter("mode", "sync");
});
});La fachada sync es estrictamente síncrona: step() debe completarse de forma síncrona y no debe devolver un Promise.
Metadatos
Asigna la descripción, enlaces y otros metadatos de una prueba.
Título
allure.displayName(name: string): PromiseLike<void>
Establece el nombre para mostrar de la prueba.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.displayName("Test Authentication!");
// ...
});Descripción
allure.description(markdown: string): PromiseLike<void>allure.descriptionHtml(html: string): PromiseLike<void>
Establece la descripción de la prueba.
Usa description() para contenido en Markdown. Cualquier formato HTML, si está presente, será eliminado por motivos de seguridad.
Usa descriptionHtml() cuando necesites proporcionar HTML sin procesar directamente en lugar de Markdown.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.description("Esta prueba intenta iniciar sesión en el sitio web.");
// ...
});Propietario
allure.owner(name: string): PromiseLike<void>@allure.label.owner:⟨VALUE⟩
Establece el propietario de la prueba.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.owner("John Doe");
// ...
});import test from "node:test";
test("Test Authentication @allure.label.owner:JohnDoe", async () => {
// ...
});Tag
allure.tag(name: string): PromiseLike<void>allure.tags(...tagsList: string[]): PromiseLike<void>@allure.label.tag:⟨VALUE⟩
Establece los tags de la prueba.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.tag("New UI");
await allure.tags("Essentials", "Authentication");
// ...
});import test from "node:test";
test("Test Authentication @allure.label.tag:WebInterface @allure.label.tag:Authentication", async () => {
// ...
});Además, si la versión de Node.js en ejecución soporta tags nativos de prueba, también se reportan como tags de Allure.
Severidad
allure.severity(name: string): PromiseLike<void>@allure.label.severity:⟨VALUE⟩
Establece la severidad de la prueba.
Los valores permitidos son: "trivial", "minor", "normal", "critical" y "blocker".
import * as allure from "allure-js-commons";
import { Severity } from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.severity(Severity.CRITICAL);
// ...
});import test from "node:test";
test("Test Authentication @allure.label.severity:critical", async () => {
// ...
});Etiqueta
allure.label(name: LabelName | string, value: string): PromiseLike<void>allure.labels(...labelsList: Label[]): PromiseLike<void>@allure.label.⟨NAME⟩:⟨VALUE⟩
Establece una etiqueta arbitraria para la prueba. Esta es la implementación base de muchas otras funciones de Allure.
Puedes llamar a label() varias veces para crear un array de valores bajo el mismo nombre.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.label("microservice", "UI");
// ...
});import test from "node:test";
test("Test Authentication @allure.label.microservice:UI", async () => {
// ...
});ID
allure.allureId(value: string): PromiseLike<void>@allure.id:⟨VALUE⟩
Establece el ID de la prueba.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.allureId("123");
// ...
});import test from "node:test";
test("Test Authentication @allure.id:123", async () => {
// ...
});ID de historial
allure.historyId(value: string): PromiseLike<void>
Sobrescribe el valor que Allure Report utiliza para encontrar la misma prueba en el historial. Úsalo si el valor calculado automáticamente a partir del nombre completo de la prueba y sus parámetros no se ajusta a tus necesidades.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.historyId("auth-test-1");
// ...
});ID de caso de prueba
allure.testCaseId(value: string): PromiseLike<void>
Sobrescribe el valor que Allure Report utiliza para reconocer resultados como pertenecientes al mismo caso de prueba, por ejemplo, al agrupar reintentos.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.testCaseId("auth-test-case-1");
// ...
});Enlace
allure.link(url: string, name?: string, type?: LinkType | string): PromiseLike<void>allure.links(...linksList: Link[]): PromiseLike<void>allure.issue(url: string, name?: string): PromiseLike<void>allure.tms(url: string, name?: string): PromiseLike<void>@allure.link.⟨TYPE⟩:⟨VALUE⟩
Agrega un enlace relacionado con la prueba.
Si el url no es una URL completa (por ejemplo, solo es un identificador de issue), Allure intentará construir la dirección completa a partir de una plantilla de enlace que corresponde al type (que puede ser cualquier string y por defecto es "link"), según lo definido por la opción de configuración links. Si no se encuentra una plantilla para el tipo dado, o el valor ya es una URL completa, se deja sin modificar.
El name se usará como el texto del enlace. Si se omite, se usará la URL en su lugar.
Por conveniencia, Allure proporciona dos funciones abreviadas con tipos de enlace preseleccionados: issue y tms.
import * as allure from "allure-js-commons";
import test from "node:test";
test("Test Authentication", async () => {
await allure.issue("AUTH-123", "Issue relacionado");
await allure.tms("TMS-456", "Issue TMS relacionado");
await allure.link("JIRA-777", "Issue Jira relacionado", "jira");
await allure.link("https://example.com/", "Sitio web del proyecto");
// ...
});import test from "node:test";
test("Test Authentication @allure.link.issue:AUTH-123 @allure.link.tms:TMS-456", async () => {
// ...
});Jerarquía basada en comportamiento
allure.epic(name: string): PromiseLike<void>allure.feature(name: string): PromiseLike<void>allure.story(name: string): PromiseLike<void>@allure.label.epic:⟨VALUE⟩@allure.label.feature:⟨VALUE⟩@allure.label.story:⟨VALUE⟩
Asigna nombres de epics, features o historias de usuario a una prueba, como parte de la jerarquía basada en comportamiento de Allure.
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");
// ...
});import test from "node:test";
test(
"Test Authentication" +
" @allure.label.epic:WebInterface" +
" @allure.label.feature:EssentialFeatures" +
" @allure.label.story:Authentication",
async () => {
// ...
},
);Jerarquía basada en suite
allure.parentSuite(name: string): PromiseLike<void>allure.suite(name: string): PromiseLike<void>allure.subSuite(name: string): PromiseLike<void>@allure.label.parentSuite:⟨VALUE⟩@allure.label.suite:⟨VALUE⟩@allure.label.subSuite:⟨VALUE⟩
Asigna los nombres de parent suite, suite o sub-suite a una prueba, como parte de la jerarquía basada en suite de Allure.
Esto sobrescribe los niveles correspondientes de la jerarquía de suites por defecto, que Allure Node.js Test Runner crea en base a los argumentos de describe().
import * as allure from "allure-js-commons";
import { describe, it } from "node:test";
describe("authentication", () => {
it("Test Authentication", async () => {
await allure.parentSuite("Pruebas para la interfaz web");
await allure.suite("Pruebas para funcionalidades esenciales");
await allure.subSuite("Pruebas para autenticación");
// ...
});
});import { describe, it } from "node:test";
describe("authentication", () => {
it(
"Test Authentication" +
" @allure.label.parentSuite:TestsForWebInterface" +
" @allure.label.suite:TestsForEssentialFeatures" +
" @allure.label.subSuite:TestsForAuthentication",
async () => {
// ...
},
);
});Pasos de prueba
allure.step<T = void>(name: string, body: (context: StepContext) => T | PromiseLike<T>): PromiseLike<T>allure.logStep(name: string, status?: Status, error?: Error): PromiseLike<void>
Define un paso o subpaso de prueba con el name dado.
La función step() acepta una función anónima como segundo argumento, que puede ser síncrona o asincrónica. La función anónima puede aceptar ningún argumento o un solo argumento de tipo StepContext. Este objeto proporciona los siguientes métodos:
displayName()— sobrescribe el nombre del paso durante su ejecución.parameter(name: string, value: string, mode?: "default" | "masked" | "hidden")— indica parámetros arbitrarios usados para el paso. El tercer argumento opcional establece el modo de visualización del parámetro, consulta Pruebas parametrizadas. Los parámetros de paso no soportan la opciónexcluded.
Para crear un paso sin cuerpo, llama a la función logStep() que acepta un nombre y un estado de paso opcional.
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);
});Ten en cuenta que los pasos de Allure son diferentes de los subtests nativos t.test(): un subtest se reporta como un resultado de prueba separado, mientras que un paso es parte del resultado de su prueba.
Pruebas parametrizadas
allure.parameter(name: string, value: string, options?: ParameterOptions): PromiseLike<void>
El patrón de pruebas parametrizadas en el test runner de Node.js puede implementarse ejecutando un test() dentro de un bucle. Allure Report reconoce cada iteración como una ejecución de prueba separada.
Los valores que distinguen una iteración de otra se llaman parámetros de prueba. Para mostrar el valor de un parámetro en el reporte de pruebas, pásalo a la función parameter().
El argumento options, si se proporciona, debe ser un objeto con dos propiedades opcionales: excluded y mode.
Si
excludedse establece entrue, Allure no usará el parámetro al comparar el resultado de prueba actual con los anteriores en el historial. Consulta Error común: los reintentos de una prueba se muestran como pruebas separadas.El
modeafecta cómo se mostrará el parámetro en el reporte. Las opciones disponibles son:"default"(igual que no especificar ningún modo) — el parámetro y su valor se mostrarán en una tabla junto con otros parámetros."masked"— el parámetro se mostrará en la tabla, pero su valor estará oculto. Usa este modo para contraseñas, tokens y otros parámetros sensibles."hidden"— el parámetro y su valor no se mostrarán en el reporte de pruebas.
Ten en cuenta que incluso cuando uses el modo
"masked"o"hidden", aún es posible extraer el valor desde el directorioallure-resultssi lo publicas.
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 });
// ...
});
}Adjuntos
allure.attachment(name: string, content: Buffer | Uint8Array | string, options: ContentType | string | AttachmentOptions): PromiseLike<void>allure.attachmentPath(name: string, path: string, options: ContentType | string | Omit<AttachmentOptions, "encoding">): PromiseLike<void>
Agrega un adjunto al resultado de prueba bajo el name dado. Pasa el content directamente o el path desde el cual se leerán los datos.
El argumento options controla el tipo de medio del contenido y la extensión de archivo que se usará si un usuario descarga el adjunto desde el reporte de pruebas. Puedes especificar ambas opciones en un objeto (como se muestra para el adjunto de imagen abajo) o solo especificar el tipo de medio y dejar que Allure deduzca la extensión de archivo apropiada automáticamente (como se muestra para el adjunto de texto abajo). En cualquier caso, el tipo de medio puede ser un valor de la enumeración ContentType o cualquier string.
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",
});
});Para agregar un adjunto a la ejecución de prueba completa en lugar del resultado de la prueba actual, utiliza las variantes globales de las funciones. Aceptan los mismos argumentos:
allure.globalAttachment(name: string, content: Buffer | Uint8Array | string, options: ContentType | string | AttachmentOptions): PromiseLike<void>allure.globalAttachmentPath(name: string, path: string, options: ContentType | string | Omit<AttachmentOptions, "encoding">): PromiseLike<void>
De manera similar, puedes reportar un error que se relacione con la ejecución de prueba completa en lugar de con una prueba en particular:
allure.globalError(details: StatusDetails): PromiseLike<void>
El objeto details puede contener un string message y un string trace.
Además, la integración crea algunos adjuntos automáticamente:
- todo lo que una prueba escribe en la salida estándar y el flujo de error estándar se adjunta como "stdout" y "stderr";
- los mensajes registrados con el
t.diagnostic()incorporado se adjuntan como "diagnostics"; - la salida que no puede atribuirse a una prueba en particular se adjunta a la ejecución de prueba completa.