Unit Testing Essentials for Express API: A Step-by-Step Guide

Unit testing is a very important aspect of software development. It involves testing the smallest units of code (eg. functions or methods) and if written well, they act as a guard rail whenever your code violates its expected behavior.

In this article, we'll cover all the steps required to write unit tests for your node express API.

By the end of this article, you'd have an understanding of how unit tests work, how to write them, and how to be less lost finding the bugs.

Here's an overview of the concepts covered in this article:

• 📰 What is unit testing?
• 🛸 Why unit testing is important
• 🔰 How to use this guide
• 🌠 Our express API
• 🧪 Let's begin testing
• 🔎 Install mocha and chai
• 🧩 Create your first test
• ✨ Running your first test
• 🔮 Try async
• 🪝 Before and After hooks
• 📈 One unit at a time
• 🎭 Stubbing private resources with Rewire
• 🏭 Testing our database
• 🐫 Testing our routes
• 👓 Check your coverage
• 🏎️ Test driven development
• 🚨 Drawbacks of Unit testing
• 💠 Conclusion
• 💭 What next?
• 🏄🏼‍♂️ Resources

But before writing tests for our Node.js API, let's cover the basics.

What is unit testing?

It is about testing the smallest piece of units of your application in isolation.

Testing in isolation is the key.

Web applications often connect to the database, talk to external services, and touch the file system. Unit testing ensures that each one of those units works as expected in isolation.

But unit testing is not enough. It only checks for individual pieces. It should be followed with integration testing to make sure all the units work as expected in unison.

Why is unit testing important?

Unit tests are often the first level of testing done in a web application. For most projects, it is the last one too. Integration and end-to-end tests come after it.

Writing unit tests early in the development cycle helps identify bugs before they creep into the later stages of development.

Why do we need unit tests if they can't guarantee a functional web application?

There are some valid reasons:

1. Since you can't have integration or end-to-end tests during development, unit testing is the best way to catch bugs as they arise.
2. It serves as good documentation for the codebase.
3. Adopting Test Driven Development (more on this later) helps set the expectations.

How to use this guide

To follow along, you only need a working Express.js API by your side, opened in an editor of your choice.

If you do not have one, you can grab the sample Express.js API that we will be using throughout the article from here.

Our express API

We'll be using a simple express API throughout this article to demonstrate unit testing. You can find the code on Github.

The API only provides five endpoints:

1. GET /health/sync - returns 'OK' synchronously
2. GET /health/async - returns 'OK' asynchronously
3. GET /item/:hash - fetches an item from MongoDB with matching hash value
4. POST /item - creates new item in MongoDB
5. PUT /item - updates item's hash value in MongoDB

Let’s begin testing

We are now ready to write some unit tests. We'll be using mocha and chai for our API. Mocha is open-source, can be combined with various assertion libraries, and has great community support. Moreover, it is used by Coursera, Asana, Intuit, and the like.

There are several components (or units) that we need to test in our API:

1. Controllers (or services or business logic handlers) - it is responsible for performing the business logic and returning the result.
2. MongoDB models (database schemas) - Constraints are defined in the schema and are enforced at runtime.
3. Express routes - It is responsible for mapping the HTTP requests to the corresponding controller and eventually returning the response to the client.

Install mocha and chai

First off, we need to install mocha and chai:

1npm install -D mocha chai

Done? Great! Time to create our first test ⚡.

Create your first test

Let's start by creating a test file. Here's how the current project structure looks like:

1- src
2-- controllers
3---- item.controller.js
4---- health.controller.js
5-- models
6---- item.model.js
7-- routes
8---- index.js
9---- item.route.js
10---- health.route.js
11-- tests
12---- health.spec.js
13-- app.js

We'll be adding our tests inside the tests folder. We have created a new file health.spec.js inside the folder.

Let's start writing some basic tests for our /health API:

1describe('Test /health', () => {
2  describe('Health check on /sync', () => {
3    it('health should be okay', () => {
4      const actualResult = healthCheckSync();
5      expect(actualResult).to.equal('OK');
6    });
7  });
8});

describe block

We use this outer-most describe block to group related test suites similar to how we've structured our application code.

