DEV Community: Dyarlen Iber

Hexagonal Architecture and Clean Architecture (with examples)

Dyarlen Iber — Wed, 10 Aug 2022 22:51:22 +0000

Hexagonal Architecture and Clean Architecture

One of the things that changed my career as a software developer and changed my perspective on how to build software is the knowledge of how to architect my applications, and how to design my code in a more professional way, allowing my applications to scale.

BTW, I'm creating a series of videos about Clean Architecture with Typescript, where I'll build a real-world API, exploring a bunch of cool features and concepts, and how to implement them using Clean Architecture.

If that sounds interesting, and you want to go beyond simple CRUDs with MVC, you can check out the Playlist on YouTube, and the GitHub repository of this project.

We will cover in the last session of this article some next steps and examples you can follow, but if you are looking for an example of how to apply Clean Architecture to a project with Typescript, you can take a look at this repository.

Keep reading to understand the concepts better and why I believe the best way to understand Clean Architecture is to understand Hexagonal Architecture first :)

Normally when we start to develop software, especially when we use some framework, we tend to always use that well-known MVC pattern, dividing our application into models, views, and controllers.
This is not that bad if you are building some simple, such as an MVP for example, however as we need to scale this application, add more features, replace a library, or something like that, we face several issues because as our code tends to get more coupled it becomes more and more difficult to make changes in our application without having to also change a lot of different places in our code.

With that our software becomes more susceptible to bugs and demotivates all the developers who need to maintain that code. And this is extremely common, mainly if you're just starting, we're not usually taught how to architect our application, we generally let some framework make the decision for us, and we end up putting all the business logic inside the controller for example.
I remember doing this a lot when I was starting my career, and I remember being rejected in many interviews mostly for those companies that were looking for someone more senior or mid-level.

With that said, my main goal in this article is to give you a better understanding of how to architect your application, by separating the software into layers, and how to organize and isolate your business logic, so you will no longer squeeze everything inside the controller.

Hexagonal Architecture (Ports and Adapters Architecture)

Before diving into Clean Architecture, we will first take a brief look at Hexagonal Architecture (or Ports and Adapters Architecture, which I believe is a better name).

The Hexagonal Architecture (also known as Ports and Adapters Architecture) is a software architecture that is based on the idea of isolation of the core business logic from outside concerns by separating the application into loosely coupled components.

I took this image from this Netflix blog post.

Let's imagine that we are building an API that needs to fetch some data from a REST API.

Instead of having our use case class (or service class) tightly coupled to the external REST API, we can simply create a Port, which defines the interface that our use case class needs to implement to fetch the data (independently of how the data is fetched, using a REST API, a database, a GraphQL API, etc.). And then we can create n Adapter, which is a class that implements the Port interface and delegates the calls to the external REST API (or another external service).

This way, if we need to change the way we fetch the data, we only need to create a new Adapter that implements the Port interface, without having to change the use case implementation.

Before seeing some practical examples of how to create these Ports and Adapters, I want you to take a look at these two quotes from this blog post, which I believe summarize the main idea of the Hexagonal Architecture:

“The idea of Hexagonal Architecture is to put inputs and outputs at the edges of our design. Business logic should not depend on whether we expose a REST or a GraphQL API, and it should not depend on where we get data from — a database, a microservice API exposed via gRPC or REST, or just a simple CSV file.”

“The pattern allows us to isolate the core logic of our application from outside concerns. Having our core logic isolated means we can easily change data source details without a significant impact or major code rewrites to the codebase.”

It's important to note that Hexagonal Architecture came before Clean Architecture, however, both share the same objective, which is the separation of concerns.
In fact, the Hexagonal Architecture was one of the architectural patterns that Robert C. Martin (Uncle Bob - author of Clean Architecture) used as a reference to the Clean Architecture.

However, Hexagonal Architecture lacks some implementation details, that is where the Clean Architecture comes in, to fill in these "gaps".

Typescript example

Let's take a look at the Hexagonal Architecture in action using TypeScript.

One of the ways to create those Ports and Adapters is by using the Dependency Inversion Principle, the last SOLID principle (and this is kind of a spoiler for Clean Architecture).

The Dependency Inversion Principle states that:

"High-level modules should not import anything from low-level modules. Both should depend on abstractions (e.g., interfaces)."

