---
title: Cypress configuration
description: Configuration properties for Allure Cypress | Change allure-results directory
---

# Allure Cypress configuration

The [Allure Cypress](/docs/cypress/) integration behavior can be affected by some configuration options set in your [Cypress configuration file](https://docs.cypress.io/guides/references/configuration), e.g., `cypress.config.ts`.

The configuration options must be defined in the object passed to `allureCypress()` as the third argument. For example:

```js
import { allureCypress } from "allure-cypress/reporter";
import { Status } from "allure-js-commons";
import * as os from "node:os";

export default {
  e2e: {
    setupNodeEvents(on, config) {
      allureCypress(on, config, {
        resultsDir: "allure-results",
        links: {
          issue: {
            nameTemplate: "Issue #%s",
            urlTemplate: "https://issues.example.com/%s",
          },
          tms: {
            nameTemplate: "TMS #%s",
            urlTemplate: "https://tms.example.com/%s",
          },
          jira: {
            urlTemplate: (v) => `https://jira.example.com/browse/${v}`,
          },
        },
        categories: [
          {
            name: "foo",
            messageRegex: "bar",
            traceRegex: "baz",
            matchedStatuses: [Status.FAILED, Status.BROKEN],
          },
        ],
        environmentInfo: {
          os_platform: os.platform(),
          os_release: os.release(),
          os_version: os.version(),
          node_version: process.version,
        },
      });
      return config;
    },
  },
};
```

Warning:
Both the `config` object and the Allure Cypress configuration must be passed to `allureCypress()`. Skipping the `config` object may cause some of the integration features to not work.

## Using Allure Cypress with custom event handlers

Some of the Allure Cypress functionality is implemented via the event handlers for the [`after:spec`](https://docs.cypress.io/api/plugins/after-spec-api) of [`after:run`](https://docs.cypress.io/api/plugins/after-run-api) events. If your project needs to define its own handlers to these events, it is important to make sure that Cypress executes all handlers, not the last defined ones.

To do so, save the result of the `allureCypress()` call into a variable and call its `onAfterSpec()` or `onAfterRun()` at the beginning of your event handlers.

For example:

```js
import { allureCypress } from "allure-cypress/reporter";
import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    setupNodeEvents: (on, config) => {
      const allurePlugin = allureCypress(on, config);

      on("after:run", (results) => {
        allurePlugin.onAfterRun(results);

        // ... the rest of the code ...
      });

      return config;
    },
  },
});
```

## Using Allure Cypress with other Cypress plugins

To avoid conflicts between Allure Cypress and other Cypress plugins that rely on handling the [`after:spec`](https://docs.cypress.io/api/plugins/after-spec-api) of [`after:run`](https://docs.cypress.io/api/plugins/after-run-api) events, we recommend using [`cypress-on-fix`](https://github.com/bahmutov/cypress-on-fix). It modifies the `on` object so that you can then pass it to multiple Cypress plugins (including Allure Cypress) without causing event handler conflicts.

Here's an example that uses both Allure Cypress and [Cucumber preprocessor for Cypress](https://github.com/badeball/cypress-cucumber-preprocessor):

```js
import { defineConfig } from "cypress";
import { allureCypress } from "allure-cypress/reporter";
import createBundler from "@bahmutov/cypress-esbuild-preprocessor";
import { addCucumberPreprocessorPlugin } from "@badeball/cypress-cucumber-preprocessor";
import { createEsbuildPlugin } from "@badeball/cypress-cucumber-preprocessor/esbuild";
import cypressOnFix from "cypress-on-fix";

export default defineConfig({
  e2e: {
    setupNodeEvents = async (on, config) => {
      on = cypressOnFix(on);

      await addCucumberPreprocessorPlugin(on, config);

      on("file:preprocessor", createBundler({
        plugins: [createEsbuildPlugin(config)],
      }));

      allureCypress(on, config);

      return config;
    },
    // ...
  },
});
```

## Supported options

### resultsDir

Path to the directory where Allure Cypress will save the test results, see [How it works](/docs/how-it-works/). If the directory does not exist, it will be created. Defaults to `allure-results`.

### links

A mapping of templates that can be used to construct full URLs from short identifiers.

For each type of link (see [`allure.link()`](/docs/cypress-reference/#link)), you can specify the following:

- `nameTemplate` — a template or a function for generating the link name when it is not provided.
- `urlTemplate` — a template or a function for generating the link address when it is not provided.

The templates can be strings (with `%s` where the identifier should be placed) or functions (accepting the identifier and returning the URL).

For example, with the configuration above, `allure.issue("123")` will produce a link with the name `Issue #123` and the address `https://issues.example.com/`. Allure will display the link with the appropriate icon for the `issue` type.

### categories

Define custom categories that will be used to distinguish test results by their errors; see [Categories](/docs/categories/).

This setting is an array, each item being an object representing one custom category. The objects may have the following properties:

- `name` — a category name.
- `messageRegex` — a regular expression that the test result's message should match.
- `traceRegex` — a regular expression that the test result's trace should match.
- `matchedStatuses` — an array of statuses that the test result should be one of.
- `flaky` — whether the test result should be marked as [flaky](/docs/test-stability/#flaky-tests).

### environmentInfo

Key-value pairs that will be displayed on the report's main page, see [Environment information](/docs/v2/readability/#environment-information).