You can also create nested describe blocks to contain your test suites. For example, here's how we will structure the tests for /health endpoint:

1- describe('Test /health')
2-- describe('Test /health/sync')
3-- describe('Test /health/async')

We will be adding a lot unit tests for our express API and it is usually a good idea to split your unit tests across different files corresponding to different modules (or business logic).

it block

This is the place where we actually write our test suites and check for assertions, return values, etc.

Running your first test

Now that we have our first test suite ready, we are all set. To run the test we've written, let's add the following line to the package.json file inside the scripts section:

1"test": "mocha ./src/tests/*.spec.js"

This script will look for all the files inside the tests folder and run them using mocha. So we just need to run the below command whenever we want to run our test suites:

1npm test

And here we have our first test suite passing 🎉!

If you want to run mocha in watch mode to automatically trigger on file changes, you can have another test script in your package.json file like this:

1"test:watch": "mocha --watch ./src/tests/*.spec.js"

Try async

The tests we write are probably going to test async operations that happen across our express API. Let’s write a test for our /health/async endpoint as well which is async in nature:

1describe('Test /health', () => {
2  describe('Health check on /sync', () => {
3    it('health should be okay', () => {
4      const actualResult = healthCheckSync();
5      expect(actualResult).to.equal('OK');
6    });
7  });
8
9  describe('Health check on /async', () => {
10    it('health should be okay', async () => {
11      const actualResult = await healthCheckAsync();
12      expect(actualResult).to.equal('OK');
13    });
14  });
15});

We get a lot of flexibility here because mocha supports multiple ways we can handle async operations in our test suites:

1. We can use async/await like show above,
2. We can have the thenables attached which perform assertions on the result, or
3. We can use done parameter with callbacks to handle the result and perform assertions.

Before and After hooks

We sometimes need to run some setup/teardown code before/after each test suite. For example, we might need to connect to a database before each test suite and disconnect it after each test suite.

In a describe block, you get access to the following hooks:

1. before - runs before all the tests inside the describe block runs
2. beforeEach - runs before each test inside the describe block runs
3. after - runs after all the tests inside the describe block have run
4. afterEach - runs after each test inside the describe block has run

Let's take a look at the following example for clarity:

1describe('Test /health', () => {
2  before('before', () => {
3    console.log('Ran before all the test suites');
4  });
5
6  after('after', () => {
7    console.log('Ran after all the test suites');
8  });
9
10  beforeEach('beforeEach', () => {
11    console.log('Ran before EACH test suite');
12  });
13
14  afterEach('afterEach', () => {
15    console.log('Ran after EACH test suite');
16  });
17
18  describe('Health check on /sync', () => {
19    it('health should be okay', () => {
20      const actualResult = healthCheckSync();
21      expect(actualResult).to.equal('OK');
22    });
23  });
24
25  describe('Health check on /async', () => {
26    it('health should be okay', async () => {
27      const actualResult = await healthCheckAsync();
28      expect(actualResult).to.equal('OK');
29    });
30  });
31});

Running the above code gives the following output:

We can observe that:

• Before and after hooks ran at the start and end of the outer-most describe block.
• BeforeEach and afterEach ran before & after each test suite (i.e. each test or it block).

One unit at a time

When testing a function, the idea of unit testing is to only test that function and not the other stuff present in that function. So if a function involves a database call, we don’t actually want to make that database call when testing. Here's why:

1. We're performing "unit" test on the function, not the database.
2. Any problem in the database would cause the function to fail for no reason.

We'll test our readItem function to understand this better. But first, let's install the necessary dependencies by running the following command:

1npm install -D rewire sinon sinon-chai

Now that we have our dependencies ready, let's look at the test suites for readItem:

1describe('Testing /item endpoint', () => {
2  let sampleItemVal;
3  let findOneStub;
4
5  beforeEach(() => {
6    sampleItemVal = {
7      name: 'sample item',
8      price: 10,
9      rating: '5',
10      hash: '123456891'
11    };
12
13    findOneStub = sandbox.stub(mongoose.Model, 'findOne').resolves(sampleItemVal);
14  });
15
16  afterEach(() => {
17    itemController = rewire('../controllers/item.controller');
18    sandbox.restore();
19  });
20
21  describe('GET /', () => {
22    it('should return error when called without hash', async () => {
23      itemController
24        .readItem()
25        .then(() => {
26          throw new Error('⚠️ Unexpected success!');
27        })
28        .catch((err) => {
29          expect(result).to.be.instanceOf(Error);
30          expect(err.message).to.equal('Invalid item id');
31        });
32    });
33
34    it('should succeed when called with hash', async () => {
35      itemController
36        .readItem('someRandomHash')
37        .then((item) => {
38          expect(item).to.equal(sampleItemVal);
39        })
40        .catch((err) => {
41          throw new Error('⚠️ Unexpected failure!');
42        });
43    });
44  });
45});

Let's go through it step-by-step:

1. We stub the findOne method of mongoose in the before hook for /item endpoint.
2. We reset the itemController to the original one after each test suite (i,e., "it" block) runs.
3. We restore the sandbox afterEach test suite to reset the stubs (it is generally a good practice to use sandbox).
4. In the first test suite, we call readItem without hash.
5. We expect the result to be an error and make an assertion inside the catch block.
6. In the second one, we pass the hash. It results with a sampleItemVal because we stubbed the findOne method.
7. We make the assertion on the result.

As expected, tests pass seamlessly:

We have now successfully tested our readItem function by stubbing out the findOne method of mongoose. This is one of the extremely important concept to understand when writing unit tests.

Stubbing private resources with Rewire

There is a lot that we have covered starting from scratch. If you're following along, you would've started noticing how the same process can be replicated to test most of the things.

Let's try to replicate the same process to test our updateItem function:

1exports.updateItemHash = async function (hash) {
2  try {
3    if (!hash) {
4      throw new Error('Incomplete arguments');
5    }
6
7    let item = await Item.findOne({
8      hash
9    });
10    item.hash = getUniqueHash(item);
11
12    return await item.save();
13  } catch (err) {
14    return Promise.reject(err);
15  }
16};

As you can see, there is a helper function we're using here called getUniqueHash. And unfortunately, we can't access this function outside the module since it is not exported.

1function getUniqueHash(item) {
2  if (!item) return null;
3  const currentHash = item.hash;
4  let newHash = nanoid(10);
5
6  while (newHash === currentHash) {
7    newHash = nanoid(10);
8  }
9  return newHash;
10}

If you look at the documentation of sinon stub, you'll see that we cannot use the stub in this case.

For it to work, we would need to use the rewire package. It is just like require but comes with a setter and getter function to modify the behavior of private functions and variables in modules.

Let's see the test suite for updateItem and understand how it works:

1describe('Testing /item endpoint', () => {
2  let sampleItemVal;
3  let findOneStub;
4  const sampleUniqueHash = '1234567891';
5
6  beforeEach(() => {
7    sampleItemVal = {
8      name: 'sample item',
9      price: 10,
10      rating: '5',
11      hash: sampleUniqueHash
12    };
13
14    findOneStub = sandbox.stub(mongoose.Model, 'findOne').resolves(sampleItemVal);
15  });
16
17  afterEach(() => {
18    itemController = rewire('../controllers/item.controller');
19    sandbox.restore();
20  });
21
22  describe('PUT /', () => {
23    let getUniqueHashStub, saveStub, result, sampleUpdatedItemVal;
24    const sampleUpdatedHash = '9876543219';
25
26    beforeEach(async () => {
27      // forcefully restore sandbox to allow re-write of findOneStub
28      sandbox.restore();
29
30      // Stub to mock getUniqueHash's Functionality
31      getUniqueHashStub = sandbox.stub().returns(sampleUpdatedHash);
32
33      sampleUpdatedItemVal = {
34        ...sampleItemVal,
35        hash: sampleUpdatedHash
36      };
37      // save stub to return updated item
38      saveStub = sandbox.stub().returns(sampleUpdatedItemVal);
39
40      // make findOneStub return save() method in addition to sampleItemVal
41      findOneStub = sandbox.stub(mongoose.Model, 'findOne').resolves({
42        ...sampleItemVal,
43        save: saveStub
44      });
45
46      // Use rewire to modify itemController's private method getUniqueHash
47      itemController.__set__('getUniqueHash', getUniqueHashStub);
48    });
49
50    it('should throw invalid argument error', () => {
51      itemController
52        .updateItemHash()
53        .then(() => {
54          throw new Error('⚠️ Unexpected success!');
55        })
56        .catch((err) => {
57          expect(result).to.be.instanceOf(Error);
58          expect(err.message).to.equal('Incomplete arguments');
59        });
60    });
61
62    it('should update item hash successfully', async () => {
63      result = await itemController.updateItemHash(sampleUniqueHash);
64      expect(findOneStub).to.have.been.calledWith({
65        hash: sampleUniqueHash
66      });
67      expect(findOneStub).to.have.been.calledOnce;
68      expect(saveStub).to.have.been.calledOnce;
69      expect(result).to.equal(sampleUpdatedItemVal);
70    });
71  });
72});

