Testing becomes increasingly important as a Node.js application grows.
At the beginning, you may manually check whether a function works. But as your application gets larger, manually testing every feature becomes slow and unreliable.
A better approach is to automate your tests.
A popular and flexible testing stack for Node.js uses three libraries:
Mocha → Runs and organizes tests
Chai → Makes assertions
Sinon → Creates spies, stubs, fakes, and mocks
Together, they can help you build a flexible testing environment for Node.js applications.
In this guide, you’ll learn how to build a complete Node.js testing setup with Mocha, Chai, and Sinon from scratch.
We’ll cover:
- What Mocha, Chai, and Sinon do
- Installing the testing libraries
- Creating a test structure
- Configuring Mocha
- Writing your first test
- Using Chai assertions
- Using Sinon spies
- Using Sinon stubs
- Mocking dependencies
- Testing asynchronous code
- Testing errors
- Using Mocha hooks
- Restoring Sinon after tests
- Testing API and service logic
- Unit vs integration testing
- Common mistakes
- Testing best practices
- A complete project example
What Are Mocha, Chai, and Sinon?
Before setting up the project, it is important to understand the role of each library.
Mocha
Mocha is the test framework and test runner.
It provides features such as:
describe()it()before()after()beforeEach()afterEach()- Async test support
- Test reporters
- Test configuration
Mocha runs tests and reports whether they passed or failed. It supports asynchronous tests using callbacks, Promises, and async/await.
Chai
Chai is an assertion library.
It allows you to check whether your code produces the expected result.
For example:
expect(result).to.equal(30);
Chai provides different assertion styles, including expect, should, and assert.
Sinon
Sinon is used for test doubles such as:
- Spies
- Stubs
- Fakes
- Mocks
- Timers
For example, you can use Sinon to check whether a function was called:
expect(callback.calledOnce).to.be.true;
Or replace a dependency with controlled behavior:
sinon.stub(api, "getUser").resolves(user);
Sinon is designed to work with popular test runners including Mocha.
How the Three Libraries Work Together
Think of the testing stack like this:
Node.js Application
↓
Mocha
Runs the test case
↓
Application Function
↙ ↘
Chai Sinon
Assertions Test Doubles
For example:
it("should send a welcome email", async function() {
const result = await createUser();
expect(result.name).to.equal("John");
expect(emailService.send.calledOnce).to.be.true;
});
Here:
- Mocha runs the test.
- Chai checks the result.
- Sinon checks whether the email service was called.
This separation makes the testing setup flexible.
What We Will Build
By the end of this tutorial, our project will look roughly like this:
node-testing-demo/
│
├── src/
│ ├── userService.js
│ ├── emailService.js
│ └── userRepository.js
│
├── test/
│ ├── unit/
│ │ └── userService.test.js
│ │
│ └── integration/
│ └── userRepository.test.js
│
├── .mocharc.cjs
├── package.json
└── package-lock.json
This structure separates application code from tests and makes it easier to grow the project later.
Step 1: Create a Node.js Project
Create a new folder:
mkdir node-testing-demo
Move into it:
cd node-testing-demo
Initialize npm:
npm init -y
You now have a basic Node.js project.
Step 2: Check Your Node.js Version
Current Mocha 12 requires:
Node.js ^20.19.0 || >=22.12.0
Check your installed version:
node -v
If your version is too old, upgrade Node.js before installing the current Mocha release.
Step 3: Install Mocha, Chai, and Sinon
Install them as development dependencies:
npm install --save-dev mocha chai sinon
Mocha’s current documentation recommends installing Mocha as a development dependency, while Chai and Sinon provide the assertion and test-double functionality.
Your package.json will contain development dependencies similar to:
{
"devDependencies": {
"chai": "...",
"mocha": "...",
"sinon": "..."
}
}
Step 4: Create the Project Structure
Create the following folders:
src/
test/
Then:
node-testing-demo/
│
├── src/
│
├── test/
│
└── package.json
Mocha looks for test files in the test/ directory by default.
Step 5: Add a Test Script
Open package.json and add:
{
"scripts": {
"test": "mocha"
}
}
Now you can run:
npm test
instead of typing:
npx mocha
Mocha’s current getting-started guide uses the same test script pattern.
Step 6: Create Your First Function
Create:
src/calculator.js
Add:
function add(a, b) {
return a + b;
}
function subtract(a, b) {
return a - b;
}
module.exports = {
add,
subtract
};
Now we have something to test.
Step 7: Write Your First Mocha Test
Create:
test/calculator.test.js
Add:
const { describe, it } = require("mocha");
const { expect } = require("chai");
const {
add,
subtract
} = require("../src/calculator");
describe("Calculator", function() {
it("should add two numbers", function() {
const result = add(10, 20);
expect(result).to.equal(30);
});
it("should subtract two numbers", function() {
const result = subtract(20, 10);
expect(result).to.equal(10);
});
});
Run:
npm test
You should see passing tests.
Why Are We Using describe and it?
Mocha provides functions such as:
describe()
it()
describe() groups related tests.
describe("Calculator", function() {
});
it() defines a specific behavior:
it("should add two numbers", function() {
});
This gives your test suite a readable structure.
Step 8: Using Chai Assertions
Chai’s expect style is easy to read.
const { expect } = require("chai");
Then:
expect(result).to.equal(30);
Some common assertions are:
expect(value).to.equal(expected);
expect(value).to.not.equal(expected);
expect(value).to.be.true;
expect(value).to.be.false;
expect(value).to.be.null;
expect(value).to.be.undefined;
Testing Objects
Suppose:
const user = {
id: 1,
name: "John"
};
You can test:
expect(user).to.be.an("object");
Check a property:
expect(user).to.have.property("name");
Check the property’s value:
expect(user)
.to.have.property("name", "John");
Testing Arrays
For:
const users = ["John", "Mike", "Sarah"];
You can write:
expect(users).to.be.an("array");
Check the length:
expect(users).to.have.lengthOf(3);
Check an item:
expect(users).to.include("John");
Comparing Objects
For objects, use deep.equal() when you want to compare their contents.
const actual = {
name: "John",
age: 25
};
const expected = {
name: "John",
age: 25
};
expect(actual).to.deep.equal(expected);
This is different from:
expect(actual).to.equal(expected);
because separate objects are different references in JavaScript.
Step 9: What Is Sinon?
Now let’s introduce Sinon.
Imagine this function:
function sendWelcomeEmail(emailService, email) {
emailService.send(
email,
"Welcome to our application"
);
}
We don’t want to send a real email every time we run our tests.
Instead, we can use Sinon to create a fake or spy.
Sinon provides tools for observing and controlling behavior such as function calls.
Step 10: Creating a Sinon Spy
A spy records information about function calls.
For example:
const sinon = require("sinon");
const spy = sinon.spy();
spy("Hello");
console.log(spy.called);
The spy records that it was called.
You can check:
spy.calledOnce
You can inspect arguments:
spy.firstCall.args
For example:
expect(spy.calledOnce).to.be.true;
Testing a Callback With a Spy
Consider:
function processUser(user, callback) {
callback(user.name);
}
Test:
it("should call the callback with the user name", function() {
const callback = sinon.spy();
processUser(
{ name: "John" },
callback
);
expect(callback.calledOnce).to.be.true;
expect(callback.firstCall.args[0])
.to.equal("John");
});
Now we’re testing not only the returned result but also how the function interacts with another function.
What Is a Sinon Stub?
A stub replaces a function with controlled behavior.
For example:
const stub = sinon.stub();
stub.returns("Hello");
Calling:
stub();
returns:
Hello
This is useful when your application depends on another function that you don’t want to execute during a unit test.
Stubbing a Method
Suppose we have:
const userRepository = {
findById: async function(id) {
// real database operation
}
};
During a unit test, we can replace it:
const stub = sinon
.stub(userRepository, "findById")
.resolves({
id: 1,
name: "John"
});
Now:
await userRepository.findById(1);
returns the fake user instead of accessing the database.
Why Use Stubs?
Suppose your service does this:
User Service
↓
Database
If you’re testing the service logic, you don’t necessarily want the test to connect to a real database.
Instead:
User Service
↓
Sinon Stub
↓
Fake User
This makes the test:
- Faster
- More isolated
- Easier to control
- Less dependent on external systems
returns() With Sinon
For synchronous functions:
const stub = sinon.stub();
stub.returns(100);
expect(stub()).to.equal(100);
returnsArg()
Sinon can also return one of the arguments:
const stub = sinon.stub();
stub.returnsArg(0);
expect(stub("Hello"))
.to.equal("Hello");
This can be useful when creating controlled test behavior.
resolves() for Promises
For asynchronous functions:
const stub = sinon.stub();
stub.resolves({
id: 1,
name: "John"
});
Now:
const user = await stub();
returns:
{
id: 1,
name: "John"
}
rejects() for Errors
You can simulate a rejected Promise:
const stub = sinon.stub();
stub.rejects(
new Error("Database unavailable")
);
Then:
await stub();
will reject.
This is useful for testing error handling.
Step 11: Creating a User Service
Let’s create a more realistic example.
Create:
src/userService.js
Add:
async function getUserName(repository, id) {
const user = await repository.findById(id);
if (!user) {
throw new Error("User not found");
}
return user.name;
}
module.exports = {
getUserName
};
This service depends on a repository.
Testing the User Service With Sinon
Create:
test/userService.test.js
const { describe, it } = require("mocha");
const { expect } = require("chai");
const sinon = require("sinon");
const {
getUserName
} = require("../src/userService");
describe("User Service", function() {
it("should return the user's name", async function() {
const repository = {
findById: sinon.stub().resolves({
id: 1,
name: "John"
})
};
const result = await getUserName(
repository,
1
);
expect(result).to.equal("John");
expect(repository.findById.calledOnce)
.to.be.true;
});
});
Now we’re testing two things:
1. Did the service return "John"?
2. Did it call the repository?
Chai handles the assertions.
Sinon tracks the repository call.
Mocha runs the test.
Checking Arguments
You can also check which arguments were passed.
expect(repository.findById.firstCall.args[0])
.to.equal(1);
Or using Sinon assertions:
sinon.assert.calledWith(
repository.findById,
1
);
Sinon provides its own assertion API for spies and stubs.
Using Sinon-Chai
If you prefer Chai’s fluent assertion syntax, you can install sinon-chai.
npm install --save-dev sinon-chai
The plugin provides Chai assertions for Sinon spies, stubs, and mocks.
For example, instead of:
expect(repository.findById.calledOnce)
.to.be.true;
you can write:
expect(repository.findById)
.to.have.been.calledOnce;
You can also check arguments:
expect(repository.findById)
.to.have.been.calledWith(1);
This can make tests more readable.
Configuring Sinon-Chai
With a CommonJS setup:
const chai = require("chai");
const sinonChai = require("sinon-chai");
chai.use(sinonChai);
const { expect } = chai;
Now you can use:
expect(spy).to.have.been.calledOnce;
The plugin is optional.
You can use Sinon directly without installing sinon-chai.
Step 12: Always Restore Sinon
Sinon modifies functions when you create spies or stubs.
Those modifications should be cleaned up after your tests.
Sinon recommends restoring its default sandbox after each test to prevent state from leaking between tests.
Use:
afterEach(function() {
sinon.restore();
});
For example:
describe("User Service", function() {
afterEach(function() {
sinon.restore();
});
// tests...
});
This is one of the most important Sinon habits to learn.
Why sinon.restore() Matters
Imagine:
Test 1
↓
Stub database
↓
Test finishes
Test 2
↓
Uses same stub accidentally
Now Test 2 may behave differently depending on whether Test 1 ran first.
That’s exactly the kind of hidden test dependency you want to avoid.
Restoring Sinon after each test keeps tests isolated.
Step 13: Testing Error Handling
Let’s test what happens when the user doesn’t exist.
it("should throw when user does not exist", async function() {
const repository = {
findById: sinon.stub().resolves(null)
};
try {
await getUserName(repository, 1);
expect.fail("Expected getUserName to throw");
} catch (error) {
expect(error.message)
.to.equal("User not found");
}
});
Now we’re testing an important failure scenario.
Testing Repository Errors
What if the database fails?
We can simulate that using rejects():
it("should handle repository errors", async function() {
const repository = {
findById: sinon.stub().rejects(
new Error("Database unavailable")
)
};
try {
await getUserName(repository, 1);
expect.fail("Expected an error");
} catch (error) {
expect(error.message)
.to.equal("Database unavailable");
}
});
No real database is needed.
Step 14: Using Mocha Hooks
Mocha provides hooks for setup and cleanup:
before()
after()
beforeEach()
afterEach()
For example:
describe("User Service", function() {
before(function() {
// Runs once before tests
});
after(function() {
// Runs once after tests
});
beforeEach(function() {
// Runs before every test
});
afterEach(function() {
// Runs after every test
});
});
Hooks are particularly useful for creating test data and cleaning up Sinon state.
A Good Sinon Test Structure
A common structure is:
describe("User Service", function() {
beforeEach(function() {
// setup
});
afterEach(function() {
sinon.restore();
});
it("should return a user", async function() {
// test
});
it("should handle errors", async function() {
// test
});
});
This makes setup and cleanup predictable.
Step 15: Testing Async Functions
Node.js applications contain a lot of asynchronous code.
Mocha supports asynchronous tests with callbacks, Promises, and async/await.
For example:
it("should return user data", async function() {
const user = await getUser();
expect(user.name).to.equal("John");
});
When using async/await, you don’t need done().
Don’t Mix done() and Promises
Avoid:
it("should return user", function(done) {
return getUser().then(function(user) {
expect(user.name).to.equal("John");
done();
});
});
Use either a returned Promise:
it("should return user", function() {
return getUser().then(function(user) {
expect(user.name).to.equal("John");
});
});
or:
it("should return user", async function() {
const user = await getUser();
expect(user.name).to.equal("John");
});
Mocha’s async testing model supports these completion mechanisms, but you shouldn’t combine them in the same test.
Step 16: Testing Timers With Sinon
Sinon can also control timers.
Imagine:
function delayedGreeting(callback) {
setTimeout(function() {
callback("Hello");
}, 1000);
}
Without fake timers, your test would have to wait one second.
Sinon can replace the timer behavior.
const clock = sinon.useFakeTimers();
const callback = sinon.spy();
delayedGreeting(callback);
clock.tick(1000);
expect(callback.calledOnce)
.to.be.true;
sinon.restore();
Now the test can advance time without actually waiting one second.
This is especially useful for:
setTimeoutsetInterval- Retry logic
- Debounce logic
- Polling
- Scheduled tasks
Step 17: Testing API Calls
Suppose your service calls an external API.
async function getWeather(apiClient, city) {
const response = await apiClient.get(
`/weather?city=${city}`
);
return response.data;
}
We don’t want every unit test to make a real network request.
Instead:
const apiClient = {
get: sinon.stub().resolves({
data: {
city: "Jaipur",
temperature: 30
}
})
};
Then:
it("should return weather information", async function() {
const result = await getWeather(
apiClient,
"Jaipur"
);
expect(result.city).to.equal("Jaipur");
expect(result.temperature).to.equal(30);
expect(apiClient.get.calledOnce)
.to.be.true;
});
This is faster and makes the test independent of the external API.
Step 18: Testing Different API Responses
One benefit of stubs is that you can easily control different responses.
Successful response
apiClient.get.resolves({
data: {
id: 1
}
});
Error response
apiClient.get.rejects(
new Error("Network error")
);
Empty response
apiClient.get.resolves({
data: null
});
This lets you test many scenarios without depending on an actual external service.
Step 19: Using onFirstCall() and onSecondCall()
Sometimes a function behaves differently on multiple calls.
Sinon allows you to configure different results.
For example:
const stub = sinon.stub();
stub.onFirstCall().returns("first");
stub.onSecondCall().returns("second");
Then:
expect(stub()).to.equal("first");
expect(stub()).to.equal("second");
This is useful for testing retry logic.
For example:
First API request
↓
Fails
Second API request
↓
Succeeds
You can simulate that behavior with a stub.
Step 20: Testing Retry Logic
Suppose:
async function fetchData(apiClient) {
try {
return await apiClient.get();
} catch (error) {
return await apiClient.get();
}
}
Test:
it("should retry when the first request fails", async function() {
const apiClient = {
get: sinon.stub()
};
apiClient.get
.onFirstCall()
.rejects(new Error("Network error"));
apiClient.get
.onSecondCall()
.resolves({
data: "Success"
});
const result = await fetchData(apiClient);
expect(result.data)
.to.equal("Success");
expect(apiClient.get.calledTwice)
.to.be.true;
});
This is a good example of how Sinon can make difficult scenarios easy to reproduce.
Step 21: Create a Mocha Configuration File
As your project grows, you’ll probably want a configuration file.
Mocha supports configuration files such as:
.mocharc.js
.mocharc.cjs
.mocharc.mjs
.mocharc.json
.mocharc.yaml
depending on your project setup.
For a CommonJS project, create:
.mocharc.cjs
Add:
module.exports = {
spec: "test/**/*.test.js",
timeout: 5000
};
Now Mocha knows where to find your tests and what timeout to use.
Why Use a Mocha Configuration File?
Without configuration, you may repeatedly type:
npx mocha "test/**/*.test.js"
With configuration:
npm test
is enough.
It also gives your team a central place for test settings.
Common Mocha Options
You can configure options such as:
module.exports = {
spec: "test/**/*.test.js",
timeout: 5000,
reporter: "spec"
};
You can also use Mocha’s CLI:
npx mocha --help
to see the available options.
Step 22: Organizing Unit and Integration Tests
As your application grows, separate different test types.
For example:
test/
│
├── unit/
│ ├── userService.test.js
│ └── orderService.test.js
│
└── integration/
├── userRepository.test.js
└── orderRepository.test.js
Unit tests
Usually:
Service
↓
Sinon Stub
Integration tests
Usually:
Service
↓
Repository
↓
Test Database
This separation makes it easier to run only the tests you need.
Step 23: Testing a Complete Service
Let’s create a more realistic example.
src/userService.js
async function createUser(
repository,
emailService,
userData
) {
const existingUser =
await repository.findByEmail(
userData.email
);
if (existingUser) {
throw new Error("Email already exists");
}
const user =
await repository.create(userData);
await emailService.sendWelcomeEmail(
user.email
);
return user;
}
module.exports = {
createUser
};
The service has two dependencies:
Repository
Email Service
We don’t want to use the real database or send a real email during a unit test.
Sinon can replace both.
Testing the Complete Service
const { describe, it, afterEach } = require("mocha");
const { expect } = require("chai");
const sinon = require("sinon");
const {
createUser
} = require("../src/userService");
describe("User Service", function() {
afterEach(function() {
sinon.restore();
});
it("should create a user and send welcome email", async function() {
const repository = {
findByEmail: sinon.stub()
.resolves(null),
create: sinon.stub()
.resolves({
id: 1,
email: "john@example.com"
})
};
const emailService = {
sendWelcomeEmail: sinon.stub()
.resolves()
};
const result = await createUser(
repository,
emailService,
{
email: "john@example.com"
}
);
expect(result.id).to.equal(1);
expect(repository.findByEmail.calledOnce)
.to.be.true;
expect(repository.create.calledOnce)
.to.be.true;
expect(emailService.sendWelcomeEmail.calledOnce)
.to.be.true;
expect(
emailService.sendWelcomeEmail.firstCall.args[0]
).to.equal("john@example.com");
});
});
This single test demonstrates the roles of all three libraries:
Mocha
↓
Runs the test
Sinon
↓
Creates repository/email stubs
Chai
↓
Checks the results
Testing Duplicate Emails
Now test the failure case:
it("should reject an existing email", async function() {
const repository = {
findByEmail: sinon.stub()
.resolves({
id: 1,
email: "john@example.com"
}),
create: sinon.stub()
};
const emailService = {
sendWelcomeEmail: sinon.stub()
};
try {
await createUser(
repository,
emailService,
{
email: "john@example.com"
}
);
expect.fail(
"Expected createUser to throw"
);
} catch (error) {
expect(error.message)
.to.equal("Email already exists");
}
expect(repository.create.notCalled)
.to.be.true;
expect(emailService.sendWelcomeEmail.notCalled)
.to.be.true;
});
This test verifies more than the error.
It also verifies that the application does not continue with creating the user or sending an email.
What Should You Mock?
A useful rule is:
Mock external dependencies, not the behavior you’re actually trying to test.
For example, if you’re testing:
User Service
you might mock:
Database
Email Service
External API
Payment Service
Message Queue
But don’t mock the actual logic you’re trying to verify.
What Should You Not Mock?
Avoid mocking everything.
For example, if you mock your entire application:
Service
↓
Mock
↓
Mock
↓
Mock
↓
Mock
the test may pass without proving much about the actual behavior.
Use mocks and stubs to isolate external dependencies while keeping the core behavior real.
Unit Tests vs Integration Tests
A complete Node.js testing setup usually benefits from both.
Unit Test
Service
↓
Sinon Stub
↓
Fake Response
Advantages:
- Very fast
- Isolated
- Easy to control
- Good for business logic
Integration Test
Service
↓
Repository
↓
Test Database
Advantages:
- Tests real database behavior
- Tests real queries
- Tests integration between modules
- Finds configuration and integration issues
You should not expect one type of test to replace the other.
Testing Database Code
Suppose your repository has:
async function findUserById(id) {
return database.query(
"SELECT * FROM users WHERE id = ?",[id]
); }
For a unit test of a service that uses this repository, you can stub:
repository.findUserById = sinon.stub()
.resolves({
id: 1,
name: "John"
});
For the repository itself, an integration test can use a real test database.
This gives you both:
Unit Test
Service → Stub
Integration Test
Repository → Test DB
Testing HTTP Requests
If your Node.js application exposes APIs, you may add another library such as Supertest.
A typical stack can become:
Mocha
+
Chai
+
Sinon
+
Supertest
Where:
- Mocha runs tests
- Chai makes assertions
- Sinon controls dependencies
- Supertest sends HTTP requests
For example:
Test
↓
POST /users
↓
Express
↓
Controller
↓
Service
↓
Response
You can then assert things such as:
Status = 201
Response contains user
Database was called
Email service was called
Testing Environment Configuration
Keep testing configuration separate from development and production.
For example:
.env
.env.test
.env.production
Your test environment might contain:
NODE_ENV=test
DATABASE_NAME=myapp_test
Never put production credentials inside your test configuration.
Test Isolation
Tests should be independent.
Bad:
Test 1
↓
Creates User
Test 2
↓
Depends on User from Test 1
Better:
Test 1
↓
Creates its own data
↓
Cleans up
Test 2
↓
Creates its own data
↓
Cleans up
For Sinon, cleanup is especially important:
afterEach(function() {
sinon.restore();
});
Sinon specifically recommends restoring its sandbox after tests to prevent state from leaking into subsequent tests.
A Recommended Complete Project Structure
A practical Node.js testing project could look like:
my-node-app/
│
├── src/
│ ├── controllers/
│ │ └── userController.js
│ │
│ ├── services/
│ │ └── userService.js
│ │
│ ├── repositories/
│ │ └── userRepository.js
│ │
│ └── utils/
│ └── validation.js
│
├── test/
│ ├── unit/
│ │ ├── userService.test.js
│ │ └── validation.test.js
│ │
│ └── integration/
│ └── userRepository.test.js
│
├── .mocharc.cjs
├── package.json
└── package-lock.json
This structure works well as an application grows.
Useful npm Scripts
You can create several scripts:
{
"scripts": {
"test": "mocha",
"test:unit": "mocha \"test/unit/**/*.test.js\"",
"test:integration": "mocha \"test/integration/**/*.test.js\""
}
}
Then:
npm test
runs everything.
Or:
npm run test:unit
runs only unit tests.
And:
npm run test:integration
runs only integration tests.
Mocha supports specifying test file patterns through its CLI and configuration.
Running Specific Tests
You can run a particular test file:
npx mocha test/unit/userService.test.js
You can also use Mocha’s --grep option to select tests by name.
For example:
npx mocha --grep "create a user"
This is useful when working on a large test suite.
Testing Only Asynchronous Tests
Mocha provides the --async-only option:
npx mocha --async-only
This requires tests to use an asynchronous completion mechanism such as a callback or returned Promise.
This can be useful in projects where asynchronous behavior needs to be explicit.
Common Mistakes
1. Forgetting to Restore Sinon
Bad:
sinon.stub(repository, "findById");
with no cleanup.
Better:
afterEach(function() {
sinon.restore();
});
2. Using Real APIs in Unit Tests
Avoid making real HTTP requests from every unit test.
Use a stub:
sinon.stub(apiClient, "get")
.resolves(fakeResponse);
3. Using a Real Database for Every Test
Database integration tests are useful, but using a real database for every small business-logic test can make the suite unnecessarily slow.
Use stubs for unit tests and real test databases for integration tests.
4. Testing Implementation Instead of Behavior
Don’t create tests that break every time you refactor internal code.
Focus on behavior:
expect(result).to.equal(expected);
and meaningful interactions:
expect(emailService.sendWelcomeEmail)
.to.have.been.calledOnce;
5. Forgetting Async Handling
Incorrect:
it("should return user", function() {
getUser().then(function(user) {
expect(user.name).to.equal("John");
});
});
Better:
it("should return user", async function() {
const user = await getUser();
expect(user.name).to.equal("John");
});
6. Overusing Mocks
If everything is mocked, your tests may become disconnected from the real application.
Use test doubles where they provide isolation and control.
Best Practices
1. Keep Tests Small
Each test should verify one meaningful behavior.
2. Use Clear Test Names
Good:
it("should reject when email already exists", function() {
});
Avoid:
it("test 5", function() {
});
3. Follow Arrange, Act, Assert
A useful test structure is:
Arrange
↓
Prepare data and dependencies
Act
↓
Call the function
Assert
↓
Verify the result
Example:
it("should return a user's name", async function() {
// Arrange
const repository = {
findById: sinon.stub().resolves({
name: "John"
})
};
// Act
const result = await getUserName(
repository,
1
);
// Assert
expect(result).to.equal("John");
});
4. Restore Test Doubles
Always clean up Sinon state:
afterEach(function() {
sinon.restore();
});
5. Test Success and Failure
Don’t only test:
Success
Also test:
Invalid input
Missing data
Dependency failure
Database failure
Network failure
Unexpected responses
6. Keep Unit Tests Fast
Unit tests should generally run quickly.
If every unit test requires:
- Database
- Network
- File system
- External API
your test suite will become slower and harder to maintain.
Use Sinon to isolate those dependencies where appropriate.
7. Use Integration Tests for Real Integrations
Don’t try to mock away every integration.
Test important real interactions separately:
Repository → Database
API Client → Test API/controlled environment
HTTP Route → Application
The Complete Testing Workflow
Once everything is configured, your workflow looks like:
Write Node.js Code
↓
Write Mocha Test
↓
Use Sinon for Dependencies
↓
Execute Function
↓
Use Chai for Assertions
↓
Mocha Reports Result
↓
Pass / Fail
For example:
it("should create a user", async function() {
const repository = {
create: sinon.stub()
.resolves({
id: 1,
name: "John"
})
};
const user = await createUser(
repository,
{
name: "John"
}
);
expect(user.id).to.equal(1);
});
The roles are clear:
Mocha
→ Runs the test
Sinon
→ Controls repository behavior
Chai
→ Verifies the result
Quick Reference
Mocha
describe();
it();
before();
after();
beforeEach();
afterEach();
Chai
expect(value).to.equal(expected);
expect(value).to.deep.equal(expected);
expect(value).to.be.true;
expect(value).to.have.property("name");
Sinon
sinon.spy();
sinon.stub();
sinon.stub().returns(value);
sinon.stub().resolves(value);
sinon.stub().rejects(error);
sinon.useFakeTimers();
sinon.restore();
Sinon-Chai
expect(spy)
.to.have.been.calledOnce;
expect(spy)
.to.have.been.calledWith("John");
Frequently Asked Questions
Is Mocha enough for Node.js testing?
Mocha can run and organize tests, but it doesn’t require a specific assertion library. You can use Node.js’s built-in assertions or a library such as Chai.
Why use Chai with Mocha?
Chai provides expressive assertions for checking values, objects, arrays, errors, and other results.
Why do we need Sinon?
Sinon provides test doubles such as spies, stubs, fakes, and mocks. It is useful when you need to isolate your code from databases, APIs, email services, timers, or other dependencies.
Is Sinon a test framework?
No.
Sinon is a library for test doubles. It can be used with Mocha, Jest, and other testing frameworks.
Do I need sinon-chai?
No.
You can use Sinon directly:
sinon.assert.calledOnce(spy);
or inspect properties:
expect(spy.calledOnce).to.be.true;
sinon-chai is optional and provides a more fluent Chai syntax for Sinon assertions.
Should I mock the database in every test?
No.
Mock database calls when testing business logic. Use integration tests with a dedicated test database when you need to verify real database behavior.
Should I use Mocha, Chai, and Sinon instead of Jest?
It depends on your project.
Mocha, Chai, and Sinon provide a modular testing stack where each tool has a specific responsibility.
Jest provides many testing features together.
Learning Mocha, Chai, and Sinon is particularly useful for understanding how test runners, assertion libraries, and test doubles work separately.
Conclusion
A complete Node.js testing setup does not have to be complicated.
With three tools, you can build a flexible testing stack:
Mocha
↓
Runs and organizes tests
Chai
↓
Checks expected results
Sinon
↓
Controls and observes dependencies
Mocha gives you the test structure and runner.
Chai gives you readable assertions.
Sinon lets you isolate your code from external dependencies and simulate different scenarios.
Together, they can be used to test:
- Functions
- Services
- APIs
- Database repositories
- Asynchronous code
- Error handling
- External dependencies
- Timers
- Business logic
The most important principle is not to test everything in exactly the same way.
Use unit tests for fast, isolated business logic.
Use integration tests when you need to verify that real components work together.
With a good combination of both, your Node.js test suite can remain fast, reliable, and maintainable as your application grows.
