Allure Mocha configuration

There are two ways of configuring Allure Mocha: using a runner script and via Mocha's configuration. The first one requires some extra steps but supports all the configuration options of Allure Mocha. The second one is easier to use, but only a limited set of options is supported.

Using a runner script

Create a runner script and pass the reporter and reporterOptions properties to an instance of Mocha. Then, use the configured instance to run the tests.

Here are examples of ESM and CommonJS setups:

runner.mjs

import { Status } from "allure-js-commons";
import { glob } from "glob";
import Mocha from "mocha";
import * as os from "node:os";

const mocha = new Mocha({
  reporter: "allure-mocha",
  reporterOptions: {
    resultsDir: "allure-results",
    extraReporters: "spec",
    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,
    },
  },

  /* Other Mocha options... */
});

glob.sync("test/**/*.spec.{m,c,}js").forEach((file) => mocha.addFile(file));
await mocha.loadFilesAsync();
mocha.run((failures) => process.exit(failures));

runner.cjs

const { Status } = require("allure-js-commons");
const { glob } = require("glob");
const Mocha = require("mocha");
const os = require("node:os");

const mocha = new Mocha({
  reporter: "allure-mocha",
  reporterOptions: {
    resultsDir: "allure-results",
    extraReporters: "spec",
    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,
    },
  },

  /* Other Mocha options */
});

glob.sync("test/**/*.spec.{m,c,}js").forEach((file) => mocha.addFile(file));
mocha.loadFilesAsync().then(() => {
  mocha.run((failures) => process.exit(failures));
});

INFO

The examples use the glob package to locate and load the test files. You may need to adjust the pattern to your project's layout.

Execute the script to run the tests:

npm, pnpm

node ./runner.mjs

yarn

yarn node ./runner.mjs

Using Mocha's configuration

You may use a Mocha configuration file or the CLI to configure Allure Mocha. Keep in mind, though, that only resultsDir and extraReporters are supported that way.

.mocharc.json

{
  "reporter": "allure-mocha",
  "reporterOptions": ["resultsDir=allure-results", "extraReporters=spec"]
}

package.json

{
  // ...
  "mocha": {
    "reporter": "allure-mocha",
    "reporterOptions": ["resultsDir=allure-results", "extraReporters=spec"]
  }
}

.mocharc.yaml

reporter: allure-mocha
reporterOptions:
  - "resultsDir=allure-results"
  - "extraReporters=spec"

.mocharc.cjs

module.exports = {
  reporter: "allure-mocha",
  reporterOptions: ["resultsDir=allure-results", "extraReporters=spec"],
};

CLI

npx mocha -R "allure-mocha" -O "resultsDir=allure-results,extraReporters=spec"

Configuration options

INFO

This section describes the configuration options for Allure Mocha 3.0 and newer. For older versions, you may check this readme.

resultsDir

Path to the directory where Allure Mocha will save the test results, see How it works. If the directory does not exist, it will be created. Defaults to allure-results.

WARNING

The path can't contain the = and , characters if provided via a Mocha configuration file or the CLI. Use a runner script if you need to overcome this limitation.

extraReporters

One or more Mocha reporters to run alongside Allure Mocha. In its most basic form, it takes a single string, which is a reporter's module name or path:

Built-in reporter

npx mocha -R allure-mocha -O extraReporters=spec

Local reporter

npx mocha -R allure-mocha -O extraReporters=./reporter.cjs

If you need to pass options to the reporter, use the following syntax (it's only supported in a runner script):

const mocha = new Mocha({
  reporter: "allure-mocha",
  reporterOptions: {
    extraReporters: ["json", { output: "results.json" }],
  },
});

You may enable more than one extra reporter:

const mocha = new Mocha({
  reporter: "allure-mocha",
  reporterOptions: {
    extraReporters: ["spec", ["json", { output: "results.json" }]],
  },
});

links

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

For each type of link (see allure.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, await 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.

INFO

This option can only be provided via a runner script.

categories

Define custom categories that will be used to distinguish test results by their errors; see Defect 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.

INFO

This option can only be provided via a runner script.

environmentInfo

Key-value pairs that will be displayed on the report's main page, see Environment information.

INFO

This option can only be provided via a runner script.