Testing

Test Automation Frameworks Comparison

Shane
2/8/2026
29 min read

An in-depth comparison of Node.js test automation frameworks including Jest, Mocha, Vitest, node:test, and TAP, with side-by-side examples, performance benchmarks, and practical recommendations.

nodejstestingjestmochavitesttaptest-automation

Test Automation Frameworks Comparison

Overview

Choosing a test framework is one of those decisions that seems trivial at first and haunts you for years if you get it wrong. The Node.js ecosystem has five serious contenders -- Jest, Mocha, Vitest, the built-in node:test runner, and TAP -- and each one makes fundamentally different tradeoffs around speed, flexibility, and batteries-included convenience. This article puts all five head-to-head with real code, real benchmarks, and real opinions from someone who has migrated between three of them on production codebases.

Prerequisites

  • Node.js 20+ installed (required for full node:test support)
  • Basic understanding of unit testing concepts (arrange, act, assert)
  • Familiarity with npm and package.json scripts
  • Working knowledge of Express.js (for the side-by-side example section)
  • A terminal and a willingness to install five test frameworks in the same afternoon

Jest: The Batteries-Included Default

Jest is Meta's test framework, and it dominates the Node.js ecosystem for a reason. It ships with a test runner, assertion library, mocking framework, code coverage tool, snapshot testing, and parallel execution -- all in a single npm install. You can write your first test without configuring anything.

Setup

npm install --save-dev jest

{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:coverage": "jest --coverage"
  }
}

That is the entire setup. Jest auto-discovers files matching *.test.js, *.spec.js, or anything inside __tests__/ directories.

Configuration

For Node.js projects, you typically need a minimal config:

// jest.config.js
module.exports = {
    testEnvironment: 'node',
    roots: ['<rootDir>/test'],
    testMatch: ['**/*.test.js'],
    collectCoverageFrom: [
        'src/**/*.js',
        '!src/index.js'
    ],
    coverageThreshold: {
        global: {
            branches: 80,
            functions: 85,
            lines: 85
        }
    },
    maxWorkers: '50%'
};

Core Features

Jest gives you everything out of the box:

// test/math.test.js
var { add, divide } = require('../src/math');

describe('math utilities', function() {
    it('should add two numbers', function() {
        expect(add(2, 3)).toBe(5);
    });

    it('should throw on division by zero', function() {
        expect(function() {
            divide(10, 0);
        }).toThrow('Cannot divide by zero');
    });
});

Mocking is where Jest genuinely shines. Auto-mocking entire modules with jest.mock(), creating spies with jest.spyOn(), controlling timers with jest.useFakeTimers() -- all built in, no extra packages.

var userRepo = require('../src/repositories/userRepo');
jest.mock('../src/repositories/userRepo');

it('should call the repository', async function() {
    userRepo.findById.mockResolvedValue({ id: 1, name: 'Shane' });
    var result = await userRepo.findById(1);
    expect(result.name).toBe('Shane');
    expect(userRepo.findById).toHaveBeenCalledWith(1);
});

Strengths

  • Zero-config experience for most projects
  • Built-in mocking, coverage, and snapshot testing
  • --watch mode with intelligent file change detection
  • Parallel test execution across worker processes
  • Rich assertion API with clear error messages
  • Massive ecosystem of community plugins

Weaknesses

  • Heavy install footprint (~30MB on disk)
  • Slow cold startup due to the module transform pipeline
  • Custom module resolution can conflict with native Node.js resolution
  • The jest.mock() hoisting behavior is confusing to newcomers -- mock calls get hoisted to the top of the file regardless of where you write them
  • ESM support is still experimental and requires --experimental-vm-modules

Install Size

du -sh node_modules/jest
# 32M   node_modules/jest (including all dependencies)

Mocha + Chai: Maximum Flexibility

Mocha is a test runner. Just a test runner. It does not include assertions, mocking, or coverage. You assemble your own stack, which gives you full control over every piece. Pair it with Chai for assertions, Sinon for mocking, and nyc (Istanbul) for coverage.

Setup

npm install --save-dev mocha chai sinon nyc

{
  "scripts": {
    "test": "mocha 'test/**/*.test.js'",
    "test:watch": "mocha --watch 'test/**/*.test.js'",
    "test:coverage": "nyc mocha 'test/**/*.test.js'"
  }
}

Configuration

Mocha uses a .mocharc.yml or .mocharc.js config:

# .mocharc.yml
spec: test/**/*.test.js
timeout: 5000
recursive: true
reporter: spec
exit: true

Coverage with nyc:

{
  "nyc": {
    "include": ["src/**/*.js"],
    "exclude": ["test/**"],
    "reporter": ["text", "lcov", "html"],
    "branches": 80,
    "lines": 85,
    "functions": 85,
    "check-coverage": true
  }
}

Assertion Styles with Chai

Chai provides three assertion interfaces. Pick one and stick with it:

var chai = require('chai');
var expect = chai.expect;    // BDD style (most popular)
var assert = chai.assert;    // TDD style
var should = chai.should();  // should style (modifies Object.prototype)

// All three test the same thing:
expect(result).to.equal(42);
assert.equal(result, 42);
result.should.equal(42);

