When building a Node.js application, writing code is only part of the job.
You also need to make sure that your code works correctly.
This is where unit testing becomes important.
Unit testing allows you to test small parts of your application independently. Instead of testing the entire application at once, you test individual functions and modules.
One popular testing framework for Node.js is Mocha.js.
Mocha is a flexible JavaScript test framework that runs on Node.js and supports both synchronous and asynchronous testing. It also allows you to use different assertion libraries, including Node.js’s built-in assert module.
In this practical guide, you will learn how to set up Mocha, write your first unit test, use assertions, test asynchronous code, organize tests, handle errors, and follow good testing practices.
What Is Unit Testing?
Unit testing means testing small, individual parts of an application.
A unit is usually a small piece of code such as:
- A function
- A method
- A module
- A small piece of business logic
For example:
function add(a, b) {
return a + b;
}
This function is simple enough to test independently.
A unit test could check:
add(2, 3);
and make sure the result is:
5
Instead of testing the entire Node.js application, we are testing one small piece of logic.
Why Is Unit Testing Important?
Unit tests provide confidence that your code behaves as expected.
They are especially useful when your application becomes larger.
Without tests, changing one part of your application can accidentally break another part.
With unit tests, you can quickly find out when something stops working.
Unit testing can help you:
- Find bugs early
- Prevent regressions
- Improve code quality
- Make refactoring safer
- Understand existing code
- Reduce manual testing
- Build confidence when adding new features
What Is Mocha.js?
Mocha.js, usually called Mocha, is a JavaScript test framework.
It can run tests in Node.js as well as in browsers. Mocha supports synchronous tests, callbacks, Promises, and async/await, which makes it useful for testing many types of JavaScript applications.
One important thing to understand is that Mocha is a test runner, not an assertion library.
For example, you can use Node.js’s built-in assert module with Mocha:
import assert from "node:assert";
You can also use other assertion libraries if your project needs them.
This flexibility is one of Mocha’s useful features.
Mocha vs Assertion Library
Beginners sometimes confuse Mocha with an assertion library.
They have different jobs.
Mocha
Mocha:
- Finds and runs tests
- Organizes test suites
- Provides hooks
- Handles asynchronous tests
- Reports test results
Assertion Library
An assertion library checks whether the result is what you expected.
For example:
assert.equal(result, 5);
Node.js provides a built-in assert module, so you can start testing without installing another assertion library.
Setting Up Mocha in a Node.js Project
Let’s create a simple Node.js project.
Start by creating a folder:
mkdir mocha-testing
Move into it:
cd mocha-testing
Initialize the project:
npm init -y
Now install Mocha as a development dependency:
npm install --save-dev mocha
The current Mocha documentation recommends installing Mocha as a development dependency. The current Mocha 12 release requires Node.js ^20.19.0 || >=22.12.0.
Create Your First Function
Let’s create a file called:
calculator.js
Add this function:
function add(a, b) {
return a + b;
}
module.exports = {
add
};
This is the function we want to test.
Create a Test Folder
Mocha conventionally looks for test files inside a test directory.
Create:
test/
Then create:
test/calculator.test.js
Your project can now look like:
mocha-testing/
│
├── calculator.js
├── package.json
├── package-lock.json
│
└── test/
└── calculator.test.js
Mocha’s current getting-started documentation uses a test/ directory and a .test.js file for its example.
Write Your First Mocha Test
Open:
test/calculator.test.js
Add:
const assert = require("assert");
const { add } = require("../calculator");
describe("add()", function () {
it("should add two numbers", function () {
const result = add(2, 3);
assert.equal(result, 5);
});
});
Let’s understand this step by step.
Understanding describe()
The describe() function groups related tests.
describe("add()", function () {
// tests
});
Here, we are grouping tests related to the add() function.
Understanding it()
The it() function defines an individual test.
it("should add two numbers", function () {
// test code
});
The first argument describes what the test should do.
A good test name makes failures easier to understand.
Understanding assert
We are using Node.js’s built-in assert module:
const assert = require("assert");
Then:
assert.equal(result, 5);
This means:
The result should equal 5.
If the result is 5, the test passes.
If the result is something else, the test fails.
Mocha itself allows you to use assertion libraries of your choice.
Running Mocha Tests
You can run your tests using:
npx mocha
Mocha will discover the tests and run them.
You should see output similar to:
add()
✓ should add two numbers
1 passing
The current Mocha getting-started documentation uses npx mocha as the basic command for running tests.
Add a Test Script to package.json
Instead of typing:
npx mocha
every time, you can add a script to package.json.
{
"scripts": {
"test": "mocha"
}
}
Now you can run:
npm test
This is a common approach for Node.js projects and is also shown in Mocha’s official setup documentation.
Testing More Than One Case
Let’s add more tests.
describe("add()", function () {
it("should add two positive numbers", function () {
assert.equal(add(2, 3), 5);
});
it("should add a positive and negative number", function () {
assert.equal(add(10, -5), 5);
});
it("should return the same number when adding zero", function () {
assert.equal(add(10, 0), 10);
});
});
Now we are testing different situations.
This is important because real applications rarely have only one possible input.
Testing Edge Cases
Good unit tests should include important edge cases.
Consider:
function divide(a, b) {
return a / b;
}
You might test:
describe("divide()", function () {
it("should divide two numbers", function () {
assert.equal(divide(10, 2), 5);
});
it("should handle zero as the first number", function () {
assert.equal(divide(0, 10), 0);
});
});
You should also think about what should happen when the second number is zero.
The correct behavior depends on your application’s requirements.
The important point is to decide what the expected behavior should be and test it.
Testing Objects
You can also test objects.
Suppose:
function createUser(name, role) {
return {
name,
role
};
}
A test could be:
describe("createUser()", function () {
it("should create a user object", function () {
const user = createUser("John", "Developer");
assert.deepEqual(user, {
name: "John",
role: "Developer"
});
});
});
deepEqual() is useful when comparing the contents of objects.
Testing Arrays
Suppose you have:
function getNumbers() {
return [1, 2, 3];
}
You can test the result:
it("should return an array of numbers", function () {
const result = getNumbers();
assert.deepEqual(result, [1, 2, 3]);
});
This verifies that the returned array contains the expected values.
Testing Errors
Testing successful operations is not enough.
You should also test how your code behaves when something goes wrong.
Consider:
function withdraw(balance, amount) {
if (amount > balance) {
throw new Error("Insufficient balance");
}
return balance - amount;
}
We can test the error:
it("should throw an error when balance is insufficient", function () {
assert.throws(() => {
withdraw(100, 200);
}, /Insufficient balance/);
});
Now the test verifies that an error is thrown with the expected message.
Testing Asynchronous Code With Mocha
Node.js applications frequently work with asynchronous operations.
Examples include:
- API requests
- Database queries
- File operations
- Timers
- Network requests
Mocha supports several ways to test asynchronous code, including callbacks, Promises, and async/await.
Testing With Promises
Suppose:
function getUser() {
return Promise.resolve({
name: "John"
});
}
You can test it using async/await:
it("should return the user", async function () {
const user = await getUser();
assert.equal(user.name, "John");
});
Because the test function is async, Mocha waits for the Promise to finish.
Testing Rejected Promises
Suppose a function returns a rejected Promise:
function getUser() {
return Promise.reject(
new Error("User not found")
);
}
You can test it with:
it("should reject when user is not found", async function () {
try {
await getUser();
assert.fail("Expected an error");
} catch (error) {
assert.equal(error.message, "User not found");
}
});
This makes sure your application handles the failure correctly.
Testing With done()
Mocha also supports callback-based asynchronous tests.
For example:
function getData(callback) {
setTimeout(() => {
callback(null, "Data loaded");
}, 100);
}
The test can use done():
it("should load data", function (done) {
getData((error, data) => {
if (error) {
done(error);
return;
}
assert.equal(data, "Data loaded");
done();
});
});
Calling done() tells Mocha that the asynchronous test has finished.
If an error occurs, passing the error to done() causes the test to fail.
Mocha also detects situations such as calling done() more than once.
Don’t Mix done() With Promises
A common mistake is using both done() and a returned Promise in the same test.
For example:
it("should work", function (done) {
return somePromise().then(() => {
done();
});
});
This is not recommended.
Use either:
it("should work", async function () {
await somePromise();
});
or:
it("should work", function (done) {
someAsyncFunction(() => {
done();
});
});
Mocha reports an error when a test uses both a returned Promise and done().
Using beforeEach()
Sometimes several tests need the same setup.
Mocha provides hooks for this.
For example:
describe("User", function () {
let user;
beforeEach(function () {
user = {
name: "John",
role: "Developer"
};
});
it("should have a name", function () {
assert.equal(user.name, "John");
});
it("should have a role", function () {
assert.equal(user.role, "Developer");
});
});
beforeEach() runs before each test.
This helps you prepare a clean starting state.
Using before()
Sometimes setup only needs to happen once.
For example:
before(function () {
console.log("Setup before all tests");
});
This runs before the tests in that suite.
Mocha also provides:
before()after()beforeEach()afterEach()
These hooks are useful for setting up and cleaning up test resources.
Using afterEach()
Use afterEach() when something needs to be cleaned up after every test.
afterEach(function () {
console.log("Cleaning up");
});
This can be useful for:
- Clearing test data
- Closing connections
- Restoring mocks
- Resetting application state
Organizing Tests With describe()
As your application grows, you will have many tests.
Use describe() to organize related tests.
For example:
describe("User Service", function () {
describe("createUser()", function () {
it("should create a user", function () {
// ...
});
it("should reject invalid data", function () {
// ...
});
});
describe("deleteUser()", function () {
it("should delete a user", function () {
// ...
});
});
});
This makes the test output easier to understand.
Testing a Node.js Service
Let’s look at a more realistic example.
Suppose we have:
function calculateTotal(price, tax) {
return price + tax;
}
module.exports = {
calculateTotal
};
Our test file:
const assert = require("assert");
const { calculateTotal } = require("../calculator");
describe("calculateTotal()", function () {
it("should calculate the total price", function () {
const result = calculateTotal(100, 20);
assert.equal(result, 120);
});
it("should return the price when tax is zero", function () {
const result = calculateTotal(100, 0);
assert.equal(result, 100);
});
});
This is a simple unit test.
The test doesn’t need a server.
It doesn’t need a database.
It only tests the function.
That is exactly what makes it a unit test.
Unit Testing vs Integration Testing
It is important to understand the difference.
Unit Testing
Unit testing focuses on one small piece of code.
For example:
calculateTotal()
You test the function independently.
Integration Testing
Integration testing checks whether multiple parts work together.
For example:
API
↓
Service
↓
Database
An integration test might check the entire flow.
Both types of testing are useful.
Unit tests are usually faster and easier to run.
Integration tests provide confidence that different parts of your application work together correctly.
Using Mocks With Mocha
Mocha does not provide a built-in mocking system like Jest.
Instead, you can use separate libraries when you need mocking or spying.
One popular choice is Sinon.
For example, you might use a stub to replace an external dependency during a unit test.
The important idea is:
Mocha runs the test, while another library can provide mocking or spying functionality.
This separation gives you flexibility in choosing the tools you need.
Testing API-Related Code
Suppose your service calls an external API.
You usually don’t want every unit test to make a real network request.
A better approach is to isolate the API dependency and replace it with a controlled test double.
For example:
async function getUserName(getUser) {
const user = await getUser();
return user.name;
}
Then:
it("should return the user's name", async function () {
const fakeGetUser = async function () {
return {
name: "John"
};
};
const result = await getUserName(fakeGetUser);
assert.equal(result, "John");
});
This test does not make a real API request.
It provides a controlled function instead.
Testing Express.js Applications
Mocha can also be part of a testing setup for Node.js web applications.
For example, you might have an Express application:
Client
↓
Express Route
↓
Controller
↓
Service
↓
Database
You can use unit tests to test individual functions.
For HTTP-level testing, you can combine Mocha with an HTTP testing library such as Supertest.
This allows you to test things like:
- HTTP status codes
- Response bodies
- API routes
- Request handling
- Authentication behavior
The exact setup depends on the application architecture.
Code Coverage With Mocha
Code coverage tells you how much of your code is executed by your tests.
Coverage can help you find parts of your application that are not being tested.
Mocha itself focuses on running tests and reporting their results. Coverage is commonly added through separate tooling.
For example, a project can use a coverage tool such as c8 alongside Mocha.
A typical workflow is:
npx c8 mocha
This can generate coverage information for your test suite.
Remember:
High coverage does not automatically mean high-quality tests.
You should still test important behavior, edge cases, and error conditions.
Best Practices for Mocha Unit Testing
1. Keep Tests Small
Each test should focus on one behavior.
Avoid creating huge tests that check many unrelated things.
2. Use Descriptive Test Names
Instead of:
it("works", function () {});
write:
it("should return an error for an invalid email", function () {});
A descriptive name makes failures easier to understand.
3. Test Behavior
Focus on what your function should do.
Avoid depending too heavily on internal implementation details.
4. Test Edge Cases
Think about:
- Empty values
- Zero
- Negative numbers
- Invalid input
- Missing data
- Errors
- Boundary values
5. Keep Tests Independent
One test should not depend on another test running first.
Every test should create the state it needs.
6. Clean Up After Tests
If a test creates resources or changes shared state, clean it up afterward.
Use:
afterEach(function () {
// cleanup
});
7. Avoid Real External Dependencies
Unit tests should generally not depend on:
- Real APIs
- Production databases
- External services
- Network availability
Use controlled test doubles when necessary.
8. Test Both Success and Failure
Don’t only test the happy path.
For example:
Valid input → Success
Invalid input → Error
Missing data → Error
Boundary value → Expected behavior
This gives you much stronger confidence in your code.
Common Mistakes Beginners Make
Writing only one test
One successful test doesn’t prove that your function works in every situation.
Testing only the happy path
Always consider errors and edge cases.
Making tests dependent on each other
Each test should be independent.
Using real APIs in unit tests
External services can make tests slow and unreliable.
Forgetting asynchronous handling
Make sure Mocha knows when an async test has finished.
Mixing done() and Promises
Use one asynchronous pattern per test.
Writing vague test names
A test name should explain what behavior is being checked.
A Complete Mocha Unit Testing Example
Let’s create a simple calculator.
calculator.js
function add(a, b) {
return a + b;
}
function subtract(a, b) {
return a - b;
}
function multiply(a, b) {
return a * b;
}
function divide(a, b) {
if (b === 0) {
throw new Error("Cannot divide by zero");
}
return a / b;
}
module.exports = {
add,
subtract,
multiply,
divide
};
calculator.test.js
const assert = require("assert");
const {
add,
subtract,
multiply,
divide
} = require("../calculator");
describe("Calculator", function () {
describe("add()", function () {
it("should add two numbers", function () {
assert.equal(add(10, 5), 15);
});
});
describe("subtract()", function () {
it("should subtract two numbers", function () {
assert.equal(subtract(10, 5), 5);
});
});
describe("multiply()", function () {
it("should multiply two numbers", function () {
assert.equal(multiply(10, 5), 50);
});
});
describe("divide()", function () {
it("should divide two numbers", function () {
assert.equal(divide(10, 5), 2);
});
it("should throw an error when dividing by zero", function () {
assert.throws(() => {
divide(10, 0);
}, /Cannot divide by zero/);
});
});
});
Now you have multiple tests organized by function.
Run them with:
npm test
You should get a report showing which tests passed or failed.
Recommended Project Structure
A simple Node.js project using Mocha could look like:
my-project/
│
├── src/
│ ├── calculator.js
│ ├── userService.js
│ └── authService.js
│
├── test/
│ ├── calculator.test.js
│ ├── userService.test.js
│ └── authService.test.js
│
├── package.json
└── package-lock.json
Keeping application code and test code organized makes a project easier to maintain.
Mocha Unit Testing Quick Reference
| Feature | Purpose |
|---|---|
describe() | Groups related tests |
it() | Defines a test |
before() | Runs setup once before tests |
after() | Runs cleanup after tests |
beforeEach() | Runs before each test |
afterEach() | Runs after each test |
assert.equal() | Compares values |
assert.deepEqual() | Compares object/array contents |
assert.throws() | Tests thrown errors |
npx mocha | Runs Mocha tests |
npm test | Runs tests through the package script |
async/await | Tests asynchronous code |
done() | Handles callback-based async tests |
Frequently Asked Questions
What is Mocha.js used for?
Mocha is a JavaScript test framework used to run and organize tests. It works with Node.js and browsers and supports synchronous and asynchronous testing.
Is Mocha an assertion library?
No. Mocha is a test framework. You can use Node.js’s built-in assert module or another assertion library with it.
How do I install Mocha?
Install it as a development dependency:
npm install --save-dev mocha
The current official setup uses this approach.
How do I run Mocha tests?
You can run:
npx mocha
or add "test": "mocha" to package.json and run:
npm test
Can Mocha test asynchronous code?
Yes. Mocha supports callbacks with done(), Promises, and async/await.
Can I use Mocha with Node.js?
Yes. Mocha is designed to run JavaScript tests in Node.js and also supports browser testing.
Does Mocha provide mocking?
Mocha focuses on running and organizing tests. Mocking and spying can be provided through additional libraries, giving you flexibility in choosing the tools you need.
Conclusion
Unit testing is an important part of building reliable Node.js applications.
With Mocha, you can create organized tests for individual functions, services, and modules.
The basic workflow is simple:
Write code
↓
Write a test
↓
Run Mocha
↓
Check the result
↓
Fix or improve the code
Start with simple tests using describe(), it(), and Node.js’s assert module.
As your application grows, add tests for asynchronous operations, errors, edge cases, external dependencies, and important business logic.
The goal isn’t to write as many tests as possible.
The goal is to write useful tests that give you confidence in your Node.js application.
