README.md

allure-cypress

Allure framework integration for Cypress

• Learn more about Allure Report at https://allurereport.org
• 📚 Documentation – discover official documentation for Allure Report
• ❓ Questions and Support – get help from the team and community
• 📢 Official annoucements – be in touch with the latest updates
• 💬 General Discussion – engage in casual conversations, share insights and ideas with the community

---

Installation

Use your favorite Node.js package manager to install the required packages:

npm add -D allure-cypress

Add the following lines to your cypress.config.js file:

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

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

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

Import allure-cypress in cypress/support/e2e.js:

import "allure-cypress";

Allure Cypress is ready to run now. When the test run completes, the result files will be collected in the ./allure-results directory. If you want to use another location, provide it via the resultsDir configuration option (see below).

View the report

You need Allure Report to generate and open the report from result files. See the installation instructions for more details.

Generate Allure Report:

allure generate ./allure-results -o ./allure-report

Open Allure Report:

allure open ./allure-report

The documentation

Learn more about Allure Cypress from the official documentation at https://allurereport.org/docs/cypress/.

Allure Cypress options

Customize Allure Cypress by providing a configuration object as the third argument of allureCypress.

The following options are supported:

Option	Description	Default
resultsDir	The path of the results folder.	./allure-results
videoOnFailOnly	When video capturing is enabled, set this option to true to attach the video to failed specs only.	false
links	Allure Runtime API link templates.	undefined
stepsFromCommands	Options that affect how Allure creates steps from Cypress commands	See below
environmentInfo	A set of key-value pairs to display in the Environment section of the report	undefined
categories	An array of category definitions, each describing a category of defects	undefined

stepsFromCommands

Property	Description	Default
maxArgumentLength	The maximum length of the parameter value created from Cypress command argument. The rest of the characters are replaces with ....	128
maxArgumentDepth	The maximum depth of the Cypress command argument (an array or an object) that will be converted to the corresponding step parameter value.	3

Example

Here is an example of the Allure Cypress configuration:

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

export default defineConfig({
  e2e: {
    setupNodeEvents: (on, config) => {
      allureCypress(on, config, {
        resultsDir: "my-allure-results",
        videoOnFailOnly: true,
        links: {
          link: {
            urlTemplate: "https://github.com/allure-framework/allure-js/blob/main/%s",
          },
          issue: {
            urlTemplate: "https://github.com/allure-framework/allure-js/issues/%s",
            nameTemplate: "ISSUE-%s",
          },
        },
        stepsFromCommands: {
          maxArgumentLength: 64,
          maxArgumentDepth: 5,
        },
        environmentInfo: {
          OS: os.platform(),
          Architecture: os.arch(),
          NodeVersion: process.version,
        },
        categories: [
          {
            name: "Missing file errors",
            messageRegex: /^ENOENT: no such file or directory/,
          },
        ],
      });

      return config;
    },
    // other Cypress config properties ...
  },
});

More details about Allure Cypress configuration are available at https://allurereport.org/docs/cypress-configuration/.

Combining Allure with other Cypress plugins

Use cypress-on-fix to enable Allure with other Cypress plugins. See more info here.

In the next example, Allure Cypress is enabled together with @badeball/cypress-cucumber-preprocessor:

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

Common issues

The test plan feature doesn't work

Make sure you pass the Cypress config as the second argument of allureCypress.

Correct:

allureCypress(on, config);

Also correct:

allureCypress(on, config, {
  resultsDir: "output",
});

Incorrect (the test plan won't work):

allureCypress(on);

Also incorrect (the legacy style; the test plan won't work either):

allureCypress(on, {
  resultsDir: "output",
});

setupNodeEvents limitations

Cypress can't compose multiple Node events, which are set in setupNodeEvents.

Allure Cypress requires access to the following events:

• after:spec
• after:run

Otherwise, it may not work as expected.

If you need to define your own handlers of those events, make sure to call the corresponding functions of the allureCypresss' return value:

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

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

      on("after:spec", (spec, results) => {
        allurePlugin.onAfterSpec(spec, results);

        // your code ...
      });

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

        // your code ...
      });

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

If you want to combine Allure Cypress with other plugins, consider using cypress-on-fix. See the example for the Cypress Cucumber preprocessor above.

You may read more details and workarounds in issues cypress-io/cypress#5240 and cypress-io/cypress#22428.