Node.js Unit Testing with Mocha, Chai & Sinon

Why Unit Testing Matters for Node.js

Unit testing forms the foundation of reliable software development. When building Node.js applications, comprehensive unit tests catch bugs early, enable confident refactoring, and serve as living documentation for expected behavior. Our web development team follows these testing practices to deliver maintainable codebases.

Key benefits include:

• Early bug detection - Issues found during development cost less to fix
• Confidence in changes - Refactor safely knowing tests will catch regressions
• Better code design - Testable code typically has better separation of concerns
• Faster development - Tests provide quick feedback loops during implementation

The Testing Pyramid

Unit tests form the broad base of the testing pyramid, offering the fastest execution and highest coverage potential. Above them sit integration tests verifying component interactions, while end-to-end tests validate complete user flows. A healthy testing strategy prioritizes unit tests while maintaining smaller numbers of integration and E2E tests. For a broader comparison of testing frameworks, see our guide on comparing Node.js unit testing frameworks.

Getting Started with Mocha

Mocha provides the structural framework for organizing and running tests. Its flexibility allows you to write tests in a way that matches your project's needs, whether you're working with Node.js backend code or browser-based JavaScript. This framework pairs excellently with our custom API development services for comprehensive backend testing.

Basic Installation

npm install --save-dev mocha

Test Structure

Mocha uses a descriptive hierarchy to organize tests. The describe function groups related tests, while it contains individual test cases with specific expectations.

describe('User Service', function() {
 describe('#createUser', function() {
 it('should create a user with valid data', function() {
 const user = userService.create({ name: 'John', email: '[email protected]' });
 expect(user).to.have.property('id');
 expect(user.name).to.equal('John');
 });

 it('should reject invalid email addresses', function() {
 expect(() => {
 userService.create({ email: 'invalid' });
 }).to.throw(Error);
 });
 });
});

Hook Functions for Setup

Mocha provides lifecycle hooks for managing test setup and cleanup. These hooks help reduce duplication and ensure consistent state across tests.

• before() - Runs once before all tests in the suite
• beforeEach() - Runs before each test, ideal for resetting state
• after() - Runs once after all tests complete
• afterEach() - Runs after each test, useful for cleanup

describe('Database Repository', function() {
 beforeEach(async function() {
 await db.clear();
 await db.seed(testData);
 });

 afterEach(async function() {
 await db.disconnect();
 });
});

Writing Clear Assertions with Chai

Chai complements Mocha by providing readable, expressive assertions. The library offers three assertion styles, with Expect (BDD-style) being the most popular among modern JavaScript developers.

Installing Chai

npm install --save-dev chai

Expect Style (Recommended)

The Expect interface uses chainable language that reads like natural English:

const { expect } = require('chai');

describe('User Model', function() {
 it('should have correct properties and types', function() {
 const user = new User({ name: 'Alice', email: '[email protected]', age: 30 });

 expect(user).to.have.property('name');
 expect(user.name).to.equal('Alice');
 expect(user.email).to.be.a('string');
 expect(user.age).to.be.a('number');
 expect(user).to.be.an.instanceof(User);
 });

 it('should validate email format', function() {
 const user = new User({ email: '[email protected]' });
 expect(user.isValidEmail()).to.be.true;
 });

 it('should handle array operations', function() {
 const tags = ['javascript', 'testing', 'node'];
 expect(tags).to.include('testing');
 expect(tags).to.have.lengthOf(3);
 expect(tags[0]).to.equal('javascript');
 });
});

Common Assertions Reference

Mocking with Sinon: Spies, Stubs, and Mocks

Sinon.js provides the mocking capabilities essential for isolating unit tests. By replacing external dependencies with test doubles, you can test your code in complete isolation from databases, APIs, and other services. This is particularly valuable when building cloud-native solutions that integrate with multiple third-party services.

Installing Sinon

npm install --save-dev sinon

Spies: Observing Function Behavior

Spies wrap existing functions to track how they're called without changing their behavior. Use spies when you need to verify that a function was invoked with specific arguments.

const sinon = require('sinon');

describe('OrderController', function() {
 it('should call orderService.create with correct data', function() {
 const orderService = {
 create: function(data) { return Promise.resolve(data); }
 };
 const createSpy = sinon.spy(orderService, 'create');

 const controller = new OrderController(orderService);
 controller.processOrder({ itemId: 'item-123', quantity: 2 });

 sinon.assert.calledOnce(createSpy);
 sinon.assert.calledWith(createSpy, { itemId: 'item-123', quantity: 2 });
 expect(createSpy.firstCall.args[0].itemId).to.equal('item-123');
 });

 it('should log when order is processed', function() {
 const logger = { info: sinon.spy() };
 const controller = new OrderController(orderService, logger);

 controller.processOrder({ itemId: 'item-456' });

 sinon.assert.calledOnce(logger.info);
 expect(logger.info.firstCall.args[0]).to.include('Order processed');
 });
});

