WDIO Mocha Framework Adapter

0.6.4 · abandoned · verified Tue Apr 21

The `wdio-mocha-framework` package, specifically version 0.6.4, served as an adapter to integrate the Mocha testing framework with WebdriverIO. Released many years ago, it allowed users to write their automated browser tests using Mocha's BDD (Behavior Driven Development) or TDD (Test Driven Development) interfaces within the WebdriverIO test runner. Its primary function was to parse Mocha tests, execute them via WebdriverIO's browser automation capabilities, and report results. Key configurations included `mochaOpts` for passing options directly to Mocha, and `require`/`compilers` for custom setup files or transpilers. This standalone package has since been abandoned; its last stable version, 0.6.4, was published in 2017. Modern WebdriverIO projects (v5+) utilize `@wdio/mocha-framework`, which is part of the main WebdriverIO monorepo and receives active maintenance and updates, reflecting a continuous release cadence in alignment with WebdriverIO's own major versions.

Common errors

```
Error: Cannot find module 'wdio-mocha-framework'
```
cause The `wdio-mocha-framework` package is either not installed, or WebdriverIO is attempting to load a framework that is not correctly configured or available.

fix Verify that `wdio-mocha-framework` is listed in your `devDependencies` in `package.json` and that you have run `npm install`. If using a modern WebdriverIO (v5+), you should instead install and configure `@wdio/mocha-framework`.
```
Error: `framework` 'mocha' not found!
```
cause WebdriverIO cannot locate the specified Mocha framework adapter. This can happen if the package is installed but not correctly integrated, or if there's a fundamental version mismatch between WebdriverIO and the adapter.

fix Check your `wdio.conf.js` to ensure `framework: 'mocha'` is correctly specified. Confirm `wdio-mocha-framework` (for WDIO v4) or `@wdio/mocha-framework` (for modern WDIO) is installed in your `node_modules` directory and listed in your `package.json`.

Warnings

breaking The standalone `wdio-mocha-framework` package (version 0.6.4) is abandoned and no longer maintained. Users should migrate to `@wdio/mocha-framework`, which is part of the official WebdriverIO monorepo and actively developed for WebdriverIO v5+.
Fix: Migrate your WebdriverIO setup to use WebdriverIO v5 or newer and replace `wdio-mocha-framework` with `@wdio/mocha-framework` in your `package.json` and `wdio.conf.js`. This will involve updating WebdriverIO itself and potentially other plugins, requiring adjustments to configuration and test code.
gotcha This package (0.6.4) is compatible with WebdriverIO v4. Newer WebdriverIO versions (v5, v6, v7, v8) introduce significant breaking changes in their configuration, APIs, and plugin architecture. Using this old package with a modern WebdriverIO installation will lead to incompatibility errors and non-functional tests.
Fix: Ensure your WebdriverIO version matches the framework adapter's compatibility. For current WebdriverIO versions, use `@wdio/mocha-framework`. If you are stuck on WebdriverIO v4, ensure all your `wdio-*` packages are also v4 compatible.
gotcha The `mochaOpts.require` configuration within `wdio.conf.js` loads custom JavaScript files. In the context of WebdriverIO v4 and Node.js versions prevalent at the time, these files are typically expected to use CommonJS modules (`module.exports`, `require()`). Using ECMAScript Modules (ESM) syntax (`import`, `export`) in such files might lead to syntax errors unless your environment is specifically configured to handle ESM.
Fix: When using `mochaOpts.require` for setup scripts, ensure they are written using CommonJS syntax. If ESM is strictly required, explore transpilation options or consider upgrading to a modern WebdriverIO setup that offers better ESM support.

Install

npm install wdio-mocha-framework npm
yarn add wdio-mocha-framework yarn
pnpm add wdio-mocha-framework pnpm

Quickstart

Demonstrates the basic `wdio.conf.js` setup for using the `wdio-mocha-framework` with WebdriverIO v4. It shows how to specify Mocha as the framework, configure `mochaOpts`, and includes a basic runnable Mocha test file.

/* wdio.conf.js */
// This configuration file is for WebdriverIO v4, compatible with wdio-mocha-framework 0.6.4
module.exports = {
  // Define where your test files are located
  specs: [
    './tests/**/*.js'
  ],

  // Capabilities (browser settings)
  capabilities: [{
    browserName: 'chrome'
  }],

  // Log level
  logLevel: 'info',

  // Reporters
  reporters: ['spec'],

  // Specify the framework to use. For Mocha, use 'mocha'.
  framework: 'mocha',

  // Options for Mocha
  mochaOpts: {
    ui: 'bdd',
    timeout: 60000, // Example: set a default timeout for all tests
    // You can also specify custom require files here for test setup or transpilation
    // require: ['./hooks/mocha-setup.js'],
    // compilers: ['coffee:foo'], // Example for transpilers like CoffeeScript
  },
  // ... other WebdriverIO configuration options
};


/* Example test file (e.g., ./tests/example.js) */
describe('My WebdriverIO application', () => {
  it('should navigate to a page and check its title', async () => {
    await browser.url('https://webdriver.io');
    const title = await browser.getTitle();
    console.log(`Page title: ${title}`);
    // In a real project, you would typically use an assertion library like @wdio/expect
    // For this old version, a simple JS check suffices, or an older assertion library.
    if (!title.includes('WebdriverIO')) {
      throw new Error('Title does not contain expected text');
    }
  });

  it('should demonstrate a skipped test', function() {
    this.skip(); // Mocha's way to skip a test
  });
});

view raw JSON →