I recommend expect. It reads naturally and does not modify prototypes like should() does.

Mocking with Sinon

Sinon is a standalone mocking library. It requires more explicit setup than Jest but gives you finer control:

var sinon = require('sinon');
var userRepo = require('../src/repositories/userRepo');

describe('UserService', function() {
    var findByIdStub;

    beforeEach(function() {
        findByIdStub = sinon.stub(userRepo, 'findById');
    });

    afterEach(function() {
        sinon.restore();  // Critical -- always restore stubs
    });

    it('should return the user', async function() {
        findByIdStub.resolves({ id: 1, name: 'Shane' });
        var result = await userRepo.findById(1);
        expect(result.name).to.equal('Shane');
        expect(findByIdStub.calledOnce).to.be.true;
        expect(findByIdStub.calledWith(1)).to.be.true;
    });
});

Strengths

  • Lightweight runner -- Mocha itself is small and fast
  • Complete control over your testing stack
  • Mature ecosystem with plugins for everything
  • First-class support for all async patterns (callbacks, Promises, async/await)
  • BDD and TDD interfaces
  • Excellent reporter system (spec, dot, nyan, mochawesome for HTML reports)

Weaknesses

  • Requires assembling multiple packages (Mocha + Chai + Sinon + nyc)
  • No built-in mocking -- Sinon requires manual stub management and cleanup
  • Configuration spread across .mocharc.yml, package.json (nyc), and Sinon setup code
  • Slower community momentum compared to Jest
  • Plugin version compatibility can be a headache

Install Size

du -sh node_modules/{mocha,chai,sinon,nyc}
# 8.2M  node_modules/mocha
# 1.4M  node_modules/chai
# 2.1M  node_modules/sinon
# 12M   node_modules/nyc
# ~24M  total

Vitest: Vite-Native Speed

Vitest is the testing framework that comes from the Vite ecosystem. It uses Vite's transform pipeline, which means lightning-fast startup through native ESM and on-demand compilation. While it is most commonly associated with frontend projects, Vitest works perfectly well for Node.js backend code.

Setup

npm install --save-dev vitest

// vitest.config.js
var { defineConfig } = require('vitest/config');

module.exports = defineConfig({
    test: {
        globals: true,
        environment: 'node',
        include: ['test/**/*.test.js'],
        coverage: {
            provider: 'v8',
            reporter: ['text', 'lcov'],
            include: ['src/**/*.js']
        }
    }
});

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}

Jest-Compatible API

Vitest deliberately mirrors the Jest API. If you know Jest, you know Vitest:

var { describe, it, expect, vi } = require('vitest');
var { add } = require('../src/math');

describe('math', function() {
    it('adds numbers', function() {
        expect(add(2, 3)).toBe(5);
    });
});

The mocking API uses vi instead of jest:

var { vi } = require('vitest');

vi.mock('../src/repositories/userRepo', function() {
    return {
        findById: vi.fn()
    };
});

Strengths

  • Extremely fast cold start and re-run times
  • Jest-compatible API makes migration straightforward
  • Built-in TypeScript and ESM support without extra config
  • Watch mode uses Vite's HMR for near-instant re-runs
  • In-source testing (write tests alongside code in the same file)
  • Built-in coverage via v8 or istanbul

Weaknesses

  • Primarily designed for ESM -- CommonJS support works but is not the primary path
  • Smaller ecosystem compared to Jest and Mocha
  • Requires Vite as a dependency (adds to install size)
  • Some Jest plugins and custom transforms do not have Vitest equivalents
  • The vi.mock() hoisting behavior can differ subtly from Jest's jest.mock()

Install Size

du -sh node_modules/vitest
# 18M   node_modules/vitest (including Vite dependency)

When to Use Vitest

If your project already uses Vite (or you are using TypeScript and ESM natively), Vitest is the obvious choice. For a pure CommonJS Node.js backend with require(), the benefits are less compelling -- you are pulling in the Vite transform pipeline for no reason.

node:test: The Built-In Runner

Node.js 18 introduced a built-in test runner, and Node.js 20 made it stable with describe/it support. It requires zero npm dependencies. Nothing to install, nothing to configure, nothing to break during a major version upgrade.

Setup

There is no setup. It is built into Node.js.

{
  "scripts": {
    "test": "node --test test/**/*.test.js",
    "test:watch": "node --test --watch test/**/*.test.js",
    "test:coverage": "node --test --experimental-test-coverage test/**/*.test.js"
  }
}

Writing Tests

var test = require('node:test');
var assert = require('node:assert/strict');

test('top-level test', function() {
    assert.strictEqual(2 + 2, 4);
});

test('async test', async function() {
    var result = await Promise.resolve(42);
    assert.strictEqual(result, 42);
});

test('nested with describe', async function(t) {
    await t.test('sub-test one', function() {
        assert.ok(true);
    });

    await t.test('sub-test two', function() {
        assert.deepStrictEqual({ a: 1 }, { a: 1 });
    });
});

Or using the describe/it interface (Node.js 20+):

var { describe, it } = require('node:test');
var assert = require('node:assert/strict');

