# mocha-helpers

> Mocha convenience helpers

Latest version **11.0.1** (published 2026-09-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install mocha-helpers
pnpm add mocha-helpers
yarn add mocha-helpers
bun add mocha-helpers
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 11.0.1 |
| Published | 2026-09-12 |
| First published | 2019-01-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=22.11 |
| Dependencies | 6 |
| Unpacked size | 14 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Kelly Selden |
| Maintainers | kellyselden |
| Keywords | describe, it, only, skip |

## Links

- npm: https://www.npmjs.com/package/mocha-helpers
- Repository: https://github.com/kellyselden/mocha-helpers
- Homepage: https://github.com/kellyselden/mocha-helpers#readme
- Issues: https://github.com/kellyselden/mocha-helpers/issues
- npm.io page: https://npm.io/package/mocha-helpers

## Dependencies (6)

- [tmp](https://npm.io/package/tmp.md) 0.2.7
- [mocha](https://npm.io/package/mocha.md) ^11.7.1
- [titleize](https://npm.io/package/titleize.md) ^2.1.0
- [callsites](https://npm.io/package/callsites.md) ^3.0.0
- [commondir](https://npm.io/package/commondir.md) ^1.0.1
- [events-async](https://npm.io/package/events-async.md) ^1.2.1

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 11.0.1 (latest) — 2026-09-12
- 11.0.0 — 2026-09-10
- 10.2.1 — 2025-08-12
- 10.2.0 — 2025-06-30
- 10.1.0 — 2025-06-30
- 10.0.0 — 2025-06-21
- 9.1.0 — 2025-06-21
- 9.0.1 — 2024-03-03
- 9.0.0 — 2023-10-29
- 8.0.0 — 2023-07-07
- 7.1.0 — 2023-03-06
- 7.0.1 — 2023-03-03
- 7.0.0 — 2023-01-15
- 6.3.0 — 2023-01-09
- 6.2.4 — 2023-01-09
- … 48 more at https://npm.io/package/mocha-helpers/versions

## README

# mocha-helpers

[![npm version](https://badge.fury.io/js/mocha-helpers.svg)](https://badge.fury.io/js/mocha-helpers)

Mocha convenience helpers

## Usage

Place this file somewhere in your test directory:

```js
// test/helpers/mocha.js
require('mocha-helpers')(module);
```

Then use it via:

```js
// test/unit/my-file/my-function-test.js
const { describe, it } = require('../../helpers/mocha');
const { myFunction } = require('my-file');

describe(function() {
  it(myFunction, function() {
    // stuff
  });

  it.allowFail('skip on error', function() {
    assert.ok(false);
  });
});
```

Prints:

```
  Unit | My-File
    ✓ myFunction
```

## Retry Hooks

Make hooks follow `--retries` logic. https://github.com/mochajs/mocha/issues/2127.

```js
// test/helpers/mocha.js
require('mocha-helpers')(module, {
  retryHooks: true
});
```

Then use it via:

```js
// test/my-test.js
const { describe, beforeEach } = require('./helpers/mocha');

describe(function() {
  let retries = 0;
  beforeEach(function() {
    if (retries++ < 1) {
      throw new Error();
    }
  });

  it('works', function() {
    // stuff
  });
});
```

```
mocha test/my-test.js --retries 1
```

Prints:

```
  My-Test
    ✓ works
```

## Async Events

Add a way to `await` Mocha's synchronous events.

```js
const { events, registerAsyncEvents, unregisterAsyncEvents } = require('mocha-helpers');

let runner;

async function retry(test, err) {
  // do something async on retries...
}

try {
  await new Promise((resolve, reject) => {
    try {
      events.on(constants.EVENT_TEST_RETRY, retry);

      runner = mocha.run(resolve);

      registerAsyncEvents(runner);
    } catch (err) {
      reject(err);
    }
  });
} finally {
  events.off(constants.EVENT_TEST_RETRY, retry);

  if (runner) {
    await unregisterAsyncEvents(runner);
  }
}
```

## Options

```js
require('mocha-helpers')(module, {
  dirname: __dirname,
  titleSeparator: ' | ',
  titleize: true,
  prefix: '',
  retryHooks: false
});
```

---
_Source: https://npm.io/package/mocha-helpers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._