Let's go through this step-by-step again:

1. We have stored the initial unique hash in sampleUniqueHash variable.
2. Inside test suites for PUT endpoint, we have stored the updated unique hash inside sampleUpdatedHash variable.
3. We need a slightly different stub for findOne so we have completely restored/reset the sinon sandbox. This will allow us to write a new stub for findOne.
4. We have created a stub for getUniqueHash function which will be invoked instead of the original private function inside itemController.
5. On line 41, we have created a new stub for findOne which contains the save method in addition to the sample item value.
6. We are using rewire to modify the private function and replace it with our stub.
7. In first test suite, we have called updateItemHash with an empty hash. It should throw an error.
8. In second test suite however, we have called updateItemHash with a valid hash. It should update the hash and return the updated item.

This lands us shiny green check marks ✅ on the terminal:

Keeping up the momentum, let's test our mongoose models in the next section ✴️.

Testing our database

We usually put some constraints on our models when we create schemas. This ensures that our data follows certain characteristics and is consistent.

Here's our item schema:

1const mongoose = require('mongoose');
2const Schema = mongoose.Schema;
3
4const itemSchema = new Schema({
5  name: {
6    type: String,
7    required: true
8  },
9  rating: {
10    type: String,
11    required: true
12  },
13  price: {
14    type: Number,
15    required: true
16  },
17  hash: {
18    type: String,
19    required: true,
20    unique: true,
21    minlength: 10,
22    maxlength: 10
23  }
24});
25
26module.exports = mongoose.model('Item', itemSchema);

Let's create a new file named model.spec.js inside our tests folder. We will add some basic checks for our model to make sure that our data respects those constraints:

1describe('Testing Item model', () => {
2  let sampleItemVal;
3
4  beforeEach(() => {
5    sampleItemVal = {
6      name: 'sample item',
7      price: 10,
8      rating: '5',
9      hash: 'hashGreaterThan10Chars'
10    };
11  });
12
13  it('it should throw an error due to missing fields', (done) => {
14    let item = new Item();
15
16    item.validate((err) => {
17      expect(err.errors.name).to.exist;
18      expect(err.errors.rating).to.exist;
19      expect(err.errors.price).to.exist;
20      expect(err.errors.hash).to.exist;
21
22      done();
23    });
24  });
25
26  it('it should throw an error due to incorrect hash length', (done) => {
27    let item = new Item(sampleItemVal);
28
29    item.validate((err) => {
30      if (err) {
31        expect(err).to.be.instanceOf(ValidationError);
32        // this is expected, do not pass err to done()
33        done();
34      } else {
35        const unexpectedSuccessError = new Error('⚠️ Unexpected success!');
36        done(unexpectedSuccessError);
37      }
38    });
39  });
40
41  it('it should create the item successfully with correct parameters', (done) => {
42    let item = new Item({
43      ...sampleItemVal,
44      hash: '1234567891'
45    });
46
47    item.validate((err) => {
48      if (err) {
49        const unexpectedFailureError = new Error('⚠️ Unexpected failure!');
50        done(unexpectedFailureError);
51      } else {
52        expect(item.hash).to.equal('1234567891');
53        done();
54      }
55    });
56  });
57});

We have create three test suites to check for three things:

1. Item validation should fail when we don't pass required fields.
2. Item validation should fail when we don't pass the correct hash length.
3. Item should be created successfully when we pass the right parameters.

Tests pass successfully 🎉:

Testing our routes

Finally, let's test our express app routes. We will create a new file named routes.spec.js inside our tests folder.

Just for your reference, here's how the final project structure looks like:

1- src
2-- controllers
3---- item.controller.js
4---- health.controller.js
5-- models
6---- item.model.js
7-- routes
8---- index.js
9---- item.route.js
10---- health.route.js
11-- tests
12---- health.spec.js
13---- item.spec.js
14---- model.spec.js
15---- routes.spec.js
16-- app.js

The next step would be to install supertest package from npm. It makes testing HTTP requests really easy and clean.

1npm install -D supertest

Finished installing? Awesome!

Let's add some tests for our routes now:

1describe('Testing express app routes', () => {
2  afterEach(() => {
3    app = rewire('../app');
4    sandbox.restore();
5  });
6
7  describe('Testing /item route', () => {
8    let sampleItemVal, hash;
9
10    beforeEach(() => {
11      hash = '1234567891';
12      sampleItemVal = {
13        name: 'sample item',
14        price: 10,
15        rating: '5',
16        hash
17      };
18      sandbox.stub(itemController, 'readItem').resolves(sampleItemVal);
19      sandbox.stub(itemController, 'createItem').resolves(sampleItemVal);
20      sandbox.stub(itemController, 'updateItemHash').resolves(sampleItemVal);
21    });
22
23    it('GET /:hash should successfully return item', (done) => {
24      request(app)
25        .get(`/item/${hash}`)
26        .expect(200)
27        .end((err, response) => {
28          expect(response.body).to.have.property('message').to.equal('Item read successfully!');
29          expect(response.body)
30            .to.have.property('item')
31            .to.have.property('name')
32            .to.equal('sample item');
33          expect(response.body).to.have.property('item').to.have.property('price').to.equal(10);
34          expect(response.body).to.have.property('item').to.have.property('rating').to.equal('5');
35          expect(response.body).to.have.property('item').to.have.property('hash').to.equal(hash);
36          done(err); // err is null in success scenario
37        });
38    });
39
40    it('POST / should successfully create a new item', (done) => {
41      request(app)
42        .post('/item/')
43        .send(sampleItemVal)
44        .expect(200)
45        .end((err, response) => {
46          expect(response.body).to.have.property('message').to.equal('Item created successfully!');
47          expect(response.body)
48            .to.have.property('item')
49            .to.have.property('name')
50            .to.equal('sample item');
51          expect(response.body).to.have.property('item').to.have.property('price').to.equal(10);
52          expect(response.body).to.have.property('item').to.have.property('rating').to.equal('5');
53          expect(response.body).to.have.property('item').to.have.property('hash').to.equal(hash);
54          done(err);
55        });
56    });
57
58    it('PUT / should successfully update hash for a given item', (done) => {
59      request(app)
60        .put('/item')
61        .send(hash)
62        .expect(200)
63        .end((err, response) => {
64          expect(response.body).to.have.property('message').to.equal('Item updated successfully!');
65          expect(response.body)
66            .to.have.property('item')
67            .to.have.property('name')
68            .to.equal('sample item');
69          expect(response.body).to.have.property('item').to.have.property('price').to.equal(10);
70          expect(response.body).to.have.property('item').to.have.property('rating').to.equal('5');
71          expect(response.body).to.have.property('item').to.have.property('hash').to.equal(hash);
72          done(err);
73        });
74    });
75  });
76});

It follows a similar structure to what we've been doing so far. We are essentially:

1. Stubbing the controllers because we want to test routes, not controllers (we've tested them already).
2. Making the request using supertest and asserting the response.

Before you run the tests, make sure to update your test script to include the --exit flag:

1"test": "mocha ./src/tests/*.spec.js --exit",

This makes sure your tests exit once finished.

There we go on our successful tests streak 🚀:

Check your coverage

Code coverage is the indication of the code percentage covered under tests. Now that we have finished writing them, it would be nice to see the code coverage of our unit tests.

Code coverage often affects developer confidence. But there is a catch. A 100% code coverage does not necessarily mean that your code is perfect.

TL;DR: code coverage is just the percentage of code covered by the tests. It does not tell whether the tests cover all the scenarios.

Let's take one example.

We have a function named getUniqueHash in our API:

1function getUniqueHash(item) {
2  const currentHash = item.hash;
3  let newHash = nanoid(10);
4
5  while (newHash === currentHash) {
6    newHash = nanoid(10);
7  }
8  return newHash;
9}

And here's one unit test:

1describe('Test getUniqueHash'), () => {
2  it('should return a new hash', () => {
3    const item = {
4      hash: '1234567890',
5    };
6    const newHash = getUniqueHash(item);
7    expect(newHash).to.not.equal(item.hash);
8  });
9});

This test technically covers the function getUniqueHash but it doesn’t cover all the scenarios.

What if the length of the hash generated in the function changes to 100? What if it is null? How about a malicious script as a string? Test coverage won't be affected but the functionality will be, drastically.

Now that we have that out of the way, let's add coverage to our app.

1. First step, let's install nyc:

1npm install -D nyc

2. Next, let's add the following script to the package.json file:

1"coverage": "nyc --reporter=text npm test"

And we're done! You can now run the coverage script with npm run coverage and see the coverage report in the terminal.

Here's how it looks for our express API:

Optional: Brief on Test Driven Development (TDD)

Test-driven development is a practice where unit tests for a feature are written before that feature is developed. Development happens progressively to fix each test case until all of them pass.

Here is a brief overview of how TDD works:

1. Write a unit test for the feature to be implemented
2. Run the tests; they all fail.
3. Implement the feature to fix the first unit test. It passes, rest of them fails.
4. Repeat the above steps until all of the tests pass.

This is an agile way which makes the development strictly combined with tests and refactoring.

The obvious benefit of going with this approach is reliability and developer confidence. As the tests are written before implementing the feature, it makes sure that developed features cater to every test case.

One common argument against this approach is the speed of development which is highly affected because the development is now combined with testing.

You can read more about test driven development here if you're curious.

Drawbacks of Unit testing

We have seen that unit testing helps in a variety of ways and adopting Test Driven Development (TDD) can significantly improve the reliability of your application.

But just like anything else, it comes with some trade-offs. Let's take a look:

1. Unit tests cannot replace or remove the need of integration and end-to-end testing.
2. Unit tests often fail to cover all the possible scenarios and edge cases.
3. Adopting TDD or writing tests for all possible scenarios offers reliability at the cost of speed of development.

Now you go, captain!

And that wraps up our unit testing endeavor! If you reached here, congrats! You are now equipped with the required knowledge to embark on your unit tests journey.

We covered a lot of ground in this article. We talked about the benefits of unit testing, how can we integrate it in our express JS API, and use stubs to mock external libraries and private functions. We also touched on the test coverage and test-driven development (TDD) programming paradigm.

Having said that, there are bound to be things that were not covered in this article. So I encourage you to use this as a starting point and explore further according to your requirements.

I hope you found this useful and actionable to implement in your express.js API. For any queries and feedback please feel free to reach out in the comments or hit me up on Twitter.

Don't stop at unit testing

Now that you have written unit tests for your Express.js API, you can step it up by writing integration tests. It will further strengthen the reliability of your Express.js API.

I'll say once again - unit tests only cover all the pieces in isolation; integration tests ensure your application is working end-to-end.

Writing unit and integration tests is a huge time commitment. If you need to pick one, go with integration tests.

Resources

• Unit test library documentation: Mocha
• Assertion library we used: Chai (comes with a lot of plugins worth exploring)
• Standalone test spies, stubs and mocks for JavaScript: Sinon
• HTTP assertions library: Supertest
• Monkey patching for private functions and variables: Rewire
• Code coverage: Nyc
• Express.js API used in this article: Github

You might also like

1. Learn How to Use Group in Mongodb Aggregation Pipeline (With Exercise)
2. Complete Guide to Multi-Provider OAuth 2 Authorization in Node.js
3. Introduction to TCP Connection Establishment for Software Developers