{"id":15927,"library":"wdio-mocha-framework","title":"WDIO Mocha Framework Adapter","description":"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.","status":"abandoned","version":"0.6.4","language":"javascript","source_language":"en","source_url":"https://github.com/webdriverio/wdio-mocha-framework","tags":["javascript","mocha","webdriverio","wdio","wdio-plugin","wdio-framework"],"install":[{"cmd":"npm install wdio-mocha-framework","lang":"bash","label":"npm"},{"cmd":"yarn add wdio-mocha-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add wdio-mocha-framework","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a WebdriverIO framework adapter and requires WebdriverIO to function as a test runner. It operates as a conceptual peer dependency for WebdriverIO v4 setups.","package":"webdriverio","optional":false}],"imports":[],"quickstart":{"code":"/* wdio.conf.js */\n// This configuration file is for WebdriverIO v4, compatible with wdio-mocha-framework 0.6.4\nmodule.exports = {\n  // Define where your test files are located\n  specs: [\n    './tests/**/*.js'\n  ],\n\n  // Capabilities (browser settings)\n  capabilities: [{\n    browserName: 'chrome'\n  }],\n\n  // Log level\n  logLevel: 'info',\n\n  // Reporters\n  reporters: ['spec'],\n\n  // Specify the framework to use. For Mocha, use 'mocha'.\n  framework: 'mocha',\n\n  // Options for Mocha\n  mochaOpts: {\n    ui: 'bdd',\n    timeout: 60000, // Example: set a default timeout for all tests\n    // You can also specify custom require files here for test setup or transpilation\n    // require: ['./hooks/mocha-setup.js'],\n    // compilers: ['coffee:foo'], // Example for transpilers like CoffeeScript\n  },\n  // ... other WebdriverIO configuration options\n};\n\n\n/* Example test file (e.g., ./tests/example.js) */\ndescribe('My WebdriverIO application', () => {\n  it('should navigate to a page and check its title', async () => {\n    await browser.url('https://webdriver.io');\n    const title = await browser.getTitle();\n    console.log(`Page title: ${title}`);\n    // In a real project, you would typically use an assertion library like @wdio/expect\n    // For this old version, a simple JS check suffices, or an older assertion library.\n    if (!title.includes('WebdriverIO')) {\n      throw new Error('Title does not contain expected text');\n    }\n  });\n\n  it('should demonstrate a skipped test', function() {\n    this.skip(); // Mocha's way to skip a test\n  });\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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+.","severity":"breaking","affected_versions":">=0.6.4"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.x"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","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.","error":"Error: Cannot find module 'wdio-mocha-framework'"},{"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`.","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.","error":"Error: `framework` 'mocha' not found!"}],"ecosystem":"npm"}