"Abstractions should not depend on details. Details (concrete implementations) should depend on abstractions."

Let's suppose we want to create a use case class to export a user.

If you are not familiar with the concept of use cases, don't worry, we will cover it in more detail in the Clean Architecture section.

But for now, just keep in mind that a use case class (or service class in the Domain-Driven Design terminology) is a class that is responsible for a specific user action (intention). Such as fetching an order, creating a product, updating a user, deleting an article, etc.
And usually, a controller class (responsible for handling the user requests) invokes the use case class to perform the user action.

And the most common way to do this is by having the use case class (or even the controller) tightly coupled to the export logic.

But instead of doing this, we can create an interface to abstract the export logic (Port):



type User = {
    name: string,
    email: string,
    dateOfBirth: Date
};

// Port interface
interface ExportUser {
    export(user: User);
}

And then create one (or more) implementations of this interface (Adapter):



// CSV Adapter implementation
class ExportUserToCSV implements ExportUser {
    export(user) {
        // Export user to a CSV file
    }
}

// PDF Adapter implementation
class ExportUserToPDF implements ExportUser {
    export(user) {
        // Export user to a PDF file
    }
}

Doing this, the implementation of the user export will depend on the interface (abstraction), as the Dependency Inversion Principle states.
And the use case class will not be dependent on any concrete implementation:



// Use case class
class ExportUserUseCase {
    constructor(private exportUser: ExportUser) {}

    execute(user: User) {
        this.exportUser.export(user);
    }
}

Finally, we can switch between different implementations of the user export, without having to change the use case class implementation:



// Export user to a CSV file
const exportUserToCSV = new ExportUserToCSV();
const exportUserUseCase = new ExportUserUseCase(exportUserToCSV);

exportUserUseCase.execute({
    name: 'John Doe',
    email: 'john.doe@mail.com',
    dateOfBirth: new Date()
});



// Export user to a PDF file
const exportUserToPDF = new ExportUserToPDF();
const exportUserUseCase = new ExportUserUseCase(exportUserToPDF);

exportUserUseCase.execute({
    name: 'John Doe',
    email: 'john.doe@mail.com',
    dateOfBirth: new Date()
});

Clean Architecture

Now, after having a look at Hexagonal Architecture, we can start to get a better look at what Clean Architecture is about.

Hexagonal Architecture and many other architectural patterns share the same goal: the separation of concerns. And they all achieve this goal by dividing the application into layers.
And the Clean Architecture is just an attempt at integrating all these architectures into a single idea.

It's important to mention that the Clean Architecture is NOT just a folder structure that you can copy and paste to your project.
It's the idea of separating the application into layers, and conforming to The Dependency Rule, creating a system that is:

Independent of Frameworks
Testable
Independent of UI
Independent of Database
Independent of any external agency

To start, let's go through the layers of the Clean Architecture:

Entities (Domain Layer)

This Layer is responsible for the business logic of the application.
It's the most stable layer, and it's basically the heart of the application.

Here is where we can apply some Domain-Driven Design tactics, such as Aggregates, Value Objects, Entities, Domain Services, etc.
By the way, the title of the book that introduced the concept of Domain-Driven Design in 2004, is "Domain-Driven Design: Tackling Complexity in the Heart of Software", by Eric Evans.

This layer is isolated from the rest of the application (outer layers concerns).

Use Cases (Application Layer)

This layer contains the application specific business rules. It implements all the use cases of the application, it uses the domain classes, but it is isolated from the details and implementation of outer layers, such as databases, adapters, etc.
This layer just holds interfaces to interact with the outside world.

As we have seen before, use cases are the user actions, or the user intentions, like fetching an order, creating a product, and so on.
And each use case must be independent of the other use cases, to be compliant with the Single Responsibility Principle (the first SOLID principle).

Example:



import { GetPostByIdUseCase } from '@application/interfaces/use-cases/posts/GetPostByIdUseCase';
import { GetPostByIdRepository } from '@application/interfaces/repositories/posts/GetPostByIdRepository';
import { PostNotFoundError } from '@application/errors/PostNotFoundError';

export class GetPostById implements GetPostByIdUseCase {
    constructor(
        private readonly getPostByIdRepository: GetPostByIdRepository,
    ) {}

