A Step-By-Step Guide to Unit Testing for Express API

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 the overview of how the article is structured:

• 🌠 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
• 💠 Conclusion
• 🏄🏼‍♂️ Resources

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 a new item in MongoDB
5. PUT /item - updates hash value of the item 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:

npm 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 what the current project structure looks like:

- src
-- controllers
---- item.controller.js
---- health.controller.js
-- models
---- item.model.js
-- routes
---- index.js
---- item.route.js
---- health.route.js
-- tests
---- health.spec.js
-- 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:

// health.spec.js contain a test for /sync endpoint
describe('Test /health', () => {
  describe('Health check on /sync', () => {
    it('health should be okay', () => {
      const actualResult = healthCheckSync();
      expect(actualResult).to.equal('OK');
    });
  });
});

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:

- describe('Test /health')
-- describe('Test /health/sync')
-- describe('Test /health/async')

We will be adding a lot of 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 is helpful to write messages in test suites to showcase what your code does from the product's perspective instead of the application/software perspective.

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:

// Test script inside package.json file
"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:

// Run test suites
npm test

And here we have our first test suite passing 🎉!

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

// Test script in watch mode
"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:

// health.spec.js test for all available endpoints
describe('Test /health', () => {
  describe('Health check on /sync', () => {
    it('health should be okay', () => {
      const actualResult = healthCheckSync();
      expect(actualResult).to.equal('OK');
    });
  });

  describe('Health check on /async', () => {
    it('health should be okay', async () => {
      const actualResult = await healthCheckAsync();
      expect(actualResult).to.equal('OK');
    });
  });
});

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 shown above,
2. We can have the thenables attached which perform assertions on the result, or
3. We can use the 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 right after.

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:

// before(Each) and after(Each) hooks
describe('Test /health', () => {
  before('before', () => {
    console.log('Ran before all the test suites');
  });

  after('after', () => {
    console.log('Ran after all the test suites');
  });

  beforeEach('beforeEach', () => {
    console.log('Ran before EACH test suite');
  });

  afterEach('afterEach', () => {
    console.log('Ran after EACH test suite');
  });

  describe('Health check on /sync', () => {
    it('health should be okay', () => {
      const actualResult = healthCheckSync();
      expect(actualResult).to.equal('OK');
    });
  });

  describe('Health check on /async', () => {
    it('health should be okay', async () => {
      const actualResult = await healthCheckAsync();
      expect(actualResult).to.equal('OK');
    });
  });
});

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 a "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:

npm install -D rewire sinon sinon-chai

• Sinon enables us to create stubs, spies, and mocks with any unit testing framework.
• Rewire provides us with setter and getter functions to replace the original functions with our own.

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

// Full test suite for GET /item endpoint
describe('Testing /item endpoint', () => {
  let sampleItemVal;
  let findOneStub;

  beforeEach(() => {
    sampleItemVal = {
      name: 'sample item',
      price: 10,
      rating: '5',
      hash: '123456891'
    };

    findOneStub = sandbox.stub(mongoose.Model, 'findOne').resolves(sampleItemVal);
  });

  afterEach(() => {
    itemController = rewire('../controllers/item.controller');
    sandbox.restore();
  });

  describe('GET /', () => {
    it('should return error when called without hash', async () => {
      itemController
        .readItem()
        .then(() => {
          throw new Error('⚠️ Unexpected success!');
        })
        .catch((err) => {
          expect(result).to.be.instanceOf(Error);
          expect(err.message).to.equal('Invalid item id');
        });
    });

    it('should succeed when called with hash', async () => {
      itemController
        .readItem('someRandomHash')
        .then((item) => {
          expect(item).to.equal(sampleItemVal);
        })
        .catch((err) => {
          throw new Error('⚠️ Unexpected failure!');
        });
    });
  });
});

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 the 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 concepts to understand when writing unit tests.

Test one unit at a time. Pay extreme care that your tests don't reach out for the production resources (for example, production database and API calls over the network).

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:

// Update item hash controller
exports.updateItemHash = async function (hash) {
  try {
    if (!hash) {
      throw new Error('Incomplete arguments');
    }

    let item = await Item.findOne({
      hash
    });
    item.hash = getUniqueHash(item);

    return await item.save();
  } catch (err) {
    return Promise.reject(err);
  }
};

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.

// Private helper function inside item controller
function getUniqueHash(item) {
  if (!item) return null;
  const currentHash = item.hash;
  let newHash = nanoid(10);

  while (newHash === currentHash) {
    newHash = nanoid(10);
  }
  return newHash;
}

