Migrate Your Test Suite from Mocha to Jest (2026)

Jest is the new hotness for JavaScript testing, and migrating your test suite from Mocha is a surprisingly smooth process, mostly because Jest is designed to be a drop-in replacement for many of Mocha’s core functionalities while packing in a ton of extra features.

Let’s see Jest in action with a simple test. Imagine you have a file math.js with a function:

// math.js
function add(a, b) {
  return a + b;
}

function subtract(a, b) {
  return a - b;
}

module.exports = { add, subtract };

Here’s how you’d test it with Jest:

// math.test.js
const { add, subtract } = require('./math');

describe('Math Functions', () => {
  test('adds two numbers correctly', () => {
    expect(add(1, 2)).toBe(3);
  });

  test('subtracts two numbers correctly', () => {
    expect(subtract(5, 3)).toBe(2);
  });
});

When you run npx jest, you’ll see output like this:

PASS  ./math.test.js
  Math Functions
    ✓ adds two numbers correctly (2ms)
    ✓ subtracts two numbers correctly (0ms)

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total

The core problem Jest solves is the fragmentation of the JavaScript testing ecosystem. Before Jest, you’d often cobble together Mocha for running tests, Chai for assertions, Sinon for spies/stubs/mocks, and JSDOM for DOM manipulation. Jest integrates all of these into a single, batteries-included package. It provides a test runner, assertion library (expect), and mocking capabilities out of the box. This unification dramatically simplifies setup and maintenance.

Internally, Jest uses a JSDOM environment by default, which simulates a browser environment for your tests. This means you can test DOM manipulation, event handling, and other browser-specific APIs without needing a physical browser or a separate tool. For Node.js specific code, it can also run tests directly in a Node.js environment.

The key levers you control in Jest are:

• Matchers: These are the assertion functions like toBe, toEqual, toHaveBeenCalled, toHaveLength, etc. Jest has a vast collection, and you can even create custom matchers.
• Mocks: Jest’s mocking system is powerful. You can mock modules (jest.mock('./module')), mock functions (jest.fn()), and spy on existing functions to check if they were called with specific arguments (jest.spyOn(object, 'method')).
• Configuration: Jest is configured via a jest.config.js file or a jest field in your package.json. You can control things like test file patterns, coverage thresholds, module name mappings, and transformer configurations (e.g., for TypeScript or Babel).
• Environment: You can specify the test environment (e.g., jsdom, node) and provide setup/teardown scripts for global setup.

The most surprising thing about Jest’s expect API is its chaining and introspection capabilities. For example, expect(value).toEqual({ a: 1, b: 2 }) doesn’t just check for equality; it recursively compares objects and arrays. When an assertion fails, Jest provides incredibly detailed diffs, showing you exactly where the mismatch occurred, which is a massive time-saver during debugging. It’s not just a simple assert(a === b); it’s an intelligent comparison engine.

To migrate from Mocha, you’ll primarily be replacing describe, it/test, and assert/expect calls. You can often rename your it blocks to test blocks directly. For assertions, if you were using Mocha with Chai’s expect, the transition is almost one-to-one with Jest’s expect.

Here’s a typical migration path:

1. Install Jest:

   npm install --save-dev jest
   # or
   yarn add --dev jest
   

2. Update package.json: Add a test script.

   {
     "scripts": {
       "test": "jest"
     }
   }
   

3. Rename Test Files (Optional but Recommended): Jest typically looks for files named *.test.js, *.spec.js, or files within a __tests__ directory. If your Mocha files have a different naming convention (e.g., *.mocha.js), you might want to rename them or configure Jest’s testMatch or testRegex options.

4. Adapt Test Syntax:

   • describe('my suite', () => { ... }); remains the same.
   • it('should do something', () => { ... }); can be renamed to test('should do something', () => { ... });.
   • Assertions:
     • If you used Mocha + Chai expect:
       • expect(value).to.equal(other); becomes expect(value).toBe(other); (for primitives) or expect(value).toEqual(other); (for deep equality).
       • expect(value).to.be.true; becomes expect(value).toBe(true);.
       • expect(value).to.throw(Error); becomes expect(() => value()).toThrow(Error);.
     • If you used Mocha + Node’s assert:
       • assert.equal(val1, val2); becomes expect(val1).toBe(val2);.
       • assert.deepEqual(obj1, obj2); becomes expect(obj1).toEqual(obj2);.
       • assert.throws(fn); becomes expect(fn).toThrow();.

5. Migrate Mocks/Stubs/Spies: If you were using Sinon.js, Jest’s built-in mocking is a replacement.

   • Spying: sinon.spy(obj, 'method') becomes jest.spyOn(obj, 'method').
   • Stubbing: sinon.stub(obj, 'method').returns(value) becomes jest.spyOn(obj, 'method').mockReturnValue(value).
   • Mocking Modules: jest.mock('module-path', factoryFunction) is Jest’s way to mock entire modules.

Consider a simple Mocha test with Sinon:

// service.js
const axios = require('axios');

async function getUser(id) {
  const response = await axios.get(`/api/users/${id}`);
  return response.data;
}

module.exports = { getUser };

// service.test.js (Mocha + Sinon)
const sinon = require('sinon');
const axios = require('axios');
const { getUser } = require('./service');

describe('User Service', () => {
  it('fetches user data', async () => {
    const mockResponse = { data: { id: 1, name: 'Test User' } };
    const axiosStub = sinon.stub(axios, 'get').resolves(mockResponse);

    const user = await getUser(1);

    expect(user).toEqual(mockResponse.data);
    expect(axiosStub.calledOnceWithExactly('/api/users/1')).toBe(true);

    axiosStub.restore(); // Clean up
  });
});

Here’s the Jest equivalent:

// service.test.js (Jest)
const axios = require('axios');
const { getUser } = require('./service');

// Mock the entire axios module
jest.mock('axios');

describe('User Service', () => {
  it('fetches user data', async () => {
    const mockResponse = { data: { id: 1, name: 'Test User' } };
    // Configure the mocked axios.get to resolve with our mock response
    axios.get.mockResolvedValue(mockResponse);

    const user = await getUser(1);

    expect(user).toEqual(mockResponse.data);
    // Check if the mocked axios.get was called correctly
    expect(axios.get).toHaveBeenCalledTimes(1);
    expect(axios.get).toHaveBeenCalledWith('/api/users/1');
  });
});

Notice how jest.mock('axios') replaces the need for sinon.stub and manual restore. The mockResolvedValue directly sets the behavior for the mocked axios.get function.

The most common stumbling block is often asynchronous code. Mocha requires done() callbacks or returning promises. Jest handles promises automatically; if your test returns a promise, Jest will wait for it to resolve or reject. If you’re using async/await, it’s even cleaner. Ensure your async tests properly await operations and that expect assertions are made after the awaits.

After migrating, your next step might be exploring Jest’s snapshot testing for UI components or configuration files, or diving deeper into its coverage reporting.