# @wdio/mocha-framework

> A WebdriverIO plugin. Adapter for Mocha testing framework.

Latest version **10.0.1** (published 2026-10-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @wdio/mocha-framework
pnpm add @wdio/mocha-framework
yarn add @wdio/mocha-framework
bun add @wdio/mocha-framework
```

## Health

**Score 70/100 (B)** — status: active.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 10.0.1 |
| Published | 2026-10-07 |
| First published | 2018-11-06 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=22.19.0 |
| Dependencies | 6 |
| Unpacked size | 30.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 9844 |
| Author | Christian Bromann |
| Maintainers | christian-bromann, wdio-user, wswebcreation-nl |
| Keywords | webdriver, wdio, wdio-reporter |

## Links

- npm: https://www.npmjs.com/package/@wdio/mocha-framework
- Repository: https://github.com/webdriverio/webdriverio
- Homepage: https://github.com/webdriverio/webdriverio/tree/main/packages/wdio-mocha-framework
- Issues: https://github.com/webdriverio/webdriverio/issues
- npm.io page: https://npm.io/package/@wdio/mocha-framework

## Dependencies (6)

- [mocha](https://npm.io/package/mocha.md) ^12.0.2
- [@types/node](https://npm.io/package/@types/node.md) ^22.20.4
- [@wdio/types](https://npm.io/package/@wdio/types.md) 10.0.1
- [@wdio/utils](https://npm.io/package/@wdio/utils.md) 10.0.1
- [@types/mocha](https://npm.io/package/@types/mocha.md) ^10.0.10
- [@wdio/logger](https://npm.io/package/@wdio/logger.md) 10.0.0

## Recent versions

- 10.0.1 (latest) — 2026-10-07
- 10.1.0-alpha.30 (next) — 2026-10-07
- 8.46.0 (v8) — 2025-08-11
- 7.40.0 (v7) — 2024-12-18
- 9.0.0-alpha.0 (v9) — 2024-03-12
- 7.0.0-beta.4 (beta) — 2021-02-09
- 5.23.0 (latest-5) — 2020-05-25
- 10.1.0-alpha.29 — 2026-10-07
- 10.1.0-alpha.26 — 2026-10-06
- 10.1.0-alpha.25 — 2026-10-06
- 10.1.0-alpha.19 — 2026-10-06
- 10.1.0-alpha.18 — 2026-10-06
- 10.0.0 — 2026-10-05
- 10.0.0-alpha.175 — 2026-10-04
- 10.0.0-alpha.165 — 2026-10-04
- … 423 more at https://npm.io/package/@wdio/mocha-framework/versions

## README

WDIO Mocha Framework Adapter
============================

> A WebdriverIO plugin. Adapter for Mocha testing framework.

## Installation

The easiest way is to keep `@wdio/mocha-framework` as a devDependency in your `package.json`, via:

```sh
npm install @wdio/mocha-framework --save-dev
```

Instructions on how to install `WebdriverIO` can be found [here.](https://webdriver.io/docs/gettingstarted)

## Configuration

Following code shows the default wdio test runner configuration...

```js
// wdio.conf.js
module.exports = {
  // ...
  framework: 'mocha',

  mochaOpts: {
    ui: 'bdd'
  }
  // ...
};
```

Note that interfaces supported are `bdd`, `tdd` and `qunit`. If you want to provide a custom interface, it should expose methods compatible with them and be named ending with `-bdd`, `-tdd` or `-qunit` accordingly.

## `mochaOpts` Options

Options will be passed to the Mocha instance. See the list of supported Mocha options [here](https://github.com/mochajs/mocha/wiki/Using-mocha-programmatically#set-options).

`failHookAffectedTests` defaults to `true`. When a `before` or `beforeEach` hook fails, the tests that hook skipped are reported as failed. Set `failHookAffectedTests: false` to report only the hook.

----

## `mochaOpts.require (string|string[])`

The `require` option is useful when you want to add or extend some basic functionality. <br />
For example, let's try to create an anonymous `describe`:

**wdio.conf.js**

```js
{
  suites: {
    login: ['tests/login/*.js']
  },

  mochaOpts: {
    require: './hooks/mocha.js'
  }
}
```

**./hooks/mocha.js**

```js
import path from 'path';

let { context, file, mocha, options } = module.parent.context;
let { describe } = context;

context.describe = function (name, callback) {
	if (callback) {
		return describe(...arguments);
	} else {
		callback = name;
		name = path.basename(file, '.js');

		return describe(name, callback);
	}
}
```

**./tests/TEST-XXX.js**

```js
describe(() => {
	it('Login form', function () => {
		this.skip();
	});
});
```

**Output**

```
TEST-XXX
   ✓ Login form
```

For more information on WebdriverIO see the [homepage](https://webdriver.io).

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