Allure Cypress reference

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

In most cases, Allure Cypress provides two different ways to use a feature: the Metadata API and the Runtime API.

• Metadata API: add a special command (beginning with @) into the test name. Allure Cypress 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.

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

Metadata

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

Description

• allure.description(markdown: string)

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

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.description("This test attempts to log into the website.");
  // ...
});

Owner

• allure.owner(name: string)

Set the test's owner.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.owner("John Doe");
  // ...
});

TypeScript
it("Authentication @allure.label.owner=JohnDoe", () => {
  // ...
});

Tag

• allure.tag(name: string)

Set the test's tags.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.tag("Web interface");
  allure.tag("Authentication");
  // ...
});

TypeScript
it("Authentication @allure.label.tag=WebInterface @allure.label.tag=Authentication", () => {
  // ...
});

Severity

• allure.severity(name: string)

Set the test's severity.

The value must be a constant from the Severity class.

TypeScript
import * as allure from "allure-cypress";
import { Severity } from "allure-js-commons";

it("Authentication", () => {
  allure.severity(Severity.CRITICAL);
  // ...
});

TypeScript
it("Authentication @allure.label.severity=critical", () => {
  // ...
});

Label

• allure.label(name: string, value: string)

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.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.label("MyCustomLabel", "value");
  // ...
});

TypeScript
it("Authentication @allure.label.MyCustomLabel=value", () => {
  // ...
});

ID

• allure.allureId(value: string)

Set the test's ID.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.allureId("123");
  // ...
});

TypeScript
it("Authentication @allure.id=123", () => {
  // ...
});

Link

• allure.link(url: string, name?: string, type?: string)
• allure.issue(url: string, name?: string)
• allure.tms(url: string, name?: string)

Add a link related to the test.

The type affects the icon that is displayed next to the link in the test report. For convenience, Allure provides two shorthand functions with pre-selected link types: issue and tms.

The name will be used as the link's text. If it is omitted, the url will be used instead.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.link("https://dev.example.com/", "Website");
  allure.issue("AUTH-123");
  allure.tms("TMS-456");
  // ...
});

Behavior-based hierarchy

• allure.epic(name: string)
• allure.feature(name: string)
• allure.story(name: string)

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

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.epic("Web interface");
  allure.feature("Essential features");
  allure.story("Authentication");
  // ...
});

TypeScript
it(
  "Authentication" +
    " @allure.label.epic=WebInterface" +
    " @allure.label.feature=EssentialFeatures" +
    " @allure.label.story=Authentication",
  () => {
    // ...
  },
);

Suite-based hierarchy

• allure.parentSuite(name: string)
• allure.suite(name: string)
• allure.subSuite(name: string)

Assign the name of suite, as part of Allure's suite-based hierarchy.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.parentSuite("Tests for web interface");
  allure.suite("Tests for essential features");
  allure.subSuite("Tests for authentication");
  // ...
});

TypeScript
it(
  "Authentication" +
    " @allure.label.parentSuite=WebInterface" +
    " @allure.label.suite=EssentialFeatures" +
    " @allure.label.subSuite=Authentication",
  () => {
    // ...
  },
);

Test steps

• allure.step(name: string, body: () => void)

Define a test step with the given name.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  allure.step("Step 1", () => {
    allure.step("Sub-step 1", () => {
      // ...
    });

    allure.step("Sub-step 2", () => {
      // ...
    });
  });

  allure.step("Step 2", () => {
    // ...
  });
});

Parametrized tests

• allure.parameter(name: string, value: string, options?: ParameterOptions)

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 previous one in the history. This argument is used by the history-related features and 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 the allure_results directory if you publish it.

TypeScript
import * as allure from "allure-cypress";

for (const login of ["johndoe", "[email protected]"]) {
  it("Authentication", () => {
    allure.parameter("login", login);
    allure.parameter("time", new Date().toUTCString(), { excluded: true });
    // ...
  });
}

Attachments

• allure.attachment(name: string, content: Cypress.Buffer | string, type?: string, encoding?: BufferEncoding)

Add an attachment under the given name to the test result.

The content can be a text string or a Cypress.Buffer. You can use data produced by any function, not necessarily read from an actual file.

For reading an actual file, we recommend using Cypress's cy.readFile() and then passing its result to allure.attachment()..

To ensure that the reader's web browser will display attachments correctly, pass the appropriate MIME type of the content as type. The ContentType class contains some popular MIME types, or you can use a custom string, as long as it will be understood by the web browser when viewing the test report.

The encoding argument (defaults to “utf-8”) specifies how a text content should be encoded. It is ignored when attaching a buffer.

TypeScript
import * as allure from "allure-cypress";

it("Authentication", () => {
  // ...
  cy.readFile("/path/to/image.png", null).then((file) => {
    allure.attachment("My image", file, "image/png");
  });
});

When you make a screenshot using cy.screenshot(), Allure Cypress automatically adds it as an attachment to the test report. No additional commands are necessary.