--- title: Node.js Test Runner reference description: Reference documentation for Allure Node.js Test Runner integration | How to add sub-steps and additional metadata | Create attachments | Organise tests --- # Allure Node.js Test Runner reference These are the functions that you can use to integrate your Node.js test runner tests with Allure. In most cases, Allure Node.js Test Runner provides two different ways to use a feature: the Runtime API and the Metadata API. - **Runtime API**: use Allure's functions to add certain data to the test result during its execution. This approach allows for constructing the data dynamically. Note that it is recommended to call Allure's functions as close to the beginning of the test as possible. This way, the data will be added even if the test fails early. - **Metadata API**: add a metadata tag (beginning with `@`) into the test name. The integration will extract it and update the test result's data accordingly. When using this approach, the data is guaranteed to be added regardless of how the test itself runs. Warning: Runtime API requirements The Runtime API only works when the tests are run with the `--import allure-node-test/setup` preload on Node.js 26.1 or later. Without the preload, Runtime API calls print a warning and have no effect on the report (the bodies of `step()` calls still run). The Metadata API works on any supported Node.js version (20 or later), including the reporter-only mode. See [Node.js version requirements](/docs/node-test/#node-js-version-requirements). ## Sync API All functions in this reference are asynchronous and return a `PromiseLike`. If your test uses synchronous helpers or matcher integrations that do not support async, import from `allure-js-commons/sync` instead: ```js import * as allure from "allure-js-commons/sync"; import test from "node:test"; test("Test Authentication", () => { allure.step("check result", () => { allure.parameter("mode", "sync"); }); }); ``` The sync facade is strict-sync only: `step()` must complete synchronously and must not return a `Promise`. ## Metadata Assign a test's [description, links and other metadata](/docs/v2/readability/#description-links-and-other-metadata). ### Title - `allure.displayName(name: string): PromiseLike` Set the test's [title](/docs/v2/readability/#title). ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.displayName("Test Authentication!"); // ... }); ``` ### Description - `allure.description(markdown: string): PromiseLike` - `allure.descriptionHtml(html: string): PromiseLike` Set the test's [description](/docs/v2/readability/#description). Use `description()` for Markdown content. Any HTML formatting, if present, will be stripped for security purposes. Use `descriptionHtml()` when you need to supply raw HTML directly instead of Markdown. ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.description("This test attempts to log into the website."); // ... }); ``` ### Owner - `allure.owner(name: string): PromiseLike` - `@allure.label.owner:⟨VALUE⟩` Set the test's [owner](/docs/v2/readability/#owner). **Runtime API:** ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.owner("John Doe"); // ... }); ``` **Metadata API:** ```js import test from "node:test"; test("Test Authentication @allure.label.owner:JohnDoe", async () => { // ... }); ``` ### Tag - `allure.tag(name: string): PromiseLike` - `allure.tags(...tagsList: string[]): PromiseLike` - `@allure.label.tag:⟨VALUE⟩` Set the test's [tags](/docs/v2/readability/#tags). **Runtime API:** ```js 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"); // ... }); ``` **Metadata API:** ```js import test from "node:test"; test("Test Authentication @allure.label.tag:WebInterface @allure.label.tag:Authentication", async () => { // ... }); ``` Additionally, if the running Node.js version supports native test tags, they are reported as Allure tags as well. ### Severity - `allure.severity(name: string): PromiseLike` - `@allure.label.severity:⟨VALUE⟩` Set the test's [severity](/docs/v2/readability/#severity). Allowed values are: `"trivial"`, `"minor"`, `"normal"`, `"critical"`, and `"blocker"`. **Runtime API:** ```js 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); // ... }); ``` **Metadata API:** ```js import test from "node:test"; test("Test Authentication @allure.label.severity:critical", async () => { // ... }); ``` ### Label - `allure.label(name: LabelName | string, value: string): PromiseLike` - `allure.labels(...labelsList: Label[]): PromiseLike` - `@allure.label.⟨NAME⟩:⟨VALUE⟩` Set an arbitrary [label](/docs/v2/readability/#other-labels) for the test. This is the underlying implementation for many of Allure's other functions. You can call `label()` multiple times to create an array of values under the given name. **Runtime API:** ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.label("microservice", "UI"); // ... }); ``` **Metadata API:** ```js import test from "node:test"; test("Test Authentication @allure.label.microservice:UI", async () => { // ... }); ``` ### ID - `allure.allureId(value: string): PromiseLike` - `@allure.id:⟨VALUE⟩` Set the test's [ID](/docs/v2/readability/#id). **Runtime API:** ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.allureId("123"); // ... }); ``` **Metadata API:** ```js import test from "node:test"; test("Test Authentication @allure.id:123", async () => { // ... }); ``` ### History ID - `allure.historyId(value: string): PromiseLike` Override the value that Allure Report uses to find the same test in the [history](/docs/history-and-retries/). Use it if the value computed automatically from the test's full name and parameters does not suit your needs. ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.historyId("auth-test-1"); // ... }); ``` ### Test case ID - `allure.testCaseId(value: string): PromiseLike` Override the value that Allure Report uses to recognize results as belonging to the same test case, for example, when grouping [retries](/docs/history-and-retries/). ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.testCaseId("auth-test-case-1"); // ... }); ``` ### Link - `allure.link(url: string, name?: string, type?: LinkType | string): PromiseLike` - `allure.links(...linksList: Link[]): PromiseLike` - `allure.issue(url: string, name?: string): PromiseLike` - `allure.tms(url: string, name?: string): PromiseLike` - `@allure.link.⟨TYPE⟩:⟨VALUE⟩` Add a [link](/docs/v2/readability/#links) related to the test. If the `url` is not a full URL (for example, it is just an issue identifier), Allure will try to construct the full address from a **link template** that corresponds to the `type` (which can be any string and defaults to `"link"`), as defined by the [`links`](/docs/node-test-configuration/#links) configuration option. If no template is found for the given type, or the value is already a full URL, it is left unmodified. The `name` will be used as the link's text. If it is omitted, the URL will be used instead. For convenience, Allure provides two shorthand functions with pre-selected link types: `issue` and `tms`. **Runtime API:** ```js import * as allure from "allure-js-commons"; import test from "node:test"; test("Test Authentication", async () => { await allure.issue("AUTH-123", "Related issue"); await allure.tms("TMS-456", "Related TMS issue"); await allure.link("JIRA-777", "Related Jira issue", "jira"); await allure.link("https://example.com/", "Project website"); // ... }); ``` **Metadata API:** ```js import test from "node:test"; test("Test Authentication @allure.link.issue:AUTH-123 @allure.link.tms:TMS-456", async () => { // ... }); ``` ## Behavior-based hierarchy - `allure.epic(name: string): PromiseLike` - `allure.feature(name: string): PromiseLike` - `allure.story(name: string): PromiseLike` - `@allure.label.epic:⟨VALUE⟩` - `@allure.label.feature:⟨VALUE⟩` - `@allure.label.story:⟨VALUE⟩` Assign names of **epics**, **features** or **user stories** for a test, as part of Allure's [behavior-based hierarchy](/docs/v2/navigation/#behavior-based-hierarchy). **Runtime API:** ```js 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"); // ... }); ``` **Metadata API:** ```js import test from "node:test"; test( "Test Authentication" + " @allure.label.epic:WebInterface" + " @allure.label.feature:EssentialFeatures" + " @allure.label.story:Authentication", async () => { // ... }, ); ``` ## Suite-based hierarchy - `allure.parentSuite(name: string): PromiseLike` - `allure.suite(name: string): PromiseLike` - `allure.subSuite(name: string): PromiseLike` - `@allure.label.parentSuite:⟨VALUE⟩` - `@allure.label.suite:⟨VALUE⟩` - `@allure.label.subSuite:⟨VALUE⟩` Assign the names of **parent suite**, **suite** or **sub-suite** for a test, as part of Allure's [suite-based hierarchy](/docs/v2/navigation/#suite-based-hierarchy). This overrides the corresponding levels of the default suites hierarchy, which Allure Node.js Test Runner creates based on the `describe()` arguments. **Runtime API:** ```js import * as allure from "allure-js-commons"; import { describe, it } from "node:test"; describe("authentication", () => { it("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:** ```js import { describe, it } from "node:test"; describe("authentication", () => { it( "Test Authentication" + " @allure.label.parentSuite:TestsForWebInterface" + " @allure.label.suite:TestsForEssentialFeatures" + " @allure.label.subSuite:TestsForAuthentication", async () => { // ... }, ); }); ``` ## Test steps - `allure.step(name: string, body: (context: StepContext) => T | PromiseLike): PromiseLike` - `allure.logStep(name: string, status?: Status, error?: Error): PromiseLike` Define a [test step or sub-step](/docs/steps/) with the given `name`. The `step()` function accepts an anonymous function as its second argument, which can be synchronous or asynchronous. The anonymous function can accept either no arguments or a single argument of type `StepContext`. This object provides the following methods: - `displayName()` — override the step name during its execution. - `parameter(name: string, value: string, mode?: "default" | "masked" | "hidden")` — indicate arbitrary parameters used for the step. The optional third argument sets the parameter's display mode, see [Parametrized tests](#parametrized-tests). Step parameters do not support the `excluded` option. To create a step without a body, call the `logStep()` function that accepts a name and an optional step status. ```js 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("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); }); ``` Note that Allure steps are different from native `t.test()` subtests: a subtest is reported as a separate test result, while a step is part of its test's result. ## Parametrized tests - `allure.parameter(name: string, value: string, options?: ParameterOptions): PromiseLike` The [parametrized tests](/docs/v2/readability/#parametrized-tests) pattern in the Node.js test runner can be implemented by running a `test()` inside a loop. Allure Report recognizes each iteration as a separate test run. The values that distinguish one iteration from another are called test parameters. To display a parameter value in the test report, pass it to the `parameter()` function. The `options` argument, if given, must be an object with two optional properties: `excluded` and `mode`. - If `excluded` is set to `true`, Allure will not use the parameter when comparing the current test result with previous ones in the history. See [Common pitfall: a test's retries are displayed as separate tests](/docs/history-and-retries/#common-pitfall-a-tests-retries-are-displayed-as-separate-tests). - The `mode` affects how the parameter will be displayed in the report. Available options are: - `"default"` (same as not specifying any mode) — the parameter and its value will be shown in a table along with other parameters. - `"masked"` — the parameter will be shown in the table, but its value will be hidden. Use this mode for passwords, tokens and other sensitive parameters. - `"hidden"` — the parameter and its value will not be shown in the test report. Note that even when you use the `"masked"` or `"hidden"` mode, it is still possible to extract the value from the `allure-results` directory if you publish it. ```js import * as allure from "allure-js-commons"; import test from "node:test"; for (const login of ["johndoe", "johndoe@example.com"]) { test(`Test Authentication as ${login}`, async () => { await allure.parameter("login", login); await allure.parameter("time", new Date().toUTCString(), { excluded: true }); // ... }); } ``` ## Attachments - `allure.attachment(name: string, content: Buffer | Uint8Array | string, options: ContentType | string | AttachmentOptions): PromiseLike` - `allure.attachmentPath(name: string, path: string, options: ContentType | string | Omit): PromiseLike` Add an [attachment](/docs/attachments/) to the test result under the given `name`. Pass either the `content` directly or the `path` from which the data will be read. The `options` argument controls the [media type](https://en.wikipedia.org/wiki/Media_type) of the content and the filename extension that will be used if a user downloads the attachment from the test report. You can either specify both options in an object (as shown for the image attachment below) or just specify the media type and let Allure deduce the appropriate filename extension automatically (as shown for the text attachment below). In either case, the media type can be a value from the `ContentType` enumeration or any string. ```js 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("Text file", "This is the file content.", ContentType.TEXT); await allure.attachmentPath("Screenshot", "/path/to/image.png", { contentType: ContentType.PNG, fileExtension: "png", }); }); ``` To add an attachment to the test run as a whole instead of the current test result, use the global variants of the functions. They accept the same arguments: - `allure.globalAttachment(name: string, content: Buffer | Uint8Array | string, options: ContentType | string | AttachmentOptions): PromiseLike` - `allure.globalAttachmentPath(name: string, path: string, options: ContentType | string | Omit): PromiseLike` Similarly, you can report an error that relates to the test run as a whole rather than to a particular test: - `allure.globalError(details: StatusDetails): PromiseLike` The `details` object may contain a `message` and a `trace` string. Additionally, the integration creates some attachments automatically: - everything a test writes to the standard output and the standard error stream is attached as "stdout" and "stderr"; - messages logged with the built-in `t.diagnostic()` are attached as "diagnostics"; - output that cannot be attributed to a particular test is attached to the test run as a whole.