# Mocha reporter

Source: https://docs.qualflare.com/docs/reporters/mocha · Last updated: 2026-10-29

Install @qualflare/mocha, set it as the reporter in .mocharc.cjs with array options, and upload the qualflare-results folder with the Qualflare CLI.

`@qualflare/mocha` is the Qualflare reporter for Mocha 8 or later: it writes each run's results, with per-attempt retries, nested steps and attachments, to `./qualflare-results`, and `qf <identifier> collect` uploads the folder as one launch.

| Fact                 | Detail                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| Package              | [`@qualflare/mocha`](https://www.npmjs.com/package/@qualflare/mocha) on npm                      |
| Works with           | Mocha 8 or later, Node.js 18 or later                                                            |
| qf                   | (requires qf 0.1.24 or later)                                                                    |
| License              | Apache-2.0                                                                                       |
| Source               | [Qualflare/qualflare-mocha](https://github.com/Qualflare/qualflare-mocha) on GitHub              |
| Without the reporter | `--format mocha` with [Mocha's JSON reporter](https://docs.qualflare.com/docs/cli/formats#mocha) |

## Before you begin

* The Qualflare CLI, `qf`: [Install the CLI](https://docs.qualflare.com/docs/cli/installation).
* A saved login: `qf login <identifier>` with a project access token whose creator still holds the project role that uploads need (requires the Editor role or higher in the project) ([Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication)).
* The **Identifier** of the environment the results belong to ([Environments](https://docs.qualflare.com/docs/runs/environments#identifier)).

## Install

```bash
npm install --save-dev @qualflare/mocha
```

## Configure

```javascript
// .mocharc.cjs
module.exports = {
  reporter: '@qualflare/mocha/reporter',
  // Array of `key=value`, NOT an object — see below.
  reporterOption: ['environment=staging'],
  // Required only for the qualflare.*() metadata API — see below.
  require: ['@qualflare/mocha/hooks'],
};
```

> **Warning: Pass reporterOption as an array**
>
> Write options as `key=value` strings in an array, such as `['environment=staging']`. An object works only on Mocha 12: Mocha 10 turns it into nothing usable and Mocha 8 drops it, and the run passes with every option at its default.

On the command line:

```bash
mocha --reporter @qualflare/mocha/reporter \
      --reporter-option environment=staging \
      --require @qualflare/mocha/hooks
```

`--require @qualflare/mocha/hooks` is needed only for the `qualflare.*()` metadata calls; without it every result is still reported.

Every reporter shares the other settings: see [Reporter configuration](https://docs.qualflare.com/docs/reporters/configuration).

Set `environment` to the environment's Identifier: a name such as `Staging` fails the upload with HTTP 400 ([Environment](https://docs.qualflare.com/docs/reporters/configuration#environment)).

## Run and upload

```bash
npx mocha
qf <identifier> collect ./qualflare-results
```

`mocha --parallel` needs no configuration: the reporter writes one report for the whole run.

## Run in CI

```yaml
- name: Upload results to Qualflare
  if: ${{ !cancelled() }}
  env:
    QF_TOKEN: ${{ secrets.QF_TOKEN }}
    QF_BRANCH: ${{ github.head_ref || github.ref_name }}
    QF_COMMIT: ${{ github.event.pull_request.head.sha || github.sha }}
  run: |
    npm install -g @qualflare/cli
    qf login ci --force
    qf ci collect ./qualflare-results
```

`if: ${{ !cancelled() }}` uploads the results when tests fail, and `QF_BRANCH` and `QF_COMMIT` record a pull request's own branch and commit ([Pull request branches](https://docs.qualflare.com/docs/cli/ci-cd#pull-request-branches)). For GitLab CI/CD, Jenkins and Azure Pipelines, see [Run the upload when tests fail](https://docs.qualflare.com/docs/cli/ci-cd#run-when-tests-fail).

## Sharding and retries

Mocha's own `--shard i/N` gives the shard index; point every shard at the same folder. See [Merge sharded CI jobs into one launch](https://docs.qualflare.com/docs/cli/sharding#merge-sharded-ci-jobs).

## What gets uploaded

* Status, with the history of each retried attempt.
* Nested steps and attachments.
* Labels, links, tags, priority and parameters.

A test sets its own metadata with the `qualflare` calls; a masked parameter's value is dropped before the report is written:

```javascript
const { qualflare } = require('@qualflare/mocha');

it('checks out', async function () {
  qualflare.label('feature', 'checkout');
  qualflare.link('https://example.com/issue/42', { type: 'issue', name: 'QF-42' });
  qualflare.tag('smoke');
  qualflare.priority('high');

  await qualflare.step('add to cart', () => {
    qualflare.parameter('sku', 'widget');
    qualflare.parameter('token', process.env.TOKEN, { masked: true });
  });
});
```

`qf` doesn't read the branch, commit, language or milestone from the report: set them on the upload ([Branch, commit, language and milestone](https://docs.qualflare.com/docs/reporters/configuration#upload-metadata)).

## Troubleshooting

* Tests a failing hook skipped are missing from the report; the hook failure is recorded.
* Nested `describe` blocks are flattened into the test name, one suite per spec file.
* `qualflare.*()` calls are dropped with a warning: add `--require @qualflare/mocha/hooks`.
* `environment "Staging" does not exist in this project`: use the environment's Identifier, or pass `--environment` on the upload ([Environment](https://docs.qualflare.com/docs/reporters/configuration#environment)).
* Screenshots can't be downloaded: `qf` is older than 0.1.24. [Upgrade qf](https://docs.qualflare.com/docs/cli/installation#upgrading).

## Related

* **Guides:** [Reporters](https://docs.qualflare.com/docs/reporters) · [Upload results with qf collect](https://docs.qualflare.com/docs/cli/collect) · [Sharded runs and result directories](https://docs.qualflare.com/docs/cli/sharding) · [Upload screenshots, videos and traces](https://docs.qualflare.com/docs/cli/artifacts)
* **Reference:** [Reporter configuration](https://docs.qualflare.com/docs/reporters/configuration) · [Mocha format](https://docs.qualflare.com/docs/cli/formats#mocha)
* **More:** [Mocha test reporting in Qualflare](https://qualflare.com/mocha-test-reporting/)