    async execute(postId: GetPostByIdUseCase.Input): Promise<GetPostByIdUseCase.Output> {
        const post = await this.getPostByIdRepository.getPostById(postId);
        if (!post) {
            return new PostNotFoundError();
        }
        return post;
    }
}

In this example, we have an interface (GetPostByIdUseCase) that contains the Input and Output of the use case, which are the DTOs (Data Transfer Objects), that are used together with other interfaces (like the GetPostByIdRepository interface) to interact with the outside world.

Note that this use case is only responsible for fetching a post by its ID, in case we need to delete a post, we need to create another use case.
It's very common when working with MVC pattern for example, to have a gigantic controller class that handles all the user requests. However, it hurts the Single Responsibility Principle.

Interface Adapters (Infrastructure Layer)

The Infrastructure layer is the layer that contains all the concrete implementations of the application, like the repositories, the adapters, the database connections, etc.

Frameworks & Drivers

This layer is composed of frameworks and tools such as the Database, the Web Framework, etc.
Usually, we don’t write much code in this layer.

Only Four layers?

There’s no rule that says you must always have just these four layers. However, The Dependency Rule always applies.

The Dependency Rule

The Dependency Rule states that:

"Source code dependencies can only point inwards."

"Nothing in an inner circle can know anything at all about something in an outer circle."

Basically, the name of something declared in an outer circle must NOT be mentioned by the code in an inner circle. That includes, functions, classes. variables, or any other named software entity.
We don’t want anything in an outer circle to impact the inner circles.

For example, in the domain layer, we must NOT mention anything within the application layer, or within the infrastructure layer. The same goes for the application layer, we must NOT mention anything within the infrastructure layer, and so on.

But obviously, we can use the entities defined within the domain layer within the application layer for example.

Final thoughts and next steps

Clean Architecture is a great architectural pattern to follow if you want to design a large-scale application (and go beyond the simple CRUDs with the MVC pattern).
It will help you to write a clean, flexible, testable, and maintainable code, by separating the application into layers.

In addition, if you want to get even better at organizing your business logic, and modeling the domain of your application, you can also take advantage of the Domain-Driven Design. Clean Architecture when combined with Domain-Driven Design is a really powerful tool!

If you want to learn more about Clean Architecture, you can also check out the Clean Architecture book, or the Clean Architecture blog post.
A fun fact is that everything you need to know about Clean Architecture is already in this blog post, all the pages that mention Clean Architecture in the book are also in the blog post.
Of course, if you have the opportunity to read the book, I highly recommend it, but it's important to know that all the concepts are already explained in this blog post.

And if you want to take a look in a code example, of how to use Clean Architecture in a project, you can also check out this repository: Simple Blog Application: backend challenge.
Where I created a Simple Blog API built with TypeScript and MongoDB, using TDD, Clean Architecture, SOLID principles, Design Patterns, and some DDD patterns.
It was part of a backend coding challenge, so it has some other interesting features, like authentication with JWT, a CI Workflow with GitHub Actions, a local environment with Docker and Docker Compose, and a documentation.

It's a good example to understand how to use Clean Architecture, but remember that Clean Architecture is not about the folder structure, you can use it as a reference, but each project will have its own specific implementation needs.
In this project, I created a directory for each layer inside the src folder. Besides the domain layer, the application layer, and the infrastructure layer, I created an additional layer for acting as an entry point for the application, it is the layer that contains the Express server, and where all the routes are defined. In this layer I also compose all the controllers, middlewares, and use cases, injecting the dependencies that are needed, since I am not using any dependency injection container.
But you can get more information in the README.md file of the project.

Last but not least, I'm creating a series of videos about Clean Architecture with Typescript, where I'll build a real-world API, exploring a bunch of cool features and concepts, and how to implement them using Clean Architecture.
These are some topics we are going to see:

OOP with Typescript
Clean Architecture
SOLID Principles
Design Patterns
DDD Patterns
REST / GraphQL
Git
- Conventional Commits
JWT authentication
Roles and Permissions
Integrations
- Google APIs
- AWS
- Email services
Advanced MongoDB
- MongoDB Indexes
- MongoDB Schemas
- MongoDB Transactions
- Migrations
Docker and Docker Compose
TDD using Jest
- Unit
- Integration
- E2E
CI Workflow using GitHub Actions
API Documentation using Swagger
Deployment