Spy assertion methods:

• sinon.assert.calledOnce(spy) - Verify function called exactly once
• sinon.assert.calledWith(spy, args) - Verify function called with specific arguments
• sinon.assert.notCalled(spy) - Verify function never called
• spy.called - Boolean check if spy was called
• spy.callCount - Number of times spy was called

Stubs: Replacing Function Behavior

Stubs completely replace functions with pre-programmed behavior. This is essential when you need to control what happens when dependencies are called, such as simulating API failures or returning specific test data.

describe('PaymentProcessor', function() {
 beforeEach(function() {
 this.paymentGateway = {
 process: sinon.stub().resolves({ status: 'success', transactionId: 'txn_123' }),
 refund: sinon.stub().resolves({ status: 'refunded' })
 };
 this.processor = new PaymentProcessor(this.paymentGateway);
 });

 it('should process payment successfully', async function() {
 const result = await this.processor.charge(99.99);

 expect(result.status).to.equal('success');
 expect(result.transactionId).to.equal('txn_123');
 sinon.assert.calledOnce(this.paymentGateway.process);
 });

 it('should handle payment failure gracefully', async function() {
 this.paymentGateway.process.rejects(new Error('Card declined'));

 await expect(this.processor.charge(50))
 .to.be.rejectedWith('Payment failed: Card declined');
 });

 it('should attempt refund on failed order', async function() {
 this.paymentGateway.process.rejects(new Error('Insufficient funds'));

 try {
 await this.processor.charge(25);
 } catch (e) {
 // Expected - refund should still be called
 sinon.assert.calledOnce(this.paymentGateway.refund);
 }
 });
});

Stub configuration methods:

• .resolves(value) - Return a Promise that resolves
• .rejects(error) - Return a Promise that rejects
• .callsFake(fn) - Call a custom function
• .returns(value) - Return a synchronous value
• .throws(error) - Throw an error

Mocks: Complete Test Doubles

Mocks are comprehensive test doubles that define expectations for multiple method calls and verify they all occurred correctly. They combine stubbing behavior with built-in verification.

describe('EmailNotificationService', function() {
 it('should send welcome email and confirmation on user signup', function() {
 const emailSender = sinon.mock();
 
 // Define expectations
 emailSender.expects('send')
 .once()
 .withArgs({
 to: '[email protected]',
 subject: 'Welcome to Our Platform!',
 template: 'welcome'
 });
 
 emailSender.expects('sendConfirmation')
 .once()
 .withArgs('[email protected]', 'welcome-sent');
 
 const service = new EmailNotificationService(emailSender);
 service.sendWelcomeEmail({
 email: '[email protected]',
 name: 'New User'
 });
 
 // Verify all expectations were met
 emailSender.verify();
 });
});

Sinon Sandboxing

When dealing with multiple stubs and spies, use sandboxes to manage cleanup efficiently. This prevents test pollution between test cases.

describe('Complex Integration', function() {
 beforeEach(function() {
 this.sandbox = sinon.createSandbox();
 
 // Create all stubs within the sandbox
 this.fsStub = this.sandbox.stub(fs, 'readFile');
 this.dbStub = this.sandbox.stub(database, 'query');
 this.loggerStub = this.sandbox.stub(logger, 'info');
 });

 afterEach(function() {
 // Restore everything in one call
 this.sandbox.restore();
 });

 it('should read config and query database', async function() {
 this.fsStub.callsArgWith(1, null, JSON.stringify({ env: 'test' }));
 this.dbStub.resolves([{ id: 1, name: 'Test' }]);
 
 const result = await myModule.loadData();
 
 expect(result).to.have.property('config');
 expect(result.data).to.have.lengthOf(1);
 });
});

Testing Asynchronous Code

Node.js heavily relies on asynchronous operations, and Mocha provides multiple patterns for testing async code effectively. For comprehensive coverage of testing strategies across different JavaScript frameworks, explore our guide on unit testing React with Cypress which covers similar async testing patterns in a frontend context.

The Done Callback

For callback-based APIs, pass the done parameter to your test. Call done() when the async operation completes, or done(err) if it fails.

describe('File Reader', function() {
 it('should read file content asynchronously', function(done) {
 fileReader.read('/test/data.json', function(err, content) {
 if (err) return done(err);
 
 expect(content).to.be.a('string');
 expect(content).to.include('testData');
 done();
 });
 });

 it('should return error for missing file', function(done) {
 fileReader.read('/nonexistent/file.json', function(err) {
 expect(err).to.exist;
 expect(err.code).to.equal('ENOENT');
 done();
 });
 });
});

Async/Await (Modern Approach)

Modern Node.js development favors async/await, which makes asynchronous tests read like synchronous ones.

