---
title: Allure CodeceptJS reference
description: Reference documentation for Allure CodeceptJS integration | Create attachments | Organise tests
---

# Allure CodeceptJS reference

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

In most cases, Allure CodeceptJS provides two different ways to use a feature: the Runtime API and the Tags 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 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.

- **Tags API**: use the [`tag()`](https://codecept.io/advanced/#tags) method to assign various data to a particular scenario.

  Most of the tags require values. You can use either a colon or an equal sign to separate the value from the name, e.g., `@allure.label.epic:WebInterface` is identical to `@allure.label.epic=WebInterface`.

  When using this approach, the data is guaranteed to be added to the test result regardless of how the test itself runs.

## Metadata

Assign a test's [description, links and other metadata](/docs/v2/readability/#description-links-and-other-metadata).

### Description

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

Set the test's [description](/docs/v2/readability/#description). Markdown formatting is allowed. Any HTML formatting, if present, will be stripped for security purposes.

```js
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.description("This test attempts to log into the website.");
  // ...
});
```

### Owner

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

Set the test's [owner](/docs/v2/readability/#owner).

**Runtime API:**
```js
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.owner("John Doe");
  // ...
});
```

**Tags API:**
```js
Feature("Test My Website");

Scenario("Test Authentication", async () => {
  // ...
}).tag("@allure.label.owner:JohnDoe");
```

### Tag

- `allure.tag(name: string): PromiseLike<void>`
- `allure.tags(...tagsList: string[]): PromiseLike<void>`

Set the test's [tags](/docs/v2/readability/#tags).

**Runtime API:**
```js
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.tags("Web interface", "Authentication");
  // ...
});
```

**Tags API:**
```js
Feature("Test My Website");

Scenario("Test Authentication", async () => {
  // ...
})
  .tag("Web interface")
  .tag("Authentication");
```

### Severity

- `allure.severity(name: string): PromiseLike<void>`
- `@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
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.severity("critical");
  // ...
});
```

**Tags API:**
```js
Feature("Test My Website");

Scenario("Test Authentication", async () => {
  // ...
}).tag("@allure.label.severity:critical");
```

### Label

- `allure.label(name: LabelName | string, value: string): PromiseLike<void>`
- `allure.labels(...labelsList: Label[]): PromiseLike<void>`
- `@allure.label.⟨NAME⟩:⟨VALUE⟩`

Set an arbitrary [label](/docs/v2/readability/#other-labels) 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.

**Runtime API:**
```js
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.label("my custom label", "value");
  // ...
});
```

**Tags API:**
```js
Feature("Test My Website");

Scenario("Test Authentication", async () => {
  // ...
}).tag("@allure.label.MyCustomLabel:value");
```

### ID

- `@allure.id:⟨VALUE⟩`

Set the test's [ID](/docs/v2/readability/#id).

```js
Feature("Test My Website");

Scenario("Test Authentication", async () => {
  // ...
}).tag("@allure.id:123");
```

### 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](/docs/v2/readability/#links) 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`](/docs/codeceptjs-configuration/#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`.

```js
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.link("https://dev.example.com/", "Website");
  await allure.issue("AUTH-123", "https://issues.example.com/AUTH-123");
  await allure.tms("TMS-456", "https://tms.example.com/TMS-456");
  // ...
});
```

## 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](/docs/v2/navigation/#behavior-based-hierarchy).

**Runtime API:**
```js
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.epic("Web interface");
  await allure.feature("Essential features");
  await allure.story("Authentication");
  // ...
});
```

**Tags API:**
```js
Feature("Test My Website");

Scenario("Test Authentication", async () => {
  // ...
})
  .tag("@allure.label.epic:WebInterface")
  .tag("@allure.label.feature:EssentialFeatures")
  .tag("@allure.label.story:Authentication");
```

## 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 name of suite, as part of Allure's [suite-based hierarchy](/docs/v2/navigation/#suite-based-hierarchy).

**Runtime API:**
```js
const allure = require("allure-js-commons");

Feature("Test My Website");

Scenario("Test Authentication", async () => {
  await allure.parentSuite("Tests for web interface");
  await allure.suite("Tests for essential features");
  await allure.subSuite("Tests for authentication");
  // ...
});
```

**Tags API:**
```js
Feature("Test My Website");

Scenario("Test Authentication", async () => {
  // ...
})
  .tag("@allure.label.parentSuite:TestsForWebInterface")
  .tag("@allure.label.suite:TestsForEssentialFeatures")
  .tag("@allure.label.subSuite:TestsForAuthentication");
```

## 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 step or sub-step](/docs/steps/) 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 step name during its execution.
- `parameter()` — indicate arbitrary parameters used for the step. The available signatures of this method are similar to the test-wide implementation, see [Parametrized tests](#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.

```js
const allure = require("allure-js-commons");
const { Status } = require("allure-js-commons");

Feature("Test My Website");

Scenario("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);
});
```

## 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](/docs/v2/readability/#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. 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.

```js
const allure = require("allure-js-commons");

Feature("Test My Website");

let accounts = new DataTable(["login", "password"]);
accounts.add(["johndoe", "qwerty"]);
accounts.add(["admin", "qwerty"]);

Data(accounts).Scenario("Test Authentication", async ({ current }) => {
  await allure.parameter("Login", current.login);
  await allure.parameter("Password", current.password);
  // ...
});
```

## 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](/docs/attachments/) to the test result under the given `name`. Pass either the `content` 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
const allure = require("allure-js-commons");
const { ContentType } = require("allure-js-commons");

Feature("Test My Website");

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