And more!

If that sounds interesting, and you want to go beyond simple CRUDs with MVC, you can check out the Playlist on YouTube, and the GitHub repository of this project.

Thank you!

Setting up a CI/CD workflow on GitHub Actions for a React App (with GitHub Pages and Codecov)

Dyarlen Iber — Fri, 19 Jun 2020 01:36:42 +0000

In this tutorial, I'm going to show you how to create a simple workflow that I use on my personal projects with React.

This workflow created on GitHub Actions will be responsible for automatically test the source code, generate a test coverage report and upload it on Codecov, build and deploy the project on GitHub Pages. All these jobs are activated by a push or pull request event on master branch.

All the source code can be found in this repository:

dyarleniber / react-workflow-gh-actions

Source code of the post: Setting up a CI/CD workflow on GitHub Actions for a React App (with GitHub Pages and Codecov)

Getting started

GitHub Actions allows you automate, customize, and execute software development workflows right in your GitHub repository.

A workflow is a configurable automated process made up of one or more jobs. You can configure your workflows to run when specific activity on GitHub happens, at a scheduled time, or when an event outside of GitHub occurs.

The workflow configuration is define by a YAML file. GitHub provides preconfigured workflow templates.

First, on your React App GitHub repository, navigate to the main page of the repository, click Actions.

Then, you'll see suggestions of CI templates that are the best fit for your project. You can use workflow templates as a starting place to build your custom workflow.
In this case, click Set up this workflow, under the name of the template Node.js.

Finally, you'll see a default YAML file like this:



# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions

name: Node.js CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [10.x, 12.x, 14.x]

    steps:
    - uses: actions/checkout@v2
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

There are 2 events that trigger the workflow on push or pull request. The virtual environment used to run the workflow is an Ubuntu machine in the latest version.

In the steps section, 2 actions and 3 NPM scripts are being used. The first action actions/checkout@v2 is a standard that you must include in your workflow before other actions when your workflow requires a copy of your repository's code. The second one, as the name suggests, it is a set up for Node.js, as you can see, the set up is made in different versions of Node.js, through an array with all the versions used.

Besides these actions, you can browse and search for actions in GitHub Marketplace to use in your workflows.

GitHub Marketplace is a central location for you to find actions created by the GitHub community.

Test coverage report generation

Let's start changing the name, the Node.js version and the NPM scripts used in the workflow:



name: CI/CD

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [12.x]

    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - name: Set up Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}

    - name: Install dependencies
      run: npm install

    - name: Run the tests
      run: npm test

    - name: Build
      run: npm run build

After set up Node.js, now, we are installing the dependencies, running the tests and building the application.

You can define a name for each step.

Now, we are going to use Codecov to upload and compare test coverage reports. Codecov is one of the most popular code coverage solution, and it's totally free for open source projects.

First, go to the Codecov website and create an account, you can use your GitHub account to sign up.

Next, access your account on the website, click Repositories, after, click Add new repository and choose the repository you want to use.

You will see a token, that token will not be useful if your repository is public, otherwise, if your repository is private, you must copy it, as you will need to use it later.

There is an action available in GitHub Marketplace, that easily upload reports to Codecov, we will use it.

The first thing we need to do is change the npm test command to generate the test reports:



- name: Run the tests and generate coverage report
  run: npm test -- --coverage

After that, include the following action in the workflow:



- name: Upload coverage to Codecov
  uses: codecov/codecov-action@v1

If you repository is private, you must include the codecov token, through a secret that makes your token accessible in the workflow. Like this:



- name: Upload coverage to Codecov
  uses: codecov/codecov-action@v1
  with:
    token: ${{ secrets.CODECOV_TOKEN }}

We'll create a secret on GitHub for deployment in a moment.

Deployment on GitHub Pages

We'll use GitHub Pages to deploy our application. GitHub Pages are public pages hosted and published through GitHub.

Before adding new steps to the workflow, we need to install and configure a new package in the project.

Add homepage to package.json.

Open your package.json and add a homepage field for your project:



"homepage": "https://myusername.github.io/my-app",

Install gh-pages and add deploy to scripts in package.json.

Run:



$ npm install --save gh-pages

Add the following scripts in your package.json:



"predeploy": "npm run build",
"deploy": "gh-pages -d build",