describe('User Service', function() {
 it('should create and return new user', async function() {
 const user = await userService.create({
 name: 'Test User',
 email: '[email protected]'
 });

 expect(user).to.have.property('id');
 expect(user.name).to.equal('Test User');
 expect(user.createdAt).to.be.a('Date');
 });

 it('should reject duplicate email addresses', async function() {
 await expect(userService.create({
 email: '[email protected]'
 })).to.be.rejectedWith('Email already exists');
 });

 it('should fetch user by ID with related data', async function() {
 const user = await userService.findById('user-123');

 expect(user).to.have.property('profile');
 expect(user.profile).to.have.property('avatar');
 });
});

Testing Promise Rejections

it('should handle API failures gracefully', async function() {
 // Stub external API to fail
 apiClientStub.get.rejects(new Error('Network timeout'));

 await expect(service.fetchData())
 .to.be.rejectedWith('Failed to fetch data');
});

Best Practices for Unit Testing

Writing effective unit tests requires discipline and consistent practices. These guidelines will help you build a maintainable test suite for your custom software solutions.

Test Organization

• Group related tests using nested describe blocks that mirror your code structure
• Use descriptive names that explain what is being tested (e.g., "should return validated user data")
• Keep tests independent - no test should depend on the outcome or state of another
• Follow AAA pattern: Arrange (setup), Act (execute), Assert (verify)

it('should calculate total with tax and discount', function() {
 // Arrange
 const cart = new ShoppingCart([{ price: 100 }]);
 
 // Act
 const total = cart.calculateTotal(0.1, 20);
 
 // Assert
 expect(total).to.equal(90); // 100 + 10% tax - 20 discount = 90
});

Test Isolation

• Mock all external dependencies - databases, APIs, file system, timers
• Never share mutable state between tests
• Use beforeEach for fresh setup, not before (which only runs once)
• Restore all stubs/spies in afterEach or use sandboxes

Performance Considerations

• Keep tests fast - unit tests should complete in milliseconds
• Stub I/O operations instead of using real file/database access
• Run tests in parallel when possible using --parallel flag
• Use watch mode during development with mocha --watch

Testing Edge Cases

describe('Input Validator', function() {
 it('should accept valid email formats', function() {
 expect(validator.isValidEmail('[email protected]')).to.be.true;
 expect(validator.isValidEmail('[email protected]')).to.be.true;
 });

 it('should reject invalid email formats', function() {
 expect(validator.isValidEmail('invalid')).to.be.false;
 expect(validator.isValidEmail('user@')).to.be.false;
 expect(validator.isValidEmail('@domain.com')).to.be.false;
 });

 it('should handle null and undefined', function() {
 expect(validator.isValidEmail(null)).to.be.false;
 expect(validator.isValidEmail(undefined)).to.be.false;
 });
});

What to Test

Test behavior, not implementation. Focus on the public interface of your functions and modules:

• Expected inputs and their corresponding outputs
• Error conditions and edge cases
• Boundary conditions and invalid states
• Integration points with other modules

Avoid testing:

• Internal private methods
• Third-party library internals
• Trivial getter/setter methods

Integrating with CI/CD Pipelines

Automated testing is most effective when integrated into your continuous integration workflow. Every code change should trigger your test suite.

npm Script Configuration

{
 "scripts": {
 "test": "mocha",
 "test:watch": "mocha --watch",
 "test:coverage": "nyc mocha",
 "test:ci": "mocha --reporter dot --exit"
 }
}

CI Best Practices

1. Run tests on every PR - Prevent regressions from reaching main branch
2. Fail builds on test failures - Tests must pass before merging
3. Track coverage over time - Identify areas lacking test coverage
4. Set reasonable timeouts - Fail fast if tests hang (use --timeout 5000)
5. Parallelize execution - Use mocha --parallel for faster feedback

GitHub Actions Example

name: Tests
on: [push, pull_request]

jobs:
 test:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v3
 - uses: actions/setup-node@v3
 with:
 node-version: '20'
 - run: npm ci
 - run: npm test
 - run: npm run test:coverage

Conclusion

Unit testing with Mocha, Chai, and Sinon provides a powerful foundation for ensuring code quality in Node.js applications. These three tools work together seamlessly:

• Mocha organizes tests with flexible structure and hooks
• Chai provides readable, comprehensive assertions
• Sinon enables complete test isolation through sophisticated mocking

When combined effectively, these tools allow you to build comprehensive test suites that catch bugs early, enable confident refactoring, and serve as living documentation for your codebase. Start by adding tests to critical functionality, then expand coverage systematically.

Next steps:

• Set up testing in your current Node.js project
• Add tests for your most critical business logic
• Integrate test running into your CI/CD pipeline
• Explore additional tools like nyc for coverage reporting

Sources

1. LogRocket: Node.js unit testing using Mocha, Chai, and Sinon - Comprehensive guide covering setup, assertions, spies, stubs, and async testing patterns
2. BrowserStack: Unit testing for NodeJS using Mocha and Chai - Setup guide and best practices for testing configurations
3. CloudBees: Using Mocha JS, Chai JS and Sinon JS - Sinon mocking strategies and sandbox patterns