If you look at the documentation of the 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:

// --- skipping other imports & initializations for brevity ---
const rewire = require('rewire');
let itemController = rewire('../controllers/item.controller'); // <-- getter & setter attached


// Full test suite for PUT /item endpoint including initial boilerplate
describe('Testing /item endpoint', () => {
  let sampleItemVal;
  let findOneStub;
  const sampleUniqueHash = '1234567891';

  beforeEach(() => {
    sampleItemVal = {
      name: 'sample item',
      price: 10,
      rating: '5',
      hash: sampleUniqueHash
    };

    findOneStub = sandbox.stub(mongoose.Model, 'findOne').resolves(sampleItemVal);
  });

  afterEach(() => {
    itemController = rewire('../controllers/item.controller');
    sandbox.restore();
  });

  describe('PUT /', () => {
    let getUniqueHashStub, saveStub, result, sampleUpdatedItemVal;
    const sampleUpdatedHash = '9876543219';

    beforeEach(async () => {
      // forcefully restore sandbox to allow re-write of findOneStub
      sandbox.restore();

      // Stub to mock getUniqueHash's Functionality
      getUniqueHashStub = sandbox.stub().returns(sampleUpdatedHash);

      sampleUpdatedItemVal = {
        ...sampleItemVal,
        hash: sampleUpdatedHash
      };
      // save stub to return updated item
      saveStub = sandbox.stub().returns(sampleUpdatedItemVal);

      // make findOneStub return save() method in addition to sampleItemVal
      findOneStub = sandbox.stub(mongoose.Model, 'findOne').resolves({
        ...sampleItemVal,
        save: saveStub
      });

      // Use rewire to modify itemController's private method getUniqueHash
      itemController.__set__('getUniqueHash', getUniqueHashStub);
    });

    it('should throw invalid argument error', () => {
      itemController
        .updateItemHash()
        .then(() => {
          throw new Error('⚠️ Unexpected success!');
        })
        .catch((err) => {
          expect(result).to.be.instanceOf(Error);
          expect(err.message).to.equal('Incomplete arguments');
        });
    });

    it('should update item hash successfully', async () => {
      result = await itemController.updateItemHash(sampleUniqueHash);
      expect(findOneStub).to.have.been.calledWith({
        hash: sampleUniqueHash
      });
      expect(findOneStub).to.have.been.calledOnce;
      expect(saveStub).to.have.been.calledOnce;
      expect(result).to.equal(sampleUpdatedItemVal);
    });
  });
});

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

1. We have stored the unique initial hash in sampleUniqueHash variable.
2. Inside test suites for the 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. Then, we 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 the first test suite, we have called updateItemHash with an empty hash. It should throw an error.
8. In the 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 ✅:

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:

// item.model.js file
const mongoose = require('mongoose');
const Schema = mongoose.Schema;

const itemSchema = new Schema({
  name: {
    type: String,
    required: true
  },
  rating: {
    type: String,
    required: true
  },
  price: {
    type: Number,
    required: true
  },
  hash: {
    type: String,
    required: true,
    unique: true,
    minlength: 10,
    maxlength: 10
  }
});

module.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 respect those constraints:

// model.spec.js file
describe('Testing Item model', () => {
  let sampleItemVal;

  beforeEach(() => {
    sampleItemVal = {
      name: 'sample item',
      price: 10,
      rating: '5',
      hash: 'hashGreaterThan10Chars'
    };
  });

  it('it should throw an error due to missing fields', (done) => {
    let item = new Item();

    item.validate((err) => {
      expect(err.errors.name).to.exist;
      expect(err.errors.rating).to.exist;
      expect(err.errors.price).to.exist;
      expect(err.errors.hash).to.exist;

      done();
    });
  });

  it('it should throw an error due to incorrect hash length', (done) => {
    let item = new Item(sampleItemVal);

    item.validate((err) => {
      if (err) {
        expect(err).to.be.instanceOf(ValidationError);
        // this is expected, do not pass err to done()
        done();
      } else {
        const unexpectedSuccessError = new Error('⚠️ Unexpected success!');
        done(unexpectedSuccessError);
      }
    });
  });

  it('it should create the item successfully with correct parameters', (done) => {
    let item = new Item({
      ...sampleItemVal,
      hash: '1234567891'
    });

    item.validate((err) => {
      if (err) {
        const unexpectedFailureError = new Error('⚠️ Unexpected failure!');
        done(unexpectedFailureError);
      } else {
        expect(item.hash).to.equal('1234567891');
        done();
      }
    });
  });
});

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

