Allure Cucumber.js reference

These are the functions that you can use to integrate your Cucumber.js tests with Allure.

In most cases, Allure Cucumber.js provides two different ways to use a feature: the Runtime API and the Gherkin tags.

• 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 the 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.

• Gherkin tags: add a Gherkin tag of a specific format (may be configured via the labels and links options). When using this approach, the data is guaranteed to be added regardless of how the test itself runs.

Metadata

Assign a test's description, links and other metadata.

Description

• allure.description(markdown: string): PromiseLike<void>

Set the test's description. Markdown formatting is allowed. Any HTML formatting, if present, will be stripped for security purposes.

Alternatively, use the native Gherkin syntax for describing scenarios.

Runtime API

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

Then("do something", async () => {
  await allure.description("This test attempts to log into the website.");
  // ...
});

Gherkin description

Feature: MyFeature

  Scenario: MyTest
  This test attempts to log into the website.

    When something should be done
    Then do something

Owner

• allure.owner(name: string): PromiseLike<void>
• @allure.label.owner:⟨VALUE⟩

Set the test's owner.

Runtime API

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

Then("do something", async () => {
  await allure.owner("John Doe");
  // ...
});

Gherkin tags

Feature: MyFeature

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

Tag

• allure.tag(name: string): PromiseLike<void>
• allure.tags(...tagsList: string[]): PromiseLike<void>
• @⟨VALUE⟩

Set the test's tags.

Alternatively, use the native Gherkin syntax for tags.

Runtime API

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

Then("do something", async () => {
  await allure.tag("New UI");
  await allure.tags("Essentials", "Authentication");
  // ...
});

Gherkin tags

Feature: MyFeature

  @NewUI
  @Essentials
  @Authentication
  Scenario: MyTest
    When something should be done
    Then do something

Severity

• allure.severity(name: string): PromiseLike<void>
• @allure.label.severity:⟨VALUE⟩

Set the test's severity.

Allowed values are: “trivial”, “minor”, “normal”, “critical”, and “blocker”.

Runtime API

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

Then("do something", async () => {
  await allure.severity(Severity.CRITICAL);
  // ...
});

Gherkin tags

Feature: MyFeature

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

Label

• allure.label(name: LabelName | string, value: string): PromiseLike<void>
• allure.labels(...labelsList: Label[]): PromiseLike<void>

Set an arbitrary label for the test. This is the underlying implementation for a lot of Allure's other functions.

You can call label() multiple times to create an array of values under the given name.

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

Then("do something", async () => {
  await allure.label("microservice", "UI");
  // ...
});

ID

• @allure.id:⟨VALUE⟩

Set the test's ID.

Feature: MyFeature

  @allure.id:123
  Scenario: MyTest
    When something should be done
    Then do something

Link

• 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>

Add a link related to the test.

Based on the type (which can be any string, defaults to “link”), Allure will try to load a corresponding link template to process the URL, as defined by the links configuration option. If no template is found for the given type or if the link already represents a proper URL, it's 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.

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

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

Behavior-based hierarchy

• 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⟩

Assign names of epics, features, or user stories for a test, as part of Allure's behavior-based hierarchy.

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

Suite-based hierarchy

• 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⟩

Assign the names of parent suite, suite, or sub-suite for a test, as part of Allure's suite-based hierarchy.

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

Test steps

• 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 a test 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.

The anonymous function can accept either no arguments or a single argument of class StepContext. This object provides the following methods:

• displayName() — override the sub-step name during its execution.
• parameter() — indicate arbitrary parameters used for the sub-step. The available signatures of this method are similar to the test-wide implementation, see Parametrized tests.

To create a step without a body, call the logStep() function that accepts a name and, optionally, a step status and an error object.

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);
});

Parametrized tests

• allure.parameter(name: string, value: string, options?: ParameterOptions): PromiseLike<void>

Specify a name and value of a parameter that was used during this test. See Parametrized tests for more details.

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 the previous one in the history. See Common pitfall: a test's 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.

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

Then("do something", async () => {
  await allure.parameter("login", "johndoe");
  await allure.parameter("time", new Date().toUTCString(), { excluded: true });
  // ...
});

Attachments

• allure.attachment(name: string, content: Buffer | string, options: ContentType | string | AttachmentOptions): PromiseLike<void>
• allure.attachmentPath(name: string, path: string, options: ContentType | string | Omit<AttachmentOptions, "encoding">): PromiseLike<void>

Add an attachment to the test result under the given name. Pass either the content or the path from which the data will be read.

Additional options may be passed in an object as the third parameter.

• The contentType and fileExtension options control the 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 or just specify the contentType type and let Allure deduce the appropriate fileExtension automatically. In either case, the media type can be a value from the ContentType enumeration or any string.

• The encoding option specifies how the attached text should be saved. It only applies when providing content as a string, and it defaults to “utf-8”.

If the third argument is not an object, it is interpreted as a single contentType option.

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",
  });
});