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

# Allure Mocha configuration

There are two ways of configuring [Allure Mocha](/docs/mocha/): [using a runner script](#using-a-runner-script) and via [Mocha's configuration](#using-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:**
```js
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:**
```js
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](https://www.npmjs.com/package/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:**
```shell
node ./runner.mjs
```

**yarn:**
```shell
yarn node ./runner.mjs
```

## Using Mocha's configuration

You may use a [Mocha configuration file](https://mochajs.org/#configuring-mocha-nodejs) or [the CLI](https://mochajs.org/#command-line-usage) to configure Allure Mocha. Keep in mind, though, that only [`resultsDir`](#resultsdir) and [`extraReporters`](#extrareporters) are supported that way.

**.mocharc.json:**
```json
{
  "reporter": "allure-mocha",
  "reporterOptions": ["resultsDir=allure-results", "extraReporters=spec"]
}
```

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

**.mocharc.yaml:**
```yaml
reporter: allure-mocha
reporterOptions:
  - "resultsDir=allure-results"
  - "extraReporters=spec"
```

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

**CLI:**
```shell
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](https://github.com/allure-framework/allure-js/blob/v2.15.1/packages/allure-mocha/README.md).

### resultsDir

Path to the directory where Allure Mocha 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`.

Warning:
The path can't contain the `=` and `,` characters if provided via a Mocha configuration file or the CLI. Use a [runner script](#using-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:**
```js
npx mocha -R allure-mocha -O extraReporters=spec
```

**Local reporter:**
```js
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](#using-a-runner-script)):

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

You may enable more than one extra reporter:

```js
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()`](/docs/mocha-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, `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](#using-a-runner-script).

### 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).

Info:
This option can only be provided via a [runner script](#using-a-runner-script).

### environmentInfo

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

Info:
This option can only be provided via a [runner script](#using-a-runner-script).