Show some love for Mocha api tests! Setting up #1

Introduction

In this story I will build simple restful api with Express and MongoDB. I will set up testing environment with Docker-Compose and write api tests for all my endpoints without any mocks.

About me

I have been a Nodejs enthusiast for almost three years already from entry level developer, to junior full stack engineer and now mid level developer. My career mostly consists of full stack development with Javascript& Typescript frameworks and libraries like AngularJS, ExpressJS, React. I am also somewhat experienced with Devops side of software engineering with tools like Terraform, Docker, Teamcity, Nginx and so on. My current position title is AWS cloud engineer and that’s not only my job but also a hobby as well — mastering AWS cloud.

Prerequisites

1. NodeJS v12.6.0 or newer;
2. NPM v6.14.0 or newer;
3. Docker v19.03.13 or newer;
4. Docker-compose v1.27.4 or newer;
5. Visual Studio Code (or any other code editor of your preference);
6. JavaScript and software development entry/junior level knowledge.

Let’s start setting up!

Initialise the project with npm init command.

npm init command

Then, install express, mongoose, mocha and jsonschema for body validation.

installing dependencies

Scaffold project structure.

project structure

Initialise Express application with connection to Mongodb

This is very simple. Great practice is to separate actual express application from web server, hence two separate files were created: app.js and server.js (entry point of the application). Mongo-connect.js module speaks for itself — it connects to Mongo database by using mongoose library. Config.js file will hold all the configuration variables like port, mongo connection string etc, usually these things should come from env variables, but for the purpose of simplicity I will hardcode them. And routes directory — here is the place where our actual api is going to live.

express application definition — app.js

configuration file — config.js

actual http server — server.js

connection to mongodb with mongoose — mongo-connect.js

Is something missing?

Yes indeed. Mongodb server running on docker. Here is a nice example of docker compose file for Mongodb:

docker-compose for dev env

But let me duplicate this file and create another one called docker-compose-tests.yaml:

docker-compose for tests env

Have you noticed the little difference? That’s right — ports. Development environment will use default 27017 port, but testing environment — 17017. That’s how we can simply ensure that we will have to separate servers for both environments. Also, here is a small update in config.js file:

new entry for tests Mongodb connection string in config.js file

Let’s start both of these containers, the commands are almost identical (don’t forget to have docker service running on your machine):

docker-compose up -d — this will launch the development compose file.

docker-compose -f docker-compose-tests.yaml up-d — this will launch the testing compose file.

To bring the services down use the same commands but instead of keyword up use keyword down.

You can validate that the containers are running with docker container ls :

docker container ls result

Create a model and register routes

I’m going to create a simple CRUD api for Items resource. The item model is going to be very simple:

Item model

Notice that I have created models/Item.js directory and module.

Next up — registering router:

Empty Items router — routes/items.js

Api routes definition and exporter file — routes/index.js

Registering it right after express.json middleware in app.js file

Time for restful api!

Here are five basic crud api endpoints: GET /, GET /:id, POST /, PUT /:id, DELETE /:id.

Mocked routes

Now I’m going to do two things — set up jsonschema validator and install express-async-wrap to handle all async errors.

jsonschema validator implementation

Now the easiest part — implementing all http api endpoints.

GET / — very simple api endpoint, it supports two query parameters — size and page and only allows maximum of 100 items to be retrieved at once and defaults to 10. Also, notice the X-Total-Count header which returns how many items there are in the database.

GET /api/items

GET /:id — even smaller api endpoint, but don’t forget to validate incoming id!

GET /api/items/:id

POST / — create new item in the database, but this has a key moment — always validate incoming request body. Also, notice updateItem function — this will explicitly use only wanted fields from DTO (data transfer object). Both schema and updateItem function can and should be reused for PUT /:id endpoint.

POST /api/items

PUT /:id has to validate both req.params.id and incoming body.

PUT /api/items/:id

DELETE /:id — no twists and you got it right — this has to validate req.params.id:

DELETE /api/items/:id

Also, don’t forget to update error handler in app.js after introducing NotFound error:

error handler in app.js

That’s it.

We have our api, you can test it via postman, curl or any other tool you prefer. Next story will only consist of api integration tests with no mocks and dedicated Mongodb we have set up. You can find a second part by clicking here.