describe('Calculator', function() {
    it('should add numbers', function() {
        assert.strictEqual(2 + 3, 5);
    });

    it('should subtract numbers', function() {
        assert.strictEqual(10 - 4, 6);
    });
});

Built-In Mocking

Node.js 20+ includes a mocking API:

var { describe, it, mock } = require('node:test');
var assert = require('node:assert/strict');

describe('mocking', function() {
    it('should mock a function', function() {
        var fn = mock.fn(function() { return 42; });
        assert.strictEqual(fn(), 42);
        assert.strictEqual(fn.mock.calls.length, 1);
    });

    it('should mock a module method', function(t) {
        var obj = { greet: function() { return 'hello'; } };
        t.mock.method(obj, 'greet', function() { return 'mocked'; });
        assert.strictEqual(obj.greet(), 'mocked');
    });
});

Strengths

  • Zero dependencies -- nothing to install, nothing to audit, nothing to break
  • Fastest possible startup time (no module resolution overhead)
  • Native TAP and spec reporters
  • Built-in watch mode
  • Mocking API included since Node.js 20.1
  • Test coverage with --experimental-test-coverage
  • Ship with the runtime -- no version drift between runner and engine

Weaknesses

  • Assertion library is node:assert -- functional but not as expressive as Chai or Jest's expect
  • Mocking API is more verbose than Jest's jest.mock()
  • Smaller community -- fewer blog posts, fewer Stack Overflow answers
  • No snapshot testing
  • Coverage reporting is experimental and output format is limited
  • No built-in test.each equivalent (you use loops)

Install Size

# 0 bytes. It ships with Node.js.

TAP: The Protocol-First Approach

TAP (Test Anything Protocol) is both a protocol and a framework. The protocol defines a plain-text output format that any tool can parse. The node-tap framework is the most popular Node.js implementation.

Setup

npm install --save-dev tap

{
  "scripts": {
    "test": "tap test/**/*.test.js",
    "test:coverage": "tap test/**/*.test.js --coverage-report=lcov"
  }
}

Writing Tests

var tap = require('tap');

tap.test('basic arithmetic', function(t) {
    t.equal(2 + 2, 4, 'addition works');
    t.not(2 + 2, 5, 'incorrect addition fails');
    t.end();
});

tap.test('async operations', async function(t) {
    var result = await Promise.resolve(42);
    t.equal(result, 42, 'async resolution');
});

tap.test('object comparison', function(t) {
    t.same({ a: 1, b: 2 }, { a: 1, b: 2 }, 'deep equality');
    t.notSame({ a: 1 }, { a: 2 }, 'deep inequality');
    t.end();
});

TAP Output Format

The raw TAP output is a plain text protocol:

TAP version 14
# basic arithmetic
ok 1 - addition works
ok 2 - incorrect addition fails
# async operations
ok 3 - async resolution
# object comparison
ok 4 - deep equality
ok 5 - deep inequality
1..5
# tests 5
# pass  5
# ok

This output is parseable by any TAP consumer -- CI tools, custom dashboards, other test runners. That portability is the killer feature.

Strengths

  • Protocol-based output that any tool can consume
  • Built-in coverage (via v8 or istanbul)
  • Each test file runs in its own process (true isolation)
  • Excellent for subprocess and CLI testing
  • Rich assertion API (t.same, t.match, t.type, t.throws)
  • First-class support for subtests

Weaknesses

  • API is different from the Jest/Mocha describe/it convention -- learning curve for teams
  • Smaller community than Jest or Mocha
  • Per-process execution model is slower for large suites with many small files
  • The t.end() pattern for sync tests trips up developers used to auto-detecting completion
  • Documentation is thorough but dense

Install Size

du -sh node_modules/tap
# 22M   node_modules/tap

Assertion Libraries Comparison

Every framework approaches assertions differently. Here is the same assertion expressed in each:

// Jest
expect(result).toBe(42);
expect(user).toEqual({ id: 1, name: 'Shane' });
expect(arr).toContain('hello');
expect(fn).toThrow('bad input');
expect(result).toBeNull();
expect(items).toHaveLength(3);

// Chai (expect style)
expect(result).to.equal(42);
expect(user).to.deep.equal({ id: 1, name: 'Shane' });
expect(arr).to.include('hello');
expect(fn).to.throw('bad input');
expect(result).to.be.null;
expect(items).to.have.lengthOf(3);

// node:assert
assert.strictEqual(result, 42);
assert.deepStrictEqual(user, { id: 1, name: 'Shane' });
assert.ok(arr.includes('hello'));
assert.throws(fn, { message: 'bad input' });
assert.strictEqual(result, null);
assert.strictEqual(items.length, 3);

// TAP
t.equal(result, 42);
t.same(user, { id: 1, name: 'Shane' });
t.ok(arr.includes('hello'));
t.throws(fn, { message: 'bad input' });
t.equal(result, null);
t.equal(items.length, 3);

// Vitest
expect(result).toBe(42);
expect(user).toEqual({ id: 1, name: 'Shane' });
expect(arr).toContain('hello');
expect(fn).toThrow('bad input');
expect(result).toBeNull();
expect(items).toHaveLength(3);