1. Item validation should fail when we don't pass the 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. But before we move on, here's what the final project structure looks like:

- src
-- controllers
---- item.controller.js
---- health.controller.js
-- models
---- item.model.js
-- routes
---- index.js
---- item.route.js
---- health.route.js
-- tests
---- health.spec.js
---- item.spec.js
---- model.spec.js
---- routes.spec.js
-- app.js

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

npm install -D supertest

Finished installing? Awesome!

Let's add some tests for our routes now:

// Test suites for /item endpoints
describe('Testing express app routes', () => {
  afterEach(() => {
    app = rewire('../app');
    sandbox.restore();
  });

  describe('Testing /item route', () => {
    let sampleItemVal, hash;

    beforeEach(() => {
      hash = '1234567891';
      sampleItemVal = {
        name: 'sample item',
        price: 10,
        rating: '5',
        hash
      };
      sandbox.stub(itemController, 'readItem').resolves(sampleItemVal);
      sandbox.stub(itemController, 'createItem').resolves(sampleItemVal);
      sandbox.stub(itemController, 'updateItemHash').resolves(sampleItemVal);
    });

    it('GET /:hash should successfully return item', (done) => {
      request(app)
        .get(`/item/${hash}`)
        .expect(200)
        .end((err, response) => {
          expect(response.body).to.have.property('message').to.equal('Item read successfully!');
          expect(response.body)
            .to.have.property('item')
            .to.have.property('name')
            .to.equal('sample item');
          expect(response.body).to.have.property('item').to.have.property('price').to.equal(10);
          expect(response.body).to.have.property('item').to.have.property('rating').to.equal('5');
          expect(response.body).to.have.property('item').to.have.property('hash').to.equal(hash);
          done(err); // err is null in success scenario
        });
    });

    it('POST / should successfully create a new item', (done) => {
      request(app)
        .post('/item/')
        .send(sampleItemVal)
        .expect(200)
        .end((err, response) => {
          expect(response.body).to.have.property('message').to.equal('Item created successfully!');
          expect(response.body)
            .to.have.property('item')
            .to.have.property('name')
            .to.equal('sample item');
          expect(response.body).to.have.property('item').to.have.property('price').to.equal(10);
          expect(response.body).to.have.property('item').to.have.property('rating').to.equal('5');
          expect(response.body).to.have.property('item').to.have.property('hash').to.equal(hash);
          done(err);
        });
    });

    it('PUT / should successfully update hash for a given item', (done) => {
      request(app)
        .put('/item')
        .send(hash)
        .expect(200)
        .end((err, response) => {
          expect(response.body).to.have.property('message').to.equal('Item updated successfully!');
          expect(response.body)
            .to.have.property('item')
            .to.have.property('name')
            .to.equal('sample item');
          expect(response.body).to.have.property('item').to.have.property('price').to.equal(10);
          expect(response.body).to.have.property('item').to.have.property('rating').to.equal('5');
          expect(response.body).to.have.property('item').to.have.property('hash').to.equal(hash);
          done(err);
        });
    });
  });
});

It follows a similar structure to what we've been doing so far. Let’s take a look:

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:

// Test script in package.json file
"test": "mocha ./src/tests/*.spec.js --exit",

This makes sure your tests exit once finished.

There we go on our successful tests streak 🚀:

To test protected routes, simply pass the authentication headers or auth credentials when making the request. You can read more on supertest documentation.

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.

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:

// Generates a new unique hash for an existing item
function getUniqueHash(item) {
  const currentHash = item.hash;
  let newHash = nanoid(10);

  while (newHash === currentHash) {
    newHash = nanoid(10);
  }
  return newHash;
}

And here's one unit test:

describe('Test getUniqueHash'), () => {
  it('should return a new hash', () => {
    const item = {
      hash: '1234567890',
    };
    const newHash = getUniqueHash(item);
    expect(newHash).to.not.equal(item.hash);
  });
});

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.

The situation does not change even if we stub the nanoId result. The library can (mistakenly) choose to return a different output in the future. While we cannot control it, we can prepare for it with a unit test covering that scenario.

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

1. In the first step, let's install nyc:

npm install -D nyc

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

   
   

// coverage script in package.json file
"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, and the rest of them fail.
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.

🚢 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 test journey.

We covered a lot of ground in this article. We talked about the benefits of unit testing, how can we integrate it into our Express.js API, and use stubs to mock external libraries and private functions. We also touched on the code 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 ✌.

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

Also published here.