Allure Vitest reference
These are the functions that you can use to integrate your Vitest tests with Allure.
The signatures of the functions depend on whether you included the Allure's setup file in your vitest.config.ts
file (see Prepare your project).
With the Allure's setup file included, the functions are available without explicit import statements. All the functions accept the arguments according to this reference.
Without the Allure's setup file, you have to import the
allure
namespace manually. When calling a function, you have to pass the Vitest's test context as the first argument.
For example:
Metadata
Assign a test's description, links and other metadata.
Title
allure.displayName(name: string): Promise<void>
Set the test's title.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.displayName("Test Authentication!");
// ...
});
Description
allure.description(markdown: string): Promise<void>
Set the test's description. Markdown formatting is allowed. Any HTML formatting, if present, will be stripped for security purposes.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.description(
"This test attempts to log into the website using a login and a password. Fails if any error happens.\n\nNote that this test does not test 2-Factor Authentication.",
);
// ...
});
Owner
allure.owner(owner: string): Promise<void>
Set the test's owner.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.owner("John Doe");
// ...
});
Tag
allure.tag(tag: string): Promise<void>
Set the test's tags.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.tag("web interface");
await allure.tag("authentication");
// ...
});
Severity
allure.severity(severity: string): Promise<void>
Set the test's severity.
Allowed values are: “trivial”, “minor”, “normal”, “critical”, and “blocker”.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.severity("critical");
// ...
});
Label
allure.label(name: string, value: string): Promise<void>
Set an arbitrary label for the test. This is the underlying implementation for a lot of Allure's other functions.
The first argument of the function is the label name. It can be any string.
You can call label()
multiple times to create an array of values under the given name.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.label("my custom label", "value");
// ...
});
ID
allure.id(allureId: string): Promise<void>
Set the test's ID.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.allureId("123");
// ...
});
Link
allure.link(type: string, url: string, name?: string): Promise<void>
allure.issue(name: string, url: string): Promise<void>
allure.tms(name: string, url: string): Promise<void>
Add a link related to the test.
Based on the type
(which can be any string), Allure will try to load a corresponding link pattern to process the URL, as defined by the links
configuration option. If no pattern found for the given type, the URL is left unmodified.
If the URL does not start with “http” or “https”, it will be processed according to the links
configuration option.
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
.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.link("link", "https://example.com/", "Project website");
await allure.issue("Related issue", "AUTH-123");
await allure.tms("Related TMS issue", "TMS-456");
// ...
});
Behavior-based hierarchy
allure.epic(epic: string): Promise<void>
allure.feature(feature: string): Promise<void>
allure.story(story: string): Promise<void>
Assign names of epics, features or user stories for a test, as part of Allure's behavior-based hierarchy.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.epic("Web interface");
await allure.feature("Essential features");
await allure.story("Authentication");
// ...
});
Suite-based hierarchy
allure.parentSuite(name: string): Promise<void>
allure.suite(name: string): Promise<void>
allure.subSuite(name: string): Promise<void>
Assign the names of parent suite, suite or sub-suite for a test, as part of Allure's suite-based hierarchy.
TypeScriptimport { 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");
// ...
});
Test steps
allure.step(name: string, body: (step?: AllureCommandStepExecutable) => void): Promise<void>: Promise<void>
Define a test step or sub-step with the given name
.
The step()
function is asynchronous, and it accepts an asynchronous anonymous function as its second argument. Notice the async
and await
keywords in the example below.
TypeScriptimport { test } from "vitest";
test("Test Authentication", async () => {
await allure.step("Step 1", async () => {
await allure.step("Sub-step 1", async () => {
// ...
});
await allure.step("Sub-step 2", async () => {
// ...
});
});
await allure.step("Step 2", async () => {
// ...
});
});
Parametrized tests
allure.parameter(name: string, value: any, options?: ParameterOptions): Promise<void>
The parametrized tests pattern in Vitest can be implemented by calling the test.each()
function or even just by running a simple test()
inside a loop. In both cases, 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 one in the history. This argument is only used by Allure TestOps.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, however, that it is still possible to extract the value from theallure_results
directory if you publish it.
Attachments
allure.attachment: (name: string, content: Buffer | string, type: string): Promise<void>
Add content
as an attachment to the test result. The content can be a text string or a base64-encoded Buffer
.
You can use data produced by any function, not necessarily read from an actual file.
To ensure that the reader's web browser will display attachments correctly, pass the appropriate MIME type of the content as type
.
TypeScriptimport { test } from "vitest";
import * as fs from "fs";
test("Test Authentication", async () => {
await allure.attachment("Screenshot", fs.readFileSync("/path/to/image.png"), "image/png");
// ...
});