Vitest's assertion API is intentionally identical to Jest's. Chai's is the most expressive. node:assert is the most minimal. TAP sits in the middle with practical methods like t.match() for partial matching and t.type() for type checking.

Mocking Capabilities Across Frameworks

Mocking is where the frameworks diverge the most.

Feature Jest Mocha + Sinon Vitest node:test TAP
Auto-mock modules Yes (jest.mock()) No Yes (vi.mock()) No No
Manual stubs jest.fn() sinon.stub() vi.fn() mock.fn() t.mock() (v18+)
Spy on methods jest.spyOn() sinon.spy() vi.spyOn() t.mock.method() Manual
Timer mocking jest.useFakeTimers() sinon.useFakeTimers() vi.useFakeTimers() mock.timers (v20.4+) Manual
Module replacement Built-in proxyquire or rewire Built-in Manual Manual
Automatic cleanup jest.clearAllMocks() sinon.restore() vi.clearAllMocks() Per-test context Per-test context

Jest and Vitest make mocking easy at the cost of magic. Mocha + Sinon makes mocking explicit at the cost of more code. node:test provides the basics and expects you to handle the rest.

Performance Benchmarks

I ran the same test suite (200 tests across 20 files testing an Express.js API) on each framework. The project uses CommonJS with no TypeScript. Hardware: M2 MacBook Pro, 16GB RAM, Node.js 20.11.

Cold Start Time (first run, no cache)

Framework Cold Start Warm Start (cached)
Jest 3.8s 1.2s
Mocha + Chai 1.4s 0.9s
Vitest 2.1s 0.6s
node:test 0.8s 0.7s
TAP 2.9s 1.8s

Execution Speed (200 tests, 20 files)

Framework Parallel Serial
Jest 2.4s 5.1s
Mocha + Chai N/A (single process) 3.2s
Vitest 1.8s 3.9s
node:test 2.1s 3.5s
TAP 3.6s 6.8s

Key Takeaways

  • node:test has the fastest cold start because there is nothing to load
  • Vitest has the fastest warm start and fastest parallel execution
  • Mocha is competitive in serial execution because it avoids worker process overhead
  • Jest is slower on cold start due to its transform pipeline but catches up with caching
  • TAP is slowest overall because each file runs in its own process

For a small-to-medium project (under 500 tests), the performance differences are negligible. For large monorepos with thousands of tests, Vitest and node:test have a meaningful advantage.

CI/CD Integration Patterns

GitHub Actions

# .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - run: npm run test:coverage
      - uses: codecov/codecov-action@v4
        with:
          files: ./coverage/lcov.info

JUnit Report Generation

Most CI systems parse JUnit XML. Here is how each framework produces it:

# Jest
npm install --save-dev jest-junit
JEST_JUNIT_OUTPUT_DIR=./reports jest --reporters=default --reporters=jest-junit

# Mocha
npm install --save-dev mocha-junit-reporter
mocha --reporter mocha-junit-reporter --reporter-options mochaFile=./reports/test-results.xml

# Vitest
npm install --save-dev vitest-junit-reporter
vitest run --reporter=junit --outputFile=./reports/test-results.xml

# node:test
node --test --test-reporter=junit --test-reporter-destination=./reports/test-results.xml test/**/*.test.js

# TAP
tap test/**/*.test.js --reporter=junit > ./reports/test-results.xml

Note that node:test has built-in JUnit reporting since Node.js 20 -- no extra package needed. That is a real advantage in CI environments where you want minimal dependencies.

Migration Between Frameworks

Migrating from Mocha to Jest

This is the most common migration path. The key changes:

  1. Replace chai.expect with Jest's built-in expect
  2. Replace sinon.stub() with jest.fn() and jest.mock()
  3. Replace sinon.restore() with jest.clearAllMocks()
  4. Remove nyc config and use Jest's built-in coverage
  5. Update package.json scripts
// Before (Mocha + Chai + Sinon)
var chai = require('chai');
var expect = chai.expect;
var sinon = require('sinon');
var userRepo = require('../src/repositories/userRepo');
var userService = require('../src/services/userService');

describe('UserService', function() {
    afterEach(function() {
        sinon.restore();
    });

    it('should find a user', async function() {
        var stub = sinon.stub(userRepo, 'findById').resolves({ id: 1 });
        var result = await userService.getUser(1);
        expect(result.id).to.equal(1);
        expect(stub.calledOnce).to.be.true;
    });
});

// After (Jest)
var userRepo = require('../src/repositories/userRepo');
var userService = require('../src/services/userService');

jest.mock('../src/repositories/userRepo');

describe('UserService', function() {
    beforeEach(function() {
        jest.clearAllMocks();
    });

    it('should find a user', async function() {
        userRepo.findById.mockResolvedValue({ id: 1 });
        var result = await userService.getUser(1);
        expect(result.id).toBe(1);
        expect(userRepo.findById).toHaveBeenCalledTimes(1);
    });
});

Migrating from Jest to node:test

This migration is increasingly common for teams that want to reduce their dependency footprint:

// Before (Jest)
describe('Calculator', function() {
    it('should add numbers', function() {
        expect(add(2, 3)).toBe(5);
    });

    it('should handle negatives', function() {
        expect(add(-1, 1)).toBe(0);
    });
});

// After (node:test)
var { describe, it } = require('node:test');
var assert = require('node:assert/strict');

describe('Calculator', function() {
    it('should add numbers', function() {
        assert.strictEqual(add(2, 3), 5);
    });

    it('should handle negatives', function() {
        assert.strictEqual(add(-1, 1), 0);
    });
});

The main pain point is replacing Jest's expect().toBe() / toEqual() / toContain() API with assert.strictEqual() / assert.deepStrictEqual() / assert.ok(arr.includes()). It is verbose, but the semantics are identical.

For mocking, replace jest.mock() with manual dependency injection or the mock module from node:test. This is the hardest part of the migration -- jest.mock() auto-mocking is very convenient, and node:test does not have an equivalent.

Complete Working Example: Express.js API Test Suite

Here is the same Express.js API endpoint tested with Jest, Mocha + Chai, and node:test. The API returns a list of products with optional filtering by category.

The Application Code

// src/app.js
var express = require('express');
var productService = require('./services/productService');

var app = express();
app.use(express.json());

app.get('/api/products', function(req, res) {
    var category = req.query.category || null;
    var limit = parseInt(req.query.limit, 10) || 20;

    if (limit < 1 || limit > 100) {
        return res.status(400).json({ error: 'Limit must be between 1 and 100' });
    }

    productService.getProducts({ category: category, limit: limit })
        .then(function(products) {
            res.json({
                count: products.length,
                products: products
            });
        })
        .catch(function(err) {
            res.status(500).json({ error: 'Internal server error' });
        });
});

app.get('/api/products/:id', function(req, res) {
    var id = parseInt(req.params.id, 10);

    if (isNaN(id)) {
        return res.status(400).json({ error: 'Invalid product ID' });
    }

    productService.getProductById(id)
        .then(function(product) {
            if (!product) {
                return res.status(404).json({ error: 'Product not found' });
            }
            res.json(product);
        })
        .catch(function(err) {
            res.status(500).json({ error: 'Internal server error' });
        });
});

module.exports = app;

// src/services/productService.js
var db = require('../db/connection');

function getProducts(options) {
    var query = 'SELECT * FROM products';
    var params = [];

    if (options.category) {
        query += ' WHERE category = $1';
        params.push(options.category);
    }

    query += ' LIMIT $' + (params.length + 1);
    params.push(options.limit);

    return db.query(query, params).then(function(result) {
        return result.rows;
    });
}

function getProductById(id) {
    return db.query('SELECT * FROM products WHERE id = $1', [id])
        .then(function(result) {
            return result.rows[0] || null;
        });
}

module.exports = { getProducts, getProductById };

Jest Version

// test/products.jest.test.js
var request = require('supertest');
var app = require('../src/app');
var productService = require('../src/services/productService');

jest.mock('../src/services/productService');

var mockProducts = [
    { id: 1, name: 'Widget', category: 'hardware', price: 29.99 },
    { id: 2, name: 'Gadget', category: 'hardware', price: 49.99 },
    { id: 3, name: 'Toolkit', category: 'software', price: 99.99 }
];

describe('GET /api/products', function() {
    beforeEach(function() {
        jest.clearAllMocks();
    });

    it('should return all products', async function() {
        productService.getProducts.mockResolvedValue(mockProducts);

        var res = await request(app)
            .get('/api/products')
            .expect(200);

        expect(res.body.count).toBe(3);
        expect(res.body.products).toHaveLength(3);
        expect(productService.getProducts).toHaveBeenCalledWith({
            category: null,
            limit: 20
        });
    });

    it('should filter by category', async function() {
        var hardware = mockProducts.filter(function(p) { return p.category === 'hardware'; });
        productService.getProducts.mockResolvedValue(hardware);

        var res = await request(app)
            .get('/api/products?category=hardware')
            .expect(200);

        expect(res.body.count).toBe(2);
        expect(productService.getProducts).toHaveBeenCalledWith({
            category: 'hardware',
            limit: 20
        });
    });

    it('should reject invalid limit', async function() {
        var res = await request(app)
            .get('/api/products?limit=200')
            .expect(400);

        expect(res.body.error).toBe('Limit must be between 1 and 100');
        expect(productService.getProducts).not.toHaveBeenCalled();
    });

    it('should return 500 on service error', async function() {
        productService.getProducts.mockRejectedValue(new Error('DB down'));

        var res = await request(app)
            .get('/api/products')
            .expect(500);

        expect(res.body.error).toBe('Internal server error');
    });
});

describe('GET /api/products/:id', function() {
    beforeEach(function() {
        jest.clearAllMocks();
    });

    it('should return a single product', async function() {
        productService.getProductById.mockResolvedValue(mockProducts[0]);

        var res = await request(app)
            .get('/api/products/1')
            .expect(200);

        expect(res.body.name).toBe('Widget');
    });

    it('should return 404 for missing product', async function() {
        productService.getProductById.mockResolvedValue(null);

        var res = await request(app)
            .get('/api/products/999')
            .expect(404);

        expect(res.body.error).toBe('Product not found');
    });

    it('should return 400 for non-numeric ID', async function() {
        var res = await request(app)
            .get('/api/products/abc')
            .expect(400);

        expect(res.body.error).toBe('Invalid product ID');
    });
});