The predeploy script will run automatically before deploy is run.

Now we are going to create a new access token, in order to deploy our application through the workflow.

Go to the Personal access tokens area in the Developer settings of your GitHub profile and click Generate new token.

Fill up a note (What's this token for?) and in the repo scope, select only the first 4 options.

Copy the generated token.

Now, in order to use this token in the workflow on GitHub Actions, we have to create a secret for our repository.

Secrets are encrypted environment variables that allows you to store sensitive information in your repository. The secrets you create are available to use in GitHub Actions workflows.

On GitHub, navigate to the main page of the repository, under your repository name, click Settings. In the left sidebar, click Secrets. And finally, Click Add a new secret.

Type a name for your secret in the Name input box, like ACTIONS_DEPLOY_ACCESS_TOKEN.

Enter the value for your secret (which should be the personal access token we just created).

Click Add secret.

Finally, we can include the script npm run deploy as the last step in our workflow.

But, before that, we should make some configurations in the Git. To ensure that it will have all the necessary access to be able to deploy the application.

Your last step on your workflow should be some like this:



- name: Deploy
  run: |
    git config --global user.name $user_name
    git config --global user.email $user_email
    git remote set-url origin https://${github_token}@github.com/${repository}
    npm run deploy
  env:
    user_name: 'github-actions[bot]'
    user_email: 'github-actions[bot]@users.noreply.github.com'
    github_token: ${{ secrets.ACTIONS_DEPLOY_ACCESS_TOKEN }}
    repository: ${{ github.repository }}

The name and email information need not necessarily be your real information. And you must replace ACTIONS_DEPLOY_ACCESS_TOKEN with the name of the secret you just created.

The github.repository variable will automatically get the name of your repository.

To learn more about environment variables on GitHub Actions, please, read this article.

After adding the deploy command on your workflow, click Start commit, and click Commit new file.

Your final workflow file should be like this:



name: CI/CD

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [12.x]

    steps:
    - name: Checkout repository
      uses: actions/checkout@v2

    - name: Set up Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}

    - name: Install dependencies
      run: npm install

    - name: Run the tests and generate coverage report
      run: npm test -- --coverage

    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v1

    - name: Build
      run: npm run build

    - name: Deploy
      run: |
        git config --global user.name $user_name
        git config --global user.email $user_email
        git remote set-url origin https://${github_token}@github.com/${repository}
        npm run deploy
      env:
        user_name: 'github-actions[bot]'
        user_email: 'github-actions[bot]@users.noreply.github.com'
        github_token: ${{ secrets.ACTIONS_DEPLOY_ACCESS_TOKEN }}
        repository: ${{ github.repository }}

Make sure GitHub Pages option in your GitHub project settings is set to use the gh-pages branch:

Now, in every push or pull request event on master branch, the CI/CD workflow will be activated. And you will be able to see if all steps have passed or not.

Adding status badges

You can also add a workflow status badge to your repository. Status badges show whether a workflow is currently failing or passing. A common place to add a status badge is in the README.md file of your repository, but you can add it to any web page you'd like.

This is the default URL for adding a workflow status badge provided by GitHub Actions:



https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg

If your workflow uses the name keyword, you must reference the workflow by name. If the name of your workflow contains white space, you'll need to replace the space with the URL encoded string %20.

For more information about GitHub Actions workflow status badge, read this article.

For instance, this will be the badge that I will put in my README.md file:



![CI/CD](https://github.com/dyarleniber/react-workflow-gh-actions/workflows/CI/CD/badge.svg)

Codecov also provided a badge you can use in your projects. This is an example of an URL:



[![codecov](https://codecov.io/gh/<OWNER>/<REPOSITORY>/branch/master/graph/badge.svg)](https://codecov.io/gh/<OWNER>/<REPOSITORY>)

In my case, my URL will be:



[![codecov](https://codecov.io/gh/dyarleniber/react-workflow-gh-actions/branch/master/graph/badge.svg)](https://codecov.io/gh/dyarleniber/react-workflow-gh-actions)

You can also use this amazing website: Shields.io to customise your badges. Accessing the website you will see many options of badges categories you can use, such as Build, Code Coverage, Size, Downloads, License and so on. In each category you can select the service you are using, fill up the name of the repository, customise as you prefer, and copy the link of the badge.

For example, this will be my custom coverage badge:



[![Codecov](https://img.shields.io/codecov/c/github/dyarleniber/react-workflow-gh-actions)](https://codecov.io/gh/dyarleniber/react-workflow-gh-actions)

I also included a license badge:



![License](https://img.shields.io/github/license/dyarleniber/react-workflow-gh-actions)

These badges in your README.md file, should look like this:

You can explore the Shields.io website and see the different options of badges available.

Bonus: Caching dependencies

To make your workflows faster and more efficient, you can create and use caches for dependencies and other commonly reused files.

GitHub can cache dependencies you frequently use in workflows. Jobs on GitHub-hosted runners start in a clean virtual environment and must download dependencies each time, causing increased network utilization, longer runtime, and increased cost.

To cache dependencies for a job, you'll need to use GitHub's cache action. The action retrieves a cache identified by a unique key. For more information, see actions/cache.

In our case, we can create a new cache when the packages in package-lock.json file change, or when the runner's operating system changes. The cache key uses contexts and expressions to generate a key that includes the runner's operating system and a SHA-256 hash of the package-lock.json file.

You should include the following snippet of code before installing the dependencies:



    - name: Cache dependencies
      uses: actions/cache@v2
      with:
        path: |
          **/node_modules
        key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

The key is required. It is the key created when saving a cache and the key used to search for a cache. Keys have a maximum length of 512 characters.

The path is required. It is the file path on the runner to cache or restore. This can be an absolute path or relative to the working directory. The path input must be a directory. You cannot cache a single file.

The restore-keys is an optional parameter. It is an ordered list of alternative keys to use for finding the cache if no cache hit occurred for key.

The cache action will attempt to restore a cache based on the key you provide. When the action finds a cache, the action restores the cached files to the path you configure. If there is no exact match, the action creates a new cache entry if the job completes successfully. The new cache will use the key you provided and contains the files in the path directory.

References

Parallel tests in Node.js with Jest and MongoDB (without mocking)

Dyarlen Iber — Tue, 22 Oct 2019 23:57:15 +0000

It's a common practice when writing tests, provide a mock implementation for your database, the problem with this approach is that, if there is any error in a query, this error will never be caught.
In this post I will demonstrate how to run tests in parallel using a shared database without mocking. We will develop a rest API with some routes and integration tests.

All the source code developed in this post can be found in this GitHub repository.

First of all, if you don't have many tests, you might consider not running the tests in parallel, Jest has an option that allows test suites to run in series. Just use the --runInBand option, and you can use a Docker image to run a new instance of the database during testing.

jest --runInBand

However, if you have many tests this is definitely not a good option for you.

Let's start by installing some dependencies.

yarn add express mongoose dotenv

Now, let's create 2 files: app.js and server.js, inside a folder called src, which should contain all the source code of our application.

In the src/app.js file, we will create a new express instance that starts a server, and the src/server.js file will listens for connections on the specified host and port, we won't use this last file for testing, just to start development environment or production environment.

src/server.js

const app = require('./app');

app.listen(process.env.NODE_PORT || 3000);

src/app.js

require('dotenv').config();

const express = require('express');

const routes = require('./routes');

const databaseHelper = require('./app/helpers/database');

class App {
  constructor() {
    this.express = express();

    this.database();
    this.middlewares();
    this.routes();
  }

  database() {
    databaseHelper.connect();
  }

  middlewares() {
    this.express.use(express.json());
  }

  routes() {
    this.express.use(routes);
  }
}

module.exports = new App().express;

The database, middlewares and routes settings were set in the src/app.js file, the routes and the database configurations will be imported from other files (we'll talk about models and controllers later).
For testing purposes we will create only 2 routes (create and delete) for each resource (users and tasks).

src/routes.js

const express = require('express');

const UserController = require('./app/controllers/UserController');
const TaskController = require('./app/controllers/TaskController');

const routes = new express.Router();

routes.post('/users', UserController.store);
routes.delete('/users', UserController.delete);
routes.post('/tasks', TaskController.store);
routes.delete('/tasks', TaskController.delete);

module.exports = routes;

src/app/helpers/database.js

const mongoose = require('mongoose');

const connect = async () => {
  if (mongoose.connection.readyState === 0) {
    await mongoose.connect(
      process.env.NODE_ENV === 'test' ? global.__DB_URL__ : process.env.DB_URL,
      {
        useNewUrlParser: true,
        useCreateIndex: true,
        useFindAndModify: false,
        useUnifiedTopology: true,
      }
    );
  }
};

const truncate = async () => {
  if (mongoose.connection.readyState !== 0) {
    const { collections } = mongoose.connection;

    const promises = Object.keys(collections).map(collection =>
      mongoose.connection.collection(collection).deleteMany({})
    );

    await Promise.all(promises);
  }
};

const disconnect = async () => {
  if (mongoose.connection.readyState !== 0) {
    await mongoose.disconnect();
  }
};

module.exports = {
  connect,
  truncate,
  disconnect,
};

The database helper will be used later for testing.
Realize that, if the environment is test, the MongoDB URI used will be the one stored in the global variable __DB_URL__, in other environments, the environment variable DB_URL will be used. We'll talk about this again in a moment.

To finalize the development of the API, we will create the models the controllers.

src/app/models/User.js

const mongoose = require('mongoose');

const UserSchema = new mongoose.Schema(
  {
    name: {
      type: String,
      required: true,
    },
    email: {
      type: String,
      required: true,
      unique: true,
      lowercase: true,
    },
    password: {
      type: String,
      required: true,
    },
  },
  {
    timestamps: true,
  }
);

module.exports = mongoose.model('User', UserSchema);

src/app/models/Task.js

const mongoose = require('mongoose');

const TaskSchema = new mongoose.Schema(
  {
    title: {
      type: String,
      required: true,
    },
    description: {
      type: String,
      required: true,
    },
  },
  {
    timestamps: true,
  }
);

module.exports = mongoose.model('Task', TaskSchema);

src/app/controllers/UserController.js

const User = require('../models/User');

class UserController {
  async store(req, res) {
    try {
      const user = new User({
        name: req.body.name,
        email: req.body.email,
        password: req.body.password,
      });

      await user.save();

      return res.json({
        id: user._id,
        name: user.name,
        email: user.email,
      });
    } catch (err) {
      return res.status(500).json({ error: 'Internal server error' });
    }
  }

  async delete(req, res) {
    try {
      const user = await User.findById(req.body.id);

      if (user) {
        await user.remove();
      }

      return res.send();
    } catch (err) {
      return res.status(400).json({ error: 'User not found' });
    }
  }
}

module.exports = new UserController();

src/app/controllers/TaskController.js

const Task = require('../models/Task');

class TaskController {
  async store(req, res) {
    try {
      const task = new Task({
        title: req.body.title,
        description: req.body.description,
      });

      await task.save();

      return res.json(task);
    } catch (err) {
      return res.status(500).json({ error: 'Internal server error' });
    }
  }

  async delete(req, res) {
    try {
      const task = await Task.findById(req.body.id);

      if (task) {
        await task.remove();
      }

      return res.send();
    } catch (err) {
      return res.status(400).json({ error: 'Task not found' });
    }
  }
}

module.exports = new TaskController();

Now, we will begin the development of our test environment. Let's start by installing our development dependencies.

yarn add jest supertest mongodb-memory-server -D

Jest will be our test runner and SuperTest will help us with integration testing. And the mongodb-memory-server will be very useful for starting a new dedicated MongoDB instance for each test suite. Let's talk later about configuring this dependency, but you can read more about it here.

Let's create a class to encapsulate all the configuration needed for the mongodb-memory-server.

src/lib/MemoryDatabaseServer.js

const { MongoMemoryServer } = require('mongodb-memory-server');

class MemoryDatabaseServer {
  constructor() {
    this.mongod = new MongoMemoryServer({
      binary: {
        version: '4.0.3',
      },
      autoStart: false,
    });
  }

  start() {
    return this.mongod.start();
  }

  stop() {
    return this.mongod.stop();
  }

  getConnectionString() {
    return this.mongod.getConnectionString();
  }
}

module.exports = new MemoryDatabaseServer();

In the constructor method we create a new instance of the MongoMemoryServer, and we can provide some options, in this case we will set a binary version of MongoDB, and the autoStart option to false avoids the automatic download of the binary at the moment we instantiate the class, so the download will be made only when we call the start method defined below. The stop method should be called at the end of all tests.

On install, the mongodb-memory-server package downloads the latest MongoDB binaries and saves it to a cache folder. Then, when the start method is invoked, if the binary cannot be found, it will be auto-downloaded. So, the first run may take some time. All further runs will be fast, because they will use the downloaded binaries.

The getConnectionString method will be responsible for returning a valid MongoDB URI for each test suite, the return of this method will be stored in the global variable __DB_URL__ mentioned before.

About Jest, we can create a jest settings file using the following command:

yarn jest --init

At the end, there should be a file called jest.config.js in the project root. Let's make some modifications in the following attributes:

{
  globalSetup: '<rootDir>/__tests__/setup.js',
  globalTeardown: '<rootDir>/__tests__/teardown.js',
  setupFilesAfterEnv: ['<rootDir>/__tests__/setupAfterEnv.js'],
  testEnvironment: '<rootDir>/__tests__/environment.js',
  testMatch: ['**/__tests__/**/*.test.js']
}

testMatch is used by Jest to detect test files.

globalSetup is a path to a module which exports an async function that is triggered once before all test suites.

tests/setup.js

const MemoryDatabaseServer = require('../src/lib/MemoryDatabaseServer');

module.exports = async () => {
  await MemoryDatabaseServer.start();
};

globalTeardown is a path to a module which exports an async function that is triggered once after all test suites.

tests/teardown.js

const MemoryDatabaseServer = require('../src/lib/MemoryDatabaseServer');

module.exports = async () => {
  await MemoryDatabaseServer.stop();
};

setupFilesAfterEnv is a list of paths to modules that run some code to configure or set up the testing framework before each test.

tests/setupAfterEnv.js

require('dotenv').config();

const databaseHelper = require('../src/app/helpers/database');

beforeAll(() => {
  return databaseHelper.connect();
});

beforeEach(() => {
  return databaseHelper.truncate();
});

afterAll(() => {
  return databaseHelper.disconnect();
});

testEnvironment is the test environment that will be used for testing.

tests/environment.js

const NodeEnvironment = require('jest-environment-node');

const MemoryDatabaseServer = require('../src/lib/MemoryDatabaseServer');

class CustomEnvironment extends NodeEnvironment {
  async setup() {
    await super.setup();

    this.global.__DB_URL__ = await MemoryDatabaseServer.getConnectionString();
  }

  async teardown() {
    await super.teardown();
  }

  runScript(script) {
    return super.runScript(script);
  }
}

module.exports = CustomEnvironment;

We are almost done. Now, we'll develop the tests for our routes, the SuperTest will be used for the integration tests.

tests/integration/user.test.js

const supertest = require('supertest');

const app = require('../../src/app');

const UserModel = require('../../src/app/models/User');

const request = supertest(app);

describe('User', () => {
  it('should be able to create user', async () => {
    const response = await request.post('/users').send({
      name: 'userName',
      email: 'useremail@email.com',
      password: '123123',
    });

    expect(response.status).toBe(200);
  });

  it('should be able to delete user', async () => {
    const user = new UserModel({
      name: 'existsUserName',
      email: 'existsUseremail@email.com',
      password: '123123',
    });

    await user.save();

    const response = await request.delete('/users').send({
      id: user._id,
    });

    expect(response.status).toBe(200);
  });
});

tests/integration/task.test.js

const supertest = require('supertest');

const app = require('../../src/app');

const TaskModel = require('../../src/app/models/Task');

const request = supertest(app);

describe('Task', () => {
  it('should be able to create task', async () => {
    const response = await request.post('/tasks').send({
      title: 'taskTitle',
      description: 'taskDescription',
    });

    expect(response.status).toBe(200);
  });

  it('should be able to delete task', async () => {
    const task = new TaskModel({
      title: 'existsTaskTitle',
      description: 'existsTaskDescription',
    });

    await task.save();

    const response = await request.delete('/tasks').send({
      id: task._id,
    });

    expect(response.status).toBe(200);
  });
});

In the package.json file we must configure the test script to set the environment variable before calling jest, and you can use the src/server.js file mentioned before to start a development environment, like this:

{
  "scripts": {
    "dev": "node src/server.js",
    "test": "NODE_ENV=test jest"
  }
}

Finally, just run the following command to start the tests:

yarn test

Obrigado!