{"id":10401,"library":"mocha","title":"Mocha Test Framework","description":"Mocha is a feature-rich JavaScript test framework for Node.js and browsers, designed to make asynchronous testing simple and enjoyable. It offers a flexible base for writing tests and integrates well with various assertion libraries. The current stable version is 11.7.5, with version 12 actively in beta, demonstrating continuous development and frequent updates.","status":"active","version":"11.7.5","language":"javascript","source_language":"en","source_url":"https://github.com/mochajs/mocha","tags":["javascript","mocha","test","bdd","tdd","tap","testing","chai","assertion"],"install":[{"cmd":"npm install mocha","lang":"bash","label":"npm"},{"cmd":"yarn add mocha","lang":"bash","label":"yarn"},{"cmd":"pnpm add mocha","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"When running tests via the Mocha CLI, `describe`, `it`, and other test functions are typically made available as globals. Explicit imports are useful for ESM environments or improved static analysis.","symbol":"describe","correct":"import { describe } from 'mocha';"}],"quickstart":{"code":"import { describe, it } from 'mocha';\nimport { expect } from 'chai';\n\ndescribe('Array', () => {\n  it('should return -1 when the value is not present', () => {\n    expect([1, 2, 3].indexOf(4)).to.equal(-1);\n  });\n\n  it('should return the correct index when present', () => {\n    expect([1, 2, 3].indexOf(2)).to.equal(1);\n  });\n});\n","lang":"typescript","description":"This quickstart demonstrates a basic Mocha test suite using `describe` and `it` with the Chai assertion library. To run, save this code as `test.ts`, install dependencies (`npm install mocha chai ts-node`), and execute with `npx mocha --require ts-node/register test.ts`."},"warnings":[{"fix":"Increase the timeout for individual tests or suites using `this.timeout(5000)` (inside a regular function, not an arrow function) or globally via the CLI (`mocha --timeout 5000`).","message":"Mocha tests have a default timeout of 2000ms. Asynchronous tests or complex operations exceeding this can lead to 'Timeout of 2000ms exceeded' errors, especially in CI environments or slower machines.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use traditional `function` declarations for hooks and tests that require access to the Mocha context (e.g., `before(function() { this.timeout(5000); })`).","message":"Using arrow functions for Mocha hooks (`before`, `afterEach`, `it`, etc.) prevents access to the Mocha context (`this`), which is necessary for methods like `this.timeout()`, `this.retries()`, or `this.skip()`. Arrow functions do not bind their own `this` context.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the Mocha v12 release notes and documentation for guidance on migrating existing CommonJS setups to ESM, including `package.json` type field and file extensions.","message":"Mocha v12 (currently in beta) introduces robust ESM support, including direct `.mjs` exports and ESM configuration files. Projects relying on CommonJS modules might require configuration adjustments and code changes when upgrading to v12.","severity":"breaking","affected_versions":">=12.0.0-beta"},{"fix":"Verify the glob pattern (e.g., `mocha 'test/**/*.test.ts'`). Ensure test files are correctly named and located in the specified directories. Use `--recursive` if tests are in subdirectories.","message":"If Mocha reports 'No tests found' and exits with an error, it often indicates an issue with the specified test file paths or glob patterns in the CLI command or configuration. It can also happen if test files are not accessible or contain syntax errors preventing their loading.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Increase the timeout for the test/suite using `this.timeout(5000)` or globally with `mocha --timeout 5000`. Ensure asynchronous operations return a Promise or call `done()`.","cause":"An asynchronous test or hook executed longer than the default 2-second timeout.","error":"Timeout of 2000ms exceeded. For async tests and hooks, ensure \"done()\" is called or a Promise is returned."},{"fix":"Double-check the test file paths and glob patterns specified in your `mocha` command or configuration file. Ensure files exist and are correctly named.","cause":"Mocha could not find any test files matching the configured patterns or paths.","error":"Error: No tests found"},{"fix":"Execute your test file using the `mocha` command (e.g., `npx mocha my-test.js`). Ensure Mocha is installed and correctly configured to expose globals.","cause":"The test file is being run outside the Mocha test runner, or Mocha's global test functions are not exposed.","error":"ReferenceError: describe is not defined"},{"fix":"Change the arrow function to a traditional `function` declaration: `it('...', function() { this.timeout(5000); /* ... */ });`.","cause":"Attempted to use `this.timeout()` or other Mocha context methods within an arrow function, which does not correctly bind `this`.","error":"TypeError: Cannot read properties of undefined (reading 'timeout')"},{"fix":"Review the console output immediately preceding the exit code for more specific error messages. Use `mocha --full-trace` for detailed stack traces to pinpoint the issue.","cause":"A general failure occurred, often due to a test failure, uncaught exception, unhandled promise rejection, or a critical configuration error.","error":"Mocha exited with code 1"}],"ecosystem":"npm"}