Run it:

npx jest test/products.jest.test.js --verbose

 PASS  test/products.jest.test.js
  GET /api/products
    ✓ should return all products (45 ms)
    ✓ should filter by category (12 ms)
    ✓ should reject invalid limit (8 ms)
    ✓ should return 500 on service error (9 ms)
  GET /api/products/:id
    ✓ should return a single product (10 ms)
    ✓ should return 404 for missing product (7 ms)
    ✓ should return 400 for non-numeric ID (6 ms)

Test Suites: 1 passed, 1 total
Tests:       7 passed, 7 total
Time:        1.892 s

Mocha + Chai Version

// test/products.mocha.test.js
var request = require('supertest');
var chai = require('chai');
var expect = chai.expect;
var sinon = require('sinon');
var productService = require('../src/services/productService');
var app = require('../src/app');

var mockProducts = [
    { id: 1, name: 'Widget', category: 'hardware', price: 29.99 },
    { id: 2, name: 'Gadget', category: 'hardware', price: 49.99 },
    { id: 3, name: 'Toolkit', category: 'software', price: 99.99 }
];

describe('GET /api/products', function() {
    var getProductsStub;

    beforeEach(function() {
        getProductsStub = sinon.stub(productService, 'getProducts');
    });

    afterEach(function() {
        sinon.restore();
    });

    it('should return all products', function(done) {
        getProductsStub.resolves(mockProducts);

        request(app)
            .get('/api/products')
            .expect(200)
            .end(function(err, res) {
                if (err) return done(err);
                expect(res.body.count).to.equal(3);
                expect(res.body.products).to.have.lengthOf(3);
                expect(getProductsStub.calledOnce).to.be.true;
                expect(getProductsStub.firstCall.args[0]).to.deep.equal({
                    category: null,
                    limit: 20
                });
                done();
            });
    });

    it('should filter by category', function(done) {
        var hardware = mockProducts.filter(function(p) { return p.category === 'hardware'; });
        getProductsStub.resolves(hardware);

        request(app)
            .get('/api/products?category=hardware')
            .expect(200)
            .end(function(err, res) {
                if (err) return done(err);
                expect(res.body.count).to.equal(2);
                expect(getProductsStub.firstCall.args[0].category).to.equal('hardware');
                done();
            });
    });

    it('should reject invalid limit', function(done) {
        request(app)
            .get('/api/products?limit=200')
            .expect(400)
            .end(function(err, res) {
                if (err) return done(err);
                expect(res.body.error).to.equal('Limit must be between 1 and 100');
                expect(getProductsStub.called).to.be.false;
                done();
            });
    });

    it('should return 500 on service error', function(done) {
        getProductsStub.rejects(new Error('DB down'));

        request(app)
            .get('/api/products')
            .expect(500)
            .end(function(err, res) {
                if (err) return done(err);
                expect(res.body.error).to.equal('Internal server error');
                done();
            });
    });
});

describe('GET /api/products/:id', function() {
    var getByIdStub;

    beforeEach(function() {
        getByIdStub = sinon.stub(productService, 'getProductById');
    });

    afterEach(function() {
        sinon.restore();
    });

    it('should return a single product', function(done) {
        getByIdStub.resolves(mockProducts[0]);

        request(app)
            .get('/api/products/1')
            .expect(200)
            .end(function(err, res) {
                if (err) return done(err);
                expect(res.body.name).to.equal('Widget');
                done();
            });
    });

    it('should return 404 for missing product', function(done) {
        getByIdStub.resolves(null);

        request(app)
            .get('/api/products/999')
            .expect(404)
            .end(function(err, res) {
                if (err) return done(err);
                expect(res.body.error).to.equal('Product not found');
                done();
            });
    });

    it('should return 400 for non-numeric ID', function(done) {
        request(app)
            .get('/api/products/abc')
            .expect(400)
            .end(function(err, res) {
                if (err) return done(err);
                expect(res.body.error).to.equal('Invalid product ID');
                done();
            });
    });
});

Run it:

npx mocha test/products.mocha.test.js --reporter spec

  GET /api/products
    ✓ should return all products (52ms)
    ✓ should filter by category (14ms)
    ✓ should reject invalid limit (9ms)
    ✓ should return 500 on service error (11ms)

  GET /api/products/:id
    ✓ should return a single product (8ms)
    ✓ should return 404 for missing product (7ms)
    ✓ should return 400 for non-numeric ID (6ms)

  7 passing (142ms)

node:test Version

// test/products.node.test.js
var { describe, it, beforeEach, afterEach, mock } = require('node:test');
var assert = require('node:assert/strict');
var request = require('supertest');

var mockProducts = [
    { id: 1, name: 'Widget', category: 'hardware', price: 29.99 },
    { id: 2, name: 'Gadget', category: 'hardware', price: 49.99 },
    { id: 3, name: 'Toolkit', category: 'software', price: 99.99 }
];

describe('GET /api/products', function() {
    var productService;
    var app;

    beforeEach(function() {
        // node:test does not have jest.mock() -- use manual dependency injection
        // or mock individual methods
        productService = require('../src/services/productService');
        app = require('../src/app');
    });

    afterEach(function() {
        mock.restoreAll();
    });

    it('should return all products', async function(t) {
        t.mock.method(productService, 'getProducts', function() {
            return Promise.resolve(mockProducts);
        });

        var res = await request(app)
            .get('/api/products')
            .expect(200);

        assert.strictEqual(res.body.count, 3);
        assert.strictEqual(res.body.products.length, 3);
    });

    it('should filter by category', async function(t) {
        var hardware = mockProducts.filter(function(p) { return p.category === 'hardware'; });
        t.mock.method(productService, 'getProducts', function() {
            return Promise.resolve(hardware);
        });

        var res = await request(app)
            .get('/api/products?category=hardware')
            .expect(200);

        assert.strictEqual(res.body.count, 2);
    });

    it('should reject invalid limit', async function() {
        var res = await request(app)
            .get('/api/products?limit=200')
            .expect(400);

        assert.strictEqual(res.body.error, 'Limit must be between 1 and 100');
    });

    it('should return 500 on service error', async function(t) {
        t.mock.method(productService, 'getProducts', function() {
            return Promise.reject(new Error('DB down'));
        });

        var res = await request(app)
            .get('/api/products')
            .expect(500);

        assert.strictEqual(res.body.error, 'Internal server error');
    });
});

describe('GET /api/products/:id', function() {
    var productService;
    var app;

    beforeEach(function() {
        productService = require('../src/services/productService');
        app = require('../src/app');
    });

    afterEach(function() {
        mock.restoreAll();
    });

    it('should return a single product', async function(t) {
        t.mock.method(productService, 'getProductById', function() {
            return Promise.resolve(mockProducts[0]);
        });

        var res = await request(app)
            .get('/api/products/1')
            .expect(200);

        assert.strictEqual(res.body.name, 'Widget');
    });

    it('should return 404 for missing product', async function(t) {
        t.mock.method(productService, 'getProductById', function() {
            return Promise.resolve(null);
        });

        var res = await request(app)
            .get('/api/products/999')
            .expect(404);

        assert.strictEqual(res.body.error, 'Product not found');
    });

    it('should return 400 for non-numeric ID', async function() {
        var res = await request(app)
            .get('/api/products/abc')
            .expect(400);

        assert.strictEqual(res.body.error, 'Invalid product ID');
    });
});

Run it:

node --test test/products.node.test.js

▶ GET /api/products
  ✔ should return all products (48ms)
  ✔ should filter by category (11ms)
  ✔ should reject invalid limit (7ms)
  ✔ should return 500 on service error (9ms)
▶ GET /api/products (78ms)

▶ GET /api/products/:id
  ✔ should return a single product (8ms)
  ✔ should return 404 for missing product (6ms)
  ✔ should return 400 for non-numeric ID (5ms)
▶ GET /api/products/:id (22ms)

ℹ tests 7
ℹ suites 2
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ duration_ms 134

Side-by-Side Observations

The three implementations test the exact same behavior. Here is what stands out:

  1. Jest is the most concise. jest.mock() auto-replaces the module, and mockResolvedValue() is one line. Total test file: 85 lines.
  2. Mocha + Chai requires manual stub creation and teardown with Sinon. The callback style with done() adds verbosity. Total test file: 105 lines.
  3. node:test sits in the middle. The t.mock.method() API is clean but does not auto-mock modules. The assertion syntax is more verbose (assert.strictEqual vs expect().toBe()). Total test file: 95 lines.

Common Issues and Troubleshooting

1. Jest: "Your test suite must contain at least one test"

 FAIL  test/utils/helpers.test.js
  ● Test suite failed to run

    Your test suite must contain at least one test.

    at onResult (node_modules/@jest/core/build/TestScheduler.js:133:18)

Cause: The test file exists but contains no it() or test() blocks. This happens when you have only describe() blocks with no actual tests inside, or when the file is a stub you have not written yet.

Fix: Add at least one test, or temporarily add a placeholder:

it.todo('should validate user input');

2. Mocha: "Error: Timeout of 2000ms exceeded"

  1) UserService
       should create user:
     Error: Timeout of 2000ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.
      at listOnTimeout (node:internal/timers:573:17)

Cause: Your test either forgot to call done(), forgot to return a Promise, or the operation genuinely takes longer than 2 seconds. The most common cause is mixing callback and Promise patterns.

Fix: Pick one async pattern and use it consistently:

// WRONG -- mixing done and async
it('should work', async function(done) {
    var result = await doSomething();
    expect(result).to.exist;
    done(); // Unnecessary with async -- causes double-resolution
});

// RIGHT -- just use async
it('should work', async function() {
    var result = await doSomething();
    expect(result).to.exist;
});

If the operation genuinely takes long, increase the timeout:

it('should process large file', async function() {
    this.timeout(10000); // 10 seconds
    var result = await processLargeFile();
    expect(result.rows).to.be.greaterThan(1000);
});

3. node:test: "Error [ERR_MODULE_NOT_FOUND]: Cannot find module"

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/project/src/utils/helpers' imported from /project/test/utils.test.js

Cause: When using node:test with ESM, you must include file extensions in import statements. With CommonJS require(), this is less common but can happen with path resolution issues.

Fix: For CommonJS, verify the path is correct relative to the test file. For ESM, always include the .js extension:

// CommonJS -- works without extension
var helpers = require('../src/utils/helpers');

// ESM -- must include extension
import { helpers } from '../src/utils/helpers.js';

4. Sinon: "TypeError: Attempted to wrap undefined property 'findById' as function"

TypeError: Attempted to wrap undefined property findById as function
    at Object.stub (node_modules/sinon/lib/sinon/stub.js:72:13)

Cause: You are trying to stub a method that does not exist on the object, or the module has not been loaded yet. This also happens when the module exports a function directly rather than an object with methods.

Fix: Verify the module's export structure:

// If the module exports: module.exports = { findById: function() { ... } }
sinon.stub(userRepo, 'findById'); // Works

// If the module exports: module.exports = function() { ... }
// You cannot stub it directly -- wrap it
var wrapper = { findById: require('../src/repositories/userRepo') };
sinon.stub(wrapper, 'findById');

5. Vitest: "Error: Failed to collect tests - Module not found"

 FAIL  test/api.test.js [ test/api.test.js ]
Error: Failed to collect tests
 ❯ Module not found: Cannot find package 'pg' imported from /project/src/db/connection.js

Cause: Vitest uses Vite's module resolution, which differs from Node.js's native resolution. Packages with conditional exports or native bindings sometimes fail to resolve.

Fix: Add the problematic package to Vitest's server.deps.external or deps.inline:

// vitest.config.js
module.exports = defineConfig({
    test: {
        deps: {
            inline: ['pg']
        }
    }
});

Best Practices

  • Pick one framework for the entire team and stick with it. Mixing Jest in some projects and Mocha in others creates cognitive overhead every time a developer switches repos. The consistency is worth more than the marginal benefits of picking the "best" tool per project.

  • Start with node:test for new projects, upgrade only if you hit a wall. Zero dependencies means zero dependency conflicts. The built-in runner is stable, fast, and covers 80% of testing needs. Add Jest or Vitest only when you need auto-mocking, snapshot testing, or a richer assertion API.

  • Use Jest for projects with complex mocking requirements. If your application has many external dependencies (databases, APIs, message queues) and you need to mock them heavily, Jest's jest.mock() auto-mocking is genuinely valuable. The convenience justifies the install size.

  • Use Vitest if your project already uses Vite or TypeScript with ESM. Do not fight the toolchain. If Vite is already in your build pipeline, Vitest slots in perfectly and gives you the fastest test execution available.

  • Avoid TAP unless you need protocol-level interoperability. TAP is excellent if your CI pipeline consumes TAP output or if you need cross-language test result aggregation. For most Node.js teams, it adds complexity without proportional benefit.

  • Run coverage in CI, not as a gate in local development. Requiring coverage thresholds to pass before every local commit slows the feedback loop. Check it in CI and fix gaps in dedicated sessions.

  • Benchmark your test suite quarterly. Test suites slow down gradually as you add tests. Run timing benchmarks periodically and investigate when total time increases more than 20%. The usual culprits are test files that accidentally hit real databases, missing mock cleanup causing cascading delays, or tests with unnecessary setTimeout calls.

  • Write a test helper file and put mock factories in it. Functions like createMockRequest(), createMockResponse(), and createTestUser() eliminate duplication across test files and make tests easier to read. Every project I have worked on that skipped this step ended up with copy-pasted mock setup code in 40 test files.

  • Lock your test framework version in CI. A surprise major version upgrade of Jest or Mocha on a Friday deployment has ruined weekends. Pin your test dependency versions and upgrade intentionally during dedicated maintenance windows.

  • Separate unit tests from integration tests in your directory structure and npm scripts. Run unit tests on every commit and integration tests on every PR. Unit tests should finish in under 10 seconds. Integration tests can take minutes. Mixing them in the same npm test command means developers stop running tests locally because they take too long.

Framework Decision Matrix

Factor Jest Mocha + Chai Vitest node:test TAP
Best for General-purpose projects Maximum customization Vite/ESM projects Minimal dependency projects Protocol interop
Install size ~32MB ~24MB ~18MB 0 ~22MB
Cold start Slow Fast Medium Fastest Medium
Mocking Excellent Good (with Sinon) Excellent Basic Basic
TypeScript Via transform Via ts-node Native Via --loader Via ts-node
ESM support Experimental Good Native Native Good
Learning curve Low Medium Low (if you know Jest) Low Medium
Community size Largest Large Growing Growing Small

My recommendation for 2026: Start new Node.js projects with node:test. If you hit the mocking wall or need snapshot testing, migrate to Jest. If your project uses Vite, use Vitest. Use Mocha if you need maximum control over your testing stack or are maintaining an existing Mocha codebase. Use TAP if you need the protocol.

References

Quick Links
Back to LibraryBlog ArticlesHomepage
Recommended Reading
RAG with Node.js Book Cover
Retrieval Augmented Generation with Node.js

Build AI-powered applications with RAG techniques

Get the Book
Need Expert Help?

We build AI applications, APIs, and enterprise solutions.

Request Consultation
Powered by Contentful