DEV Community: K. Siva Prasad Reddy

SpringBoot Integration Testing using TestContainers Starter

K. Siva Prasad Reddy — Mon, 03 Feb 2020 05:53:58 +0000

One of the many reasons for huge popularity of Spring and SpringBoot is
it's great support for Testing.
We can write unit tests using Mockito without requiring any Spring features. And, we can write Integration Tests using Spring testing support by creating Spring ApplicationContext.

Read Guide to Testing SpringBoot Applications

While running integration tests we might need to interact with external services like relational databases, NoSQL datastores, Kafka etc. We can spin up those external services as Docker containers and run tests against them.

Testcontainers

From Testcontainers docs:

Testcontainers is a Java library that supports JUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.

We can use Testcontainers to spin up a Singleton docker container
in a SpringBoot integration test as follows:

@SpringBootTest
@ContextConfiguration(initializers = {UserServiceIntegrationTest.Initializer.class})
class UserServiceIntegrationTest {
    private static PostgreSQLContainer sqlContainer;

    static {
        sqlContainer = new PostgreSQLContainer("postgres:10.7")
                .withDatabaseName("integration-tests-db")
                .withUsername("sa")
                .withPassword("sa");
        sqlContainer.start();
    }

    static class Initializer implements ApplicationContextInitializer<ConfigurableApplicationContext> {
        public void initialize(ConfigurableApplicationContext configurableApplicationContext) {
            TestPropertyValues.of(
              "spring.datasource.url=" + sqlContainer.getJdbcUrl(),
              "spring.datasource.username=" + sqlContainer.getUsername(),
              "spring.datasource.password=" + sqlContainer.getPassword()
            ).applyTo(configurableApplicationContext.getEnvironment());
        }
    }

    @Autowired
    private UserService userService;

    @Test
    void shouldGetAllUsers() {
        // test userService.getAllUsers()
    }   

}

This is such a very common requirement in SpringBoot applications, so the community built Testcontainers SpringBoot starter to make it more easy.

Testcontainers SpringBoot starter

The Testcontainers SpringBoot starter depends on spring-cloud-starter. If you are NOT already using any SpringCloud starters in the application then include spring-cloud-starter as a test dependency.

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter</artifactId>
    <scope>test</scope>
</dependency>

Now include data service library depending on what data service you need.
For example if you want to use Postgresql docker container then add the following dependency:

<dependency>
    <groupId>com.playtika.testcontainers</groupId>
    <artifactId>embedded-postgresql</artifactId>
    <scope>test</scope>
</dependency>

When you add the embedded-postgresql dependency then following properties will be added to the Environment:

embedded.postgresql.port
embedded.postgresql.host
embedded.postgresql.schema
embedded.postgresql.user
embedded.postgresql.password

We can use these properties to configure datasource properties for testing.

Usually we want to spin up docker containers for integration tests but not for unit tests. So we can disable it by default and only enable during integration tests by using profile based configuration.

src/test/resources/bootstrap.properties

embedded.postgresql.enabled=false

src/test/resources/bootstrap-integration-test.properties

embedded.postgresql.enabled=true
spring.datasource.driver-class-name=org.postgresql.Driver
spring.datasource.url=jdbc:postgresql://${embedded.postgresql.host}:${embedded.postgresql.port}/${embedded.postgresql.schema}
spring.datasource.username=${embedded.postgresql.user}
spring.datasource.password=${embedded.postgresql.password}

Now we can run integration tests with integration-test profile using @ActiveProfiles as follows:

@SpringBootTest
@ActiveProfiles("integration-test")
class UserServiceIntegrationTest {

    @Autowired
    private UserService userService;

    @Test
    void shouldGetAllUsers() {
        // test userService.getAllUsers()
    }   

}

We may want to use specific version of a docker image, then you can configure it as follows:

src/test/resources/bootstrap-integration-test.properties

embedded.postgresql.dockerImage=postgres:10.7
embedded.postgresql.enabled=true

The Testcontainers SpringBoot starter already provide support for most commonly used containers like Postgresql, MariaDB, MongoDB, Redis, RabbitMQ, Kafka, Elasticsearch etc.

To my surprise there is no direct support for MySQL as of now. But there is a simple workaround for this as described here https://github.com/testcontainers/testcontainers-spring-boot/issues/151.

Creating Yeoman based SpringBoot Generator

K. Siva Prasad Reddy — Wed, 29 Jan 2020 02:54:28 +0000

I have been working with Spring and SpringBoot for many years and
I needed to create lot of Spring(Boot) applications for various reasons like
blog posts, sample apps,
book sample code and for my personal learning as well.
So, I needed some tool/mechanism to quickly create Spring(Boot) application with most commonly used configuration.

I know we have the most popular SpringBoot Initializer to create SpringBoot applications.
But, it generates the application with only selected starter dependencies added and nothing more.

Most of the times I needed to configure some common properties in application.properties file, additional libraries like
Testcontainers, Zalando's Problem Spring Web etc. So, I thought of automating this repetitive work in some way.

As a first attempt I tried to automate this by creating various Maven archetypes
with various combination of technologies. It helped me to some extent but I had to refactor few things after generating the application.
Also, I couldn't find a way to include some dependencies/configuration conditionally based on user input.

As a second attempt I tried to extend SpringBoot Initializer
by adding new features. I felt it was okayish but not productive enough. In addition to that I need to host it somewhere and
make sure it is running all the times.

And then I thought of creating a Yeoman based generator.
First, I came to know about Yeoman when AngularJS 1.x was hot and there was an amazing Yeoman generator for
creating AngularJS applications. Later I stumbled upon JHipster which blew my mind.
JHipster is amazing and what you can build with JHipster in just 30 minutes is phenomenal.
However, there are certain JHipster features that does not fit for my personal preferences such as:

I like jar packaging
I like to use spring-boot-starter-* than configuring individual libraries
I like to have an option to generate application without spring-security
I prefer Flyway over Liquibase
I like to have only minimum and required configuration ie no AsyncConfiguration, LocaleConfiguration, CacheConfiguration, Logstash Logging etc.
I like .properties over .yml

So, I decided to write my own SpringBoot Generator using Yeoman and
I started creating generator-springboot.
And, I have implemented the generator to generate a SpringBoot application with following features:

SpringBoot REST API with jar type packaging
Generate CRUD operations along with Unit and Integration Tests
CORS configuration
Swagger UI Integration
Spring Data JPA integration with option to select databases like MySQL, Postgresql, MariaDB etc
Flyway or Liquibase data migration support
SpringBoot Actuator configuration
Integration with Config Server, Service Registry, Sleuth, Zipkin
TestContainers integration
JUnit 5
Docker configuration
Jenkinsfile

I thought of writing an article on how to create a Yeoman based generator so that others can also create their own generators if interested.

First of all there is wonderfully written Official Documentation on how to create our own Yeoman generator.
I strongly recommend to go through it.

How Yeoman Generators work?

To put it simply, Yeoman generator works as follows:

Create template file(s) with placeholders
Prompt user for inputs
Generate files by replacing the placeholders with user provided values

Okay, enough talk. Let's get to the business.

Create SpringBoot Yeoman Generator

There are some fundamental concepts to be understood which explained clearly in the documentation and repeating it over here is redundant.
So, once again I strongly recommend going through this official documentation to get some basic understanding of concepts https://yeoman.io/authoring/index.html.

Create a directory called generator-springboot and create the following files and directories inside generator-springboot as follows:

+- generator-springboot/
   +- package.json
   +- generators/
      +- app/
         +- index.js

package.json

{
  "name": "generator-springboot",
  "version": "0.0.1",
  "description": "A Yeoman generator for generating SpringBoot microservices",
  "files": ["generators"],
  "main": "index.js",
  "keywords": [
    "yeoman-generator",
    "java",
    "spring",
    "spring-boot",
    "microservice"
  ],
  "dependencies": {
    "yeoman-generator": "^4.0.1"
  }
}

generators/app/index.js

"use strict";
const Generator = require("yeoman-generator");

module.exports = class extends Generator {
  method1() {
    this.log("method 1 just ran");
  }

  method2() {
    this.log("method 2 just ran");
  }
};

During the development we can symlink to the npm package to run the generator.
From the root of your generator project (generator-springboot/ folder), type:

generator-springboot> npm link

And then run the generator as follows:

generator-springboot> yo springboot

It will execute both method1() and method2() and print the log statements on console.

As we have not explicitly mentioned any priority to the methods method1() and method2() ran with default priority as follows:

"use strict";
const Generator = require("yeoman-generator");

module.exports = class extends Generator {
  default: {
    method1() {
        this.log("method 1 just ran");
    }

    method2() {
        this.log("method 2 just ran");
    }
  }
};

Yeoman defines the following priorities so that we can hook up our custom logic at appropriate priority executions.

The available priorities are (in running order):

initializing - Your initialization methods (checking current project state, getting configs, etc)
prompting - Where you prompt users for options (where you’d call this.prompt())
configuring - Saving configurations and configure the project (creating .editorconfig files and other metadata files)
default - If the method name doesn’t match a priority, it will be pushed to this group.
writing - Where you write the generator specific files (routes, controllers, etc)
conflicts - Where conflicts are handled (used internally)
install - Where installations are run (npm, bower)
end - Called last, cleanup, say good bye, etc

Now let's create pom.xml template pom.xml.tpl and src/main/java/com/mycompany/demo/Application.java file in generators/app/templates folder as follows:

generators/app/templates/pom.xml.tpl

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.4.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.mycompany</groupId>
    <artifactId><%= appName %></artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name><%= appName %></name>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
</project>

Notice we have the placeholders with syntax <%= variableName %>.

generators/app/templates/src/main/java/com/mycompany/demo/Application.java

package com.mycompany.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Update generators/app/index.js as follows:

"use strict";
const Generator = require("yeoman-generator");

module.exports = class extends Generator {
  constructor(args, opts) {
    super(args, opts);
  }

  initializing() {
    this.log("Generating SpringBoot Application");
  }

  prompting() {
    const prompts = [
      {
        type: "string",
        name: "appName",
        message: "What is the application name?",
        default: "myservice"
      }
    ];

    return this.prompt(prompts).then(answers => {
      this.appName = answers.appName;
    });
  }

  writing() {
    this.fs.copyTpl(
      this.templatePath("pom.xml.tpl"),
      this.destinationPath(this.appName + "/pom.xml"),
      {
        appName: this.appName
      }
    );

    this.fs.copy(
      this.templatePath("src"),
      this.destinationPath(this.appName + "/src")
    );
  }

  end() {
    this.log(`Application ${this.appName} generated successfully`);
  }
};

As per the priorities order first initializing() block gets executed, then prompting() then writing() and finally end().
In prompting() we are asking user to provide application name and store it in appName variable for later use.

In writing() we are generating pom.xml file using the pom.xml.tpl template by replacing the appName placeholder with the user provided value. Also, we are copying the entire src directory.

Instead of storing each user input in separate variable and passing them explicitly to replace placeholders we can store all the user provided input values in a JSON object and pass it as follows:

"use strict";
const Generator = require("yeoman-generator");

module.exports = class extends Generator {
  constructor(args, opts) {
    super(args, opts);
    this.configOptions = this.options.configOptions || {};
  }

  initializing() {
    this.log("Generating SpringBoot Application");
  }

  prompting() {
    const prompts = [
      {
        type: "string",
        name: "appName",
        message: "What is the application name?",
        default: "myservice"
      },
      {
        type: "list",
        name: "appType",
        message: "Do you want to use WebMVC or WebFlux?",
        choices: [
          {
            value: "webmvc",
            name: "WebMVC"
          },
          {
            value: "webflux",
            name: "WebFlux"
          }
        ],
        default: "webmvc"
      }
    ];

    return this.prompt(prompts).then(answers => {
      Object.assign(this.configOptions, answers);
    });
  }

  writing() {
    this.fs.copyTpl(
      this.templatePath("pomm.xml.tpl"),
      this.destinationPath(this.configOptions.appName + "/pom.xml"),
      this.configOptions
    );

    this.fs.copy(
      this.templatePath("src"),
      this.destinationPath(this.configOptions.appName + "/src")
    );
  }

  end() {
    this.log(
      `Application ${this.configOptions.appName} generated successfully`
    );
  }
};

We have added one more prompt of type list to select the appType.

Notice that we are initializing configOptions in the constructor and adding the user provided propmt answers into configOptions. Later we are simply passing the configOptions object which will contain all the placeholders.

Now, we can conditionally include either webmvc and webflux starter in pom.xml.tpl based on the user selection as follows:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.4.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.mycompany</groupId>
    <artifactId><%= appName %></artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name><%= appName %></name>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <%_ if (appType === 'webmvc') { _%>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <%_ } _%>
        <%_ if (appType === 'webflux') { _%>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>
        <%_ } _%>
    </dependencies>
</project>

Over the time the number of inputs we need from user may grow. Instead of adding prompt questions in the same index.js file we can create separate prompt.js file and add all prompts in that file.

Create generators/app/prompt.js as follows:

module.exports = {
  prompting
};

function prompting() {
  const done = this.async();
  const prompts = [
    {
      type: "string",
      name: "appName",
      message: "What is the application name?",
      default: "myservice"
    },
    {
      type: "list",
      name: "appType",
      message: "Do you want to use WebMVC or WebFlux?",
      choices: [
        {
          value: "webmvc",
          name: "WebMVC"
        },
        {
          value: "webflux",
          name: "WebFlux"
        }
      ],
      default: "webmvc"
    }
  ];

  this.prompt(prompts).then(answers => {
    Object.assign(this.configOptions, answers);
    done();
  });
}

Update generators/app/index.js as follows:

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

module.exports = class extends Generator {

    ...
    ...
    get prompting() {
        return prompts.prompting;
    }
}

Sometimes we might want to ask more questions based on previous prompt answer.
We can conditionally prompt user using when as follows:

const prompts = [
    ...
    ...
    {
        type: 'confirm',
        name: 'sql',
        message: 'Do you want to use Spring Data Jpa?',
        default: true
    },
    {
        when: response => response.sql === true,
        type: 'list',
        name: 'databaseType',
        message: 'Which type of database you want to use?',
        choices: [
            {
                value: 'postgresql',
                name: 'Postgresql'
            },
            {
                value: 'mysql',
                name: 'MySQL'
            },
            {
                value: 'mariadb',
                name: 'MariaDB'
            }
        ],
        default: 'postgresql'
    }
]

Composing with Sub-generator

We may want to add more and more features to our generator. Instead of adding all those features to a single generator we can create sub-generators and invoke them from main generator using this.composeWith(...).

Suppose we have main generator app and 3 other sub-generators microservice, config-server and service-registry.

+- generator-springboot/
   +- package.json
   +- generators/
      +- app/
         +- index.js
      +- microservice/
         +- index.js
      +- config-server/
         +- index.js
      +- service-registry/
         +- index.js

Now from main app generator we can invoke sub-generators as follows:

generator-springboot/generators/app/index.js

"use strict";
const Generator = require("yeoman-generator");

module.exports = class extends Generator {
  prompting() {
    const prompts = [
      {
        type: "list",
        name: "appType",
        message: "Which type of application you want to generate?",
        choices: [
          {
            value: "microservice",
            name: "SpringBoot MicroService"
          },
          {
            value: "config-server",
            name: "Spring Cloud Config Server"
          },
          {
            value: "service-registry",
            name:
              "Spring Cloud Eureka Server for Service Registry and Discovery"
          }
        ],
        default: "microservice"
      }
    ];
    return this.prompt(prompts).then(answers => {
      this.appType = answers.appType;
    });
  }

  default() {
    this.composeWith(require.resolve("../" + this.appType));
  }
};

Now when you run the main generator and select the appType, it will invoke the respective sub-generator.

Invoking sub-generator directly

We can create sub-generators to add more features to an existing yeoman generated application.
For example, once we create a SpringBoot application we can use a entity sub-generator to generate a JPA entity.

We can invoke sub-generator directly as follows:

myservice> yo springboot:entity Product

Using user configuration

We can save the user selected options so that we can use them later while running sub-generators.
For example, if user selected to use FlywayDB migration tool then while running Entity generator we can check which DB migration option is selected and generate DB migration scripts accordingly.

We can save the user configuration in main generator as follows:

generators/app/index.js

module.exports = class extends Generator {

    ...
    ...
    configuring() {
        Object.assign(this.configOptions, constants);
        this.config.save(this.configOptions);
    }
}

this.config.save() method will store the user configuration in .yo-rc.json file.

.yo-rc.json

{
  "generator-springboot": {
    "appName": "myservice",
    "packageName": "com.mycompany.myservice",
    "sql": true,
    "databaseType": "postgresql",
    "dbMigrationTool": "flywaydb",
    "features": [],
    "buildTool": "gradle",
    "packageFolder": "com/mycompany/myservice",
    "...": "...",
    "...": "..."
  }
}

We can also use this.config.set() to specify one key-value pair or an object of multiple keys/values.
Note that save() method is automatically called whenever we call this.config.set().

Now we can use this.config.getAll() to load the configuration from .yo-rc.json file.

generators/entity/index.js

module.exports = class extends Generator {
    ...
    ...
    writing() {
        const userConfig = this.config.getAll();
        if(userConfig.dbMigrationTool === "flywaydb") {
            //do something
        }
    }
}

We can also pass Arguments and Options to the generator. For example for entity sub-generator we want to pass mandatory entityName as an argument and optional table-name as an argument.

generators/entity/index.js

module.exports = class extends Generator {

    constructor(args, opts) {
        super(args, opts);
        this.configOptions = this.options.configOptions || {};

        this.argument("entityName", {
            type: String,
            required: true,
            description: "Entity name"
        });

        this.option('table-name', {
            type: String,
            desc: "Table name"
        })
    }

    writing() {
        const entityName = this.options.entityName;
        const tableName = this.options.tableName;
        ....
        ...
    }
}

Now we can invoke entity sub-generator from within the generated application directory as follows:

myservice> yo springboot:entity Person --table-name persons

Testing Yeoman generator

We can also unit test yeoman generators by using mocha, yeoman-test and yeoman-assert packages.

package.json

{
  "name": "generator-springboot",
  "version": "0.0.6",
  "description": "A Yeoman generator for generating SpringBoot microservices",
  ...
  ...
  "scripts": {
    "test": "npm run test:unit -- test/**/*.spec.js test/*.spec.js --no-insight",
    "test:unit": "mocha --timeout 30000 --slow 0 --reporter spec"
  },
  ...
  ...
  "devDependencies": {
    "fs-extra": "7.0.1",
    "mocha": "6.1.4",
    "sinon": "7.2.5",
    "yeoman-assert": "3.1.1",
    "yeoman-test": "1.9.1"
  }
}

We can write unit test to invoke a generator using yeoman-test as follows:

generator-springboot/test/microservice.spec.js

const path = require("path");
const assert = require("yeoman-assert");
const helpers = require("yeoman-test");

describe("SpringBoot Microservice Generator", () => {
  describe("Generate minimal microservice with Maven", () => {
    before(done => {
      helpers
        .run(path.join(__dirname, "../generators/microservice"))
        .withPrompts({
          appName: "mymicroservice",
          packageName: "com.mycompany.mymicroservice",
          packageFolder: "com/mycompany/mymicroservice",
          sql: false,
          buildTool: "maven"
        })
        .on("end", done);
    });

    it("creates expected default files for minimal microservice", () => {
      assert.file("pom.xml");
    });
  });
});

Of course here I am doing a simple sanity check of whether pom.xml is generated or not. We can test much more if we want to.

Now we can run tests using npm run test.

I think we have covered sufficient ground to start building a Yeoman generator.

For reference please checkout my github repository https://github.com/sivaprasadreddy/generator-springboot.

Testing REST APIs using Postman and Newman

K. Siva Prasad Reddy — Sat, 09 Nov 2019 04:42:58 +0000

Postman is the most popular tool for testing REST APIs.
I guess most of the developers are familiar with how to use Postman to send various types (GET, POST, PUT, DELETE, etc) of HTTP requests
with various types of payloads (form data, JSON etc).

In addition to triggering one API request and verifying the response, I frequently come across some common needs like

Call an API and assert response
Parameterize variables based on the environment
Trigger a series of API calls to simulate some user flow
Trigger one API request with different inputs and assert expected response
Load test by simulating load on the server by firing a series of requests repeatedly with a certain delay
Run Postman collection to do Smoke Test from Build Pipeline

As I am already using Postman to test my REST APIs, I thought of exploring if I can do all these tasks using Postman itself and it turns out I can.

So, I wanted to share a few Postman tips I learned.

I am using Postman to test my REST API implemented using SpringBoot and secured with Spring Security JWT based authentication.
You can find the source code of this article at https://github.com/sivaprasadreddy/todo-list/todo-api-spring-boot.

The Postman collection files are at https://github.com/sivaprasadreddy/todo-list/tree/master/config/postman

While searching for is there a way to run postman collection programmatically
I come across Newman
which is a command-line Collection Runner for Postman. Newman is built on NodeJS and we can install it globally to use it.

$ npm install -g newman
$ newman run mycollection.json

Or we can use Newman npm package as a library as mentioned here https://www.npmjs.com/package/newman#using-newman-as-a-library.

Ok, enough talk. Lets get to the business.

First, open Postman and create a new collection, say "todolist-api".

1. Call an API and assert response

We want to make a call to SpringBoot Actuator Health endpoint and verify the HTTP Status Code and assert status is UP.

Add a new request with URL http://localhost:8080/actuator/health with GET method.
In the Headers tab add Content-Type header with application/json value.

In Tests tab add the following code:

pm.test("Check Application Health", function () {
    pm.response.to.have.status(200);
    var jsonData = pm.response.json();
    pm.expect(jsonData.status).to.eql("UP");
});

Here we are using Postman API to retrieve the response and verify the HTTP status code to be 200.
Also, the expected JSON response from /actuator/health request is to have {"status": "UP"}.
So we are asserting whether the JSON response field status is equal to UP.

We can just hit Send button and see the Response body and you can also see in Test Results tab that test is passed.

We can also run all the Requests (I know we have only one right now) by clicking on the Play button next to Collection name and Run.
It will open up the collection runner window and show all the tests available to run.
We can Select/Deselect requests and click on Run button to run the tests.

Running Postman collection using Newman

In Postman click on 3 dots next to Collection name and export the Collection as a json file.
Let's say the collection json file name is todolist.postman_collection.json.

We can run the collection using Newman as follows:

$ newman run todolist.postman_collection.json

You can see various options you can pass to newman
at https://learning.getpostman.com/docs/postman/collection_runs/command_line_integration_with_newman/#options

2. Trigger a series of API calls to simulate some user flow

Next, my requirement is user should be able to create a new Todo, update the newly created Todo and finally delete that Todo.
Even before doing all these users should be authenticated.
As we are using JWT based authentication, upon successful login user will get an access_token and
for each subsequent request user should send access_token as a Header.

Also, we need to capture the ID of newly created Todo, which is Auto generated primary key in DB,
and use that ID for update todo and delete todo requests.

Now, add a new Request named login with URL http://localhost:8080/api/auth/login and POST method with following JSON Payload:

{
    "username": "admin@gmail.com",
    "password": "admin"
}

If you hit Send button you can see the response as follows:

{
    "access_token": "some long sequence of alphanumeric chars",
    "expires_in": 604800
}

We want to capture this access_token and pass it in the subsequent request.
In order to do this, we need to run the requests in an environment so that we can set some variables in one request and reference them in further requests.

In Postman on the top right corner there is Environment dropdown, click on the gear icon and add a new environment called todo-local-env.

Now add the following code snippet in Tests tab of login request:

pm.test("Authenticate user", function () {
    pm.response.to.have.status(200);
    var jsonData = JSON.parse(responseBody);
    pm.expect(jsonData.access_token).not.eq(undefined);
    postman.clearEnvironmentVariable("TodoApiAccessToken");
    postman.setEnvironmentVariable("TodoApiAccessToken", jsonData.access_token);
});

We are verifying whether the request is successful or not and setting the TodoApiAccessToken variable in the selected environment.

Now if you trigger the login request and see todo-local-env, you can find TodoApiAccessToken variable with the access_token value.

Now, create another request named create-todo with URL http://localhost:8080/api/todos and POST method with following JSON payload:

{
    "text": "Write a new blog post"
}

In Headers tab add the Header with key Authorization and value as Bearer {{TodoApiAccessToken}}.
Here we are referring to the environment variable value using {{variable_name}} syntax.

In Tests tab add the following snippet:

pm.test("Create New Todo", function () {
    pm.response.to.have.status(201);
    var jsonData = JSON.parse(responseBody);
    postman.clearEnvironmentVariable("todo_id");
    postman.setEnvironmentVariable("todo_id", jsonData.id);
});

Here we are capturing the new Todo's id value and setting environment variable todo_id.

Next, add the update-todo Request with URL http://localhost:8080/api/todos/{{todo_id}} and PUT method with following JSON payload:

{
    "text": "Write a new blog post - updated"
}

We can add following snippet in update-todo request Tests tab:

pm.test("Update Existing Todo", function () {
    pm.response.to.have.status(200);
});

Finally, we can add delete-todo-by-id request with URL http://localhost:8080/api/todos/{{todo_id}} and DELETE method.
add following snippet in delete-todo-by-id request Tests tab:

pm.test("Delete Todo by Id", function () {
    pm.response.to.have.status(200);
    postman.clearEnvironmentVariable("todo_id");
});

Now we can run the entire collection as mentioned earlier which will
run all the requests in the order they appear in collection.

IMPORTANT: We should select the environment, todo-local-env in our case, to get the environment variables sharing to work.

Running collection using Newman with environment

In order to run the collection using newman we need to export the collection and also our environment as well.

Click on Manage Environments gear icon on the top right corner and click on Download Environment icon for todo-local-env which will be downloaded as a json file.

Lets name it as todo-local-env.postman_environment.json.

$ newman run todolist.postman_collection.json -e todo-local-env.postman_environment.json

Organizing user flows

We have created multiple requests (login, create-todo, update-todo, delete-todo) and run the collection as a single flow.
But in our real applications, there will be many different users flows with different behavior.

We can create folders within our collection representing the logical user flow and place the appropriate requests in that folder.

Then, we can run the requests of a specific directory using newman as follows:

$ newman run todolist.postman_collection.json -e todo-local-env.postman_environment.json --folder todo-crud

3. Parameterize variables based on the environment

So far I am running my application locally and is accessible at http://localhost:8080/.
I could run my application in a docker container that is accessible at http://localhost:18080/.

Now if want to run my postman collection against the docker container instance I need to change base URL for all requests.
Instead of changing the URLs or any environment-specific parameters while switching between environments
we can configure those values in different environments and use those values in request configurations.

Now click on Manage Environments, select todo-local-env and add a variable base_url with value http://localhost:8080.

Now change all the URLs from http://localhost:8080/some-path to {{base_url}}/some-path.

Next create a new environment called todo-docker-env and add variable base_url with value http://localhost:18080.

Now we can simply select the desired environment and run the collection.

4. Trigger API request with different inputs and assert expected responses

We may also need to call an API endpoint with different inputs and verify responses such as perform login
with valid and invalid credentials and assert the expected responses.

We can use data files to pass different inputs so that we don't have to change the request configuration.
We can pass data using JSON or CSV files.

For example, we can pass credentials using CSV file as follows:

todo-credentials.csv

email,password,expected_http_code
admin@gmail.com,admin.200
dummy@gmail.com,secret,401

The first row is a header with variable names.
We can use the placeholders in URL path or in the body as follows:

{
    "username": "{{email}}",
    "password": "{{password}}"
}

In Tests tab we can refer data values using data.variableName as follows:

pm.test("Authenticate user", function () {
    pm.response.to.have.status(data.expected_http_status_code);
});

$ newman run todolist.postman_collection.json -e local.postman_environment.json --folder authentication --data todo-credentials.csv

5. Load testing

I was trying to do a simple load testing of my API and I know I can use Gatling to do it.
But I just want a simple and quick solution. Turns out Postman provides that feature as well.

$ newman run todolist.postman_collection.json -e local.postman_environment.json -n 100 --delay-request 500

The -n flag represents the number of iterations to run.
The --delay-request represents delay (in ms) between requests.

6. Run Postman collection to do Smoke Test from Build Pipeline

We can create a Postman collection to perform smoke test after deploying the application.
We can simply install newman npm package and run the collection in our build pipeline.

You can checkout

Conclusion

As we have seen Postman is a very powerful and awesome tool for developers working with REST APIs.

Testing SpringBoot Applications

K. Siva Prasad Reddy — Fri, 08 Nov 2019 00:26:19 +0000

SpringBoot is the most popular tech stack for building Java based REST APIs.
In this tutorial, we will learn how to write tests for SpringBoot applications.

Create SpringBoot Application
Unit Testing using JUnit 5 and Mockito
Integration Testing using TestContainers
Testing MicroService Integrations using MockServer

As we all know, we write unit tests for testing a single component (a class) behaviour
whereas we write integration tests for testing a feature which may involve interaction with multiple components.

Most of the times one component will depend on other components, so while implementing unit tests we should mock
the dependencies with the desired behaviour using frameworks like Mockito.

So, the question is how do we implement Unit Tests and Integration tests in SpringBoot application? Read on :-)

Sample application Code for this article can be found at https://github.com/sivaprasadreddy/spring-boot-tutorials/tree/master/testing/springboot-testing-demo

Create SpringBoot Application

Let us consider a scenario where we are building a REST API to manage users.
If we follow typical 3-tier layered architecture we might have JPA entity User, Spring Data JPA Repository UserRepository,
UserService and UserController implementing CRUD operations as follows:

First of all, create a SpringBoot application with the following dependencies:

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
    http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.sivalabs</groupId>
    <artifactId>springboot-testing-demo</artifactId>
    <packaging>jar</packaging>
    <version>1.0-SNAPSHOT</version>
    <name>springboot-testing-demo</name>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.8.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <java.version>1.8</java.version>
    </properties>

    <build>
        <plugins>                       
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
            <plugin>
                <artifactId>maven-failsafe-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <scope>runtime</scope>
        </dependency>
    </dependencies>
</project>

By default spring-boot-starter-test comes with JUnit 4 as the testing framework.
We can exclude JUnit4 and add JUnit 5 dependencies as follows:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
        <exclusions>
            <exclusion>
                <groupId>junit</groupId>
                <artifactId>junit</artifactId>
            </exclusion>
        </exclusions>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-params</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

Let us create JPA entity, repository, service and controller for User as follows:

User.java

package com.sivalabs.myservice.entities;

import lombok.*;
import javax.persistence.*;
import javax.validation.constraints.NotEmpty;
import java.io.Serializable;

@Entity
@Table(name = "users")
@Setter
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class User implements Serializable
{
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotEmpty(message = "Email should not be empty")
    @Column(nullable = false, unique = true, length = 100)
    private String email;

    @Column(nullable = false, length = 100)
    private String password;

    @Column(nullable = false, length = 100)
    private String name;

}

UserRepository.java

package com.sivalabs.myservice.repositories;

import org.springframework.data.jpa.repository.JpaRepository;
import com.sivalabs.myservice.entities.User;
import org.springframework.data.jpa.repository.Query;
import java.util.Optional;

public interface UserRepository extends JpaRepository<User, Long>
{
    @Query("select u from User u where u.email=?1 and u.password=?2")
    Optional<User> login(String email, String password);

    Optional<User> findByEmail(String email);
}

UserService.java

package com.sivalabs.myservice.services;

import com.sivalabs.myservice.exception.UserRegistrationException;
import com.sivalabs.myservice.repositories.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import com.sivalabs.myservice.entities.User;
import java.util.List;
import java.util.Optional;

@Service
@Transactional
public class UserService 
{
    private final UserRepository userRepository;

    @Autowired
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public Optional<User> login(String email, String password)
    {
        return userRepository.login(email, password);
    }

    public User createUser(User user)
    {
        Optional<User> userOptional = userRepository.findByEmail(user.getEmail());
        if(userOptional.isPresent()){
            throw new UserRegistrationException("User with email "+ user.getEmail()+" already exists");
        }
        return userRepository.save(user);
    }

    public User updateUser(User user)
    {
        return userRepository.save(user);
    }

    public List<User> findAllUsers() {
        return userRepository.findAll();
    }

    public Optional<User> findUserById(Long id) {
        return userRepository.findById(id);
    }

    public void deleteUserById(Long id) {
        userRepository.deleteById(id);
    }

}

UserController.java

package com.sivalabs.myservice.web.controllers;

import com.sivalabs.myservice.entities.User;
import com.sivalabs.myservice.services.UserService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@RequestMapping("/api/users")
@Slf4j
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAllUsers();
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.findUserById(id)
                .map(ResponseEntity::ok)
                .orElseGet(() -> ResponseEntity.notFound().build());
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public User createUser(@RequestBody @Validated User user) {
        return userService.createUser(user);
    }

    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User user) {
        return userService.findUserById(id)
                .map(userObj -> {
                    user.setId(id);
                    return ResponseEntity.ok(userService.updateUser(user));
                })
                .orElseGet(() -> ResponseEntity.notFound().build());

    }

    @DeleteMapping("/{id}")
    public ResponseEntity<User> deleteUser(@PathVariable Long id) {
        return userService.findUserById(id)
                .map(user -> {
                    userService.deleteUserById(id);
                    return ResponseEntity.ok(user);
                })
                .orElseGet(() -> ResponseEntity.notFound().build());
    }
}

Nothing too fancy here, typical CRUD operations in SpringBoot application.

ExceptionHandling using Zalando Problem Web

We are going to use Zalando Problem Web SpringBoot starter to handle
Exceptions so that it will automatically convert the application errors into JSON responses.

Just adding the following dependency is enough to start using Zalando Problem Web, and of course, you can customize it if you want to.

<problem-spring-web.version>0.25.0</problem-spring-web.version>
...
...
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-spring-web-starter</artifactId>
    <version>${problem-spring-web.version}</version>
    <type>pom</type>
</dependency>

Now let us see how we can write Unit Tests and Integration Tests for this functionality.

Unit Testing using JUnit 5 and Mockito

Let us start writing unit tests for UserService.
We should be able to write unit tests for UserService WITHOUT using any Spring features.

We are going to create a mock UserRepository using Mockito.mock() and create UserService instance using the mock UserRepository instance.

package com.sivalabs.myservice.services;

import com.sivalabs.myservice.entities.User;
import com.sivalabs.myservice.exception.UserRegistrationException;
import com.sivalabs.myservice.repositories.UserRepository;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import java.util.Optional;

import static org.assertj.core.api.Assertions.assertThat;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.*;

class UserServiceTest {

    private UserService userService;
    private UserRepository userRepository;

    @BeforeEach
    void setUp() {
        userRepository = mock(UserRepository.class);
        userService = new UserService(userRepository);
    }

    @Test
    void shouldSavedUserSuccessfully() {
        User user = new User(null, "siva@gmail.com","siva","Siva");
        given(userRepository.findByEmail(user.getEmail())).willReturn(Optional.empty());
        given(userRepository.save(user)).willAnswer(invocation -> invocation.getArgument(0));

        User savedUser = userService.createUser(user);

        assertThat(savedUser).isNotNull();

        verify(userRepository).save(any(User.class));
    }

    @Test
    void shouldThrowErrorWhenSaveUserWithExistingEmail() {
        User user = new User(1L, "siva@gmail.com","siva","Siva");
        given(userRepository.findByEmail(user.getEmail())).willReturn(Optional.of(user));

        assertThrows(UserRegistrationException.class, () -> {
            userService.createUser(user);
        });

        verify(userRepository, never()).save(any(User.class));
    }
}

I have created UserRepository mock object and UserService instance in @BeforeEach method so that every test has a clean setup.
Here we are not using any Spring or SpringBoot testing features such as @SpringBootTest because we don't have to for testing the behaviour of UserService.

I am not going to write tests for other methods because they are simply delegating the calls to UserRepository.

If you prefer to use annotations magic to create mock UserRepository and inject that mock into UserService,
you can use mockito-junit-jupiter as follows:

Add mockito-junit-jupiter dependency

<dependency>
    <groupId>org.mockito</groupId>
    <artifactId>mockito-junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>

Use @Mock and @InjectMocks to create and inject mock objects as follows:

import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;

@ExtendWith(MockitoExtension.class)
class UserServiceAnnotatedTest {

    @Mock
    private UserRepository userRepository;

    @InjectMocks
    private UserService userService;

    ...
    ...
}

Now, shall we write tests for UserRepository? hmmmm...

The UserRepository is an interface extending JpaRepository and there is hardly any logic we implemented and
we shouldn't be testing Spring Data JPA framework as I strongly believe Spring Data JPA team already tested it :-)

However, we added a couple of custom methods, one leveraging Query naming convention findByEmail() and another with custom JPQL query login().
We should test these methods. If there are any syntactic errors Spring Data JPA throw errors on startup but we should test the logical errors by ourselves.

We could implement tests for UserRepository using SpringBoot's @DataJpaTest annotation with In-memory database support.
But running tests against in-memory database might give a false impression that it will also work on real production database as well.
So, I prefer to run tests against the production database type, in our case Postgresql.

We can use TestContainers support to spin up a postgresql docker container and run the tests pointing to that database.
However, I consider this as an Integration Test rather than Unit Test as we are talking to a real database.
So, we will see how to write Integration tests for UserRepository later.

What about unit tests for Controller?

Yes, I want to write unit tests for controller and I want to check whether the REST endpoint is giving the proper
HTTP ResponseCode or not, returning the expected JSON or not etc.

SpringBoot provides @WebMvcTest annotation to test Spring MVC Controllers.
Also, @WebMvcTest based tests run faster as it will load only the specified controller and its dependencies only without loading the entire application.

While loading the Controller using @WebMvcTest SpringBoot won't automatically load Zalando Problem Web AutoConfiguration.
So, we need to configure ControllerAdvice as follows:

package com.sivalabs.myservice.common;

import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.zalando.problem.spring.web.advice.ProblemHandling;

@Profile("test")
@ControllerAdvice
public final class ExceptionHandling implements ProblemHandling {

}

Now we can write tests for UserController by injecting a Mock UserService bean and invoke API endpoints using MockMvc.

As SpringBoot is creating the UserController instance we are creating mock UserService bean using Spring's @MockBean as opposed to plain Mockito's @Mock.

package com.sivalabs.myservice.web.controllers;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.sivalabs.myservice.entities.User;
import com.sivalabs.myservice.services.UserService;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;
import org.zalando.problem.ProblemModule;
import org.zalando.problem.violations.ConstraintViolationProblemModule;

import java.util.ArrayList;
import java.util.List;
import java.util.Optional;

import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.doNothing;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(controllers = UserController.class)
@ActiveProfiles("test")
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Autowired
    private ObjectMapper objectMapper;

    private List<User> userList;

    @BeforeEach
    void setUp() {
        this.userList = new ArrayList<>();
        this.userList.add(new User(1L, "user1@gmail.com", "pwd1","User1"));
        this.userList.add(new User(2L, "user2@gmail.com", "pwd2","User2"));
        this.userList.add(new User(3L, "user3@gmail.com", "pwd3","User3"));

        objectMapper.registerModule(new ProblemModule());
        objectMapper.registerModule(new ConstraintViolationProblemModule());
    }

    @Test
    void shouldFetchAllUsers() throws Exception {
        given(userService.findAllUsers()).willReturn(this.userList);

        this.mockMvc.perform(get("/api/users"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.size()", is(userList.size())));
    }

    @Test
    void shouldFindUserById() throws Exception {
        Long userId = 1L;
        User user = new User(userId, "newuser1@gmail.com", "pwd", "Name");
        given(userService.findUserById(userId)).willReturn(Optional.of(user));

        this.mockMvc.perform(get("/api/users/{id}", userId))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())))
        ;
    }

    @Test
    void shouldReturn404WhenFetchingNonExistingUser() throws Exception {
        Long userId = 1L;
        given(userService.findUserById(userId)).willReturn(Optional.empty());

        this.mockMvc.perform(get("/api/users/{id}", userId))
                .andExpect(status().isNotFound());

    }

    @Test
    void shouldCreateNewUser() throws Exception {
        given(userService.createUser(any(User.class))).willAnswer((invocation) -> invocation.getArgument(0));

        User user = new User(null, "newuser1@gmail.com", "pwd", "Name");
        this.mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())))
                ;

    }

    @Test
    void shouldReturn400WhenCreateNewUserWithoutEmail() throws Exception {
        User user = new User(null, null, "pwd", "Name");

        this.mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isBadRequest())
                .andExpect(header().string("Content-Type", is("application/problem+json")))
                .andExpect(jsonPath("$.type", is("https://zalando.github.io/problem/constraint-violation")))
                .andExpect(jsonPath("$.title", is("Constraint Violation")))
                .andExpect(jsonPath("$.status", is(400)))
                .andExpect(jsonPath("$.violations", hasSize(1)))
                .andExpect(jsonPath("$.violations[0].field", is("email")))
                .andExpect(jsonPath("$.violations[0].message", is("Email should not be empty")))
                .andReturn()
        ;
    }

    @Test
    void shouldUpdateUser() throws Exception {
        Long userId = 1L;
        User user = new User(userId, "user1@gmail.com", "pwd", "Name");
        given(userService.findUserById(userId)).willReturn(Optional.of(user));
        given(userService.updateUser(any(User.class))).willAnswer((invocation) -> invocation.getArgument(0));

        this.mockMvc.perform(put("/api/users/{id}", user.getId())
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())));

    }

    @Test
    void shouldReturn404WhenUpdatingNonExistingUser() throws Exception {
        Long userId = 1L;
        given(userService.findUserById(userId)).willReturn(Optional.empty());
        User user = new User(userId, "user1@gmail.com", "pwd", "Name");

        this.mockMvc.perform(put("/api/users/{id}", userId)
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isNotFound());

    }

    @Test
    void shouldDeleteUser() throws Exception {
        Long userId = 1L;
        User user = new User(userId, "user1@gmail.com", "pwd", "Name");
        given(userService.findUserById(userId)).willReturn(Optional.of(user));
        doNothing().when(userService).deleteUserById(user.getId());

        this.mockMvc.perform(delete("/api/users/{id}", user.getId()))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())));

    }

    @Test
    void shouldReturn404WhenDeletingNonExistingUser() throws Exception {
        Long userId = 1L;
        given(userService.findUserById(userId)).willReturn(Optional.empty());

        this.mockMvc.perform(delete("/api/users/{id}", userId))
                .andExpect(status().isNotFound());

    }

}

Now we have a good amount of unit tests testing various components of our application.
But still, there is a lot of chance for things to go wrong, maybe we might have some property configuration issues,
we might have some errors in our DB migration scripts etc.

So, let's write Integration Tests to have more confidence that our application is running properly.

Integration Testing using TestContainer

SpringBoot provides excellent support for integration testing. We can use @SpringBootTest annotation to load the application context and test various components.

Let us start with writing integration tests for UserController.
As I mentioned earlier we want to test using Postgres database instead of an in-memory database.

Add the following dependencies.

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <version>1.11.3</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>1.11.3</version>
    <scope>test</scope>
</dependency>

We can use TestContainers support for JUnit 5 as mentioned here https://www.testcontainers.org/test_framework_integration/junit_5/.
However, starting and stopping docker containers for every test or every test class might cause tests running slowly.
So, we are going to use Singleton Containers approach mentioned at https://www.testcontainers.org/test_framework_integration/manual_lifecycle_control/#singleton-containers

Let us create a base class AbstractIntegrationTest so that all our integration tests can extend without repeating the common configuration.

package com.sivalabs.myservice.common;

import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.util.TestPropertyValues;
import org.springframework.context.ApplicationContextInitializer;
import org.springframework.context.ConfigurableApplicationContext;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.testcontainers.containers.PostgreSQLContainer;

import static org.springframework.boot.test.context.SpringBootTest.WebEnvironment.RANDOM_PORT;

@Slf4j
@ActiveProfiles("test")
@SpringBootTest(webEnvironment = RANDOM_PORT)
@AutoConfigureMockMvc
@ContextConfiguration(initializers = {AbstractIntegrationTest.Initializer.class})
public abstract class AbstractIntegrationTest {

    @Autowired
    protected MockMvc mockMvc;

    @Autowired
    protected ObjectMapper objectMapper;

    private static PostgreSQLContainer sqlContainer;

    static {
        sqlContainer = new PostgreSQLContainer("postgres:10.7")
                .withDatabaseName("integration-tests-db")
                .withUsername("sa")
                .withPassword("sa");
        sqlContainer.start();
    }

    public static class Initializer
            implements ApplicationContextInitializer<ConfigurableApplicationContext> {
        public void initialize(ConfigurableApplicationContext configurableApplicationContext) {
            TestPropertyValues.of(
                    "spring.datasource.url=" + sqlContainer.getJdbcUrl(),
                    "spring.datasource.username=" + sqlContainer.getUsername(),
                    "spring.datasource.password=" + sqlContainer.getPassword()
            ).applyTo(configurableApplicationContext.getEnvironment());
        }
    }

}

We have used @AutoConfigureMockMvc to auto-configure MockMvc,
and @SpringBootTest(webEnvironment = RANDOM_PORT) to start the server on a random available port.

We have started PostgreSQLContainer and used @ContextConfiguration(initializers={AbstractIntegrationTest.Initializer.class})
to configure the dynamic database connection properties.

Now we can implement Integration Test for UserController as follows:

package com.sivalabs.myservice.web.controllers;

import com.sivalabs.myservice.common.AbstractIntegrationTest;
import com.sivalabs.myservice.entities.User;
import com.sivalabs.myservice.repositories.UserRepository;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;

import java.util.ArrayList;
import java.util.List;

import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.hasSize;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

class UserControllerIT extends AbstractIntegrationTest {

    @Autowired
    private UserRepository userRepository;

    private List<User> userList = null;

    @BeforeEach
    void setUp() {
        userRepository.deleteAll();

        userList = new ArrayList<>();
        this.userList.add(new User(1L, "user1@gmail.com", "pwd1","User1"));
        this.userList.add(new User(2L, "user2@gmail.com", "pwd2","User2"));
        this.userList.add(new User(3L, "user3@gmail.com", "pwd3","User3"));

        userList = userRepository.saveAll(userList);
    }

    @Test
    void shouldFetchAllUsers() throws Exception {
        this.mockMvc.perform(get("/api/users"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.size()", is(userList.size())));
    }

    @Test
    void shouldFindUserById() throws Exception {
        User user = userList.get(0);
        Long userId = user.getId();

        this.mockMvc.perform(get("/api/users/{id}", userId))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())))
        ;
    }

    @Test
    void shouldCreateNewUser() throws Exception {
        User user = new User(null, "user@gmail.com", "pwd", "name");
        this.mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())));

    }

    @Test
    void shouldReturn400WhenCreateNewUserWithoutEmail() throws Exception {
        User user = new User(null, null, "pwd", "Name");

        this.mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isBadRequest())
                .andExpect(header().string("Content-Type", is("application/problem+json")))
                .andExpect(jsonPath("$.type", is("https://zalando.github.io/problem/constraint-violation")))
                .andExpect(jsonPath("$.title", is("Constraint Violation")))
                .andExpect(jsonPath("$.status", is(400)))
                .andExpect(jsonPath("$.violations", hasSize(1)))
                .andExpect(jsonPath("$.violations[0].field", is("email")))
                .andExpect(jsonPath("$.violations[0].message", is("Email should not be empty")))
                .andReturn()
        ;
    }

    @Test
    void shouldUpdateUser() throws Exception {
        User user = userList.get(0);
        user.setPassword("newpwd");
        user.setName("NewName");

        this.mockMvc.perform(put("/api/users/{id}", user.getId())
                .contentType(MediaType.APPLICATION_JSON_UTF8)
                .content(objectMapper.writeValueAsString(user)))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())));

    }

    @Test
    void shouldDeleteUser() throws Exception {
        User user = userList.get(0);

        this.mockMvc.perform(
                delete("/api/users/{id}", user.getId()))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.email", is(user.getEmail())))
                .andExpect(jsonPath("$.password", is(user.getPassword())))
                .andExpect(jsonPath("$.name", is(user.getName())));

    }

}

The UserControllerIT tests look very similar to UserControllerTest with the difference being how we load the ApplicationContext.
While using @SpringBootTest SpringBoot will actually start the application by loading the entire application
so that tests will fail if there is any misconfiguration.

Next, we are going to write a test for UserRepository using @DataJpaTest.
But we want to run tests against a real database, not with an in-memory database.
We can use @AutoConfigureTestDatabase(replace=AutoConfigureTestDatabase.Replace.NONE) to turn-off using in-memory database and use the configured database.

Let us create PostgreSQLContainerInitializer so that any repository tests can use this to configure dynamic Postgres database properties.

package com.sivalabs.myservice.common;

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.test.util.TestPropertyValues;
import org.springframework.context.ApplicationContextInitializer;
import org.springframework.context.ConfigurableApplicationContext;
import org.testcontainers.containers.PostgreSQLContainer;

@Slf4j
public class PostgreSQLContainerInitializer
        implements ApplicationContextInitializer<ConfigurableApplicationContext> {

    private static PostgreSQLContainer sqlContainer;

    static {
        sqlContainer = new PostgreSQLContainer("postgres:10.7")
                .withDatabaseName("integration-tests-db")
                .withUsername("sa")
                .withPassword("sa");
        sqlContainer.start();
    }

    public void initialize (ConfigurableApplicationContext configurableApplicationContext){
        TestPropertyValues.of(
                "spring.datasource.url=" + sqlContainer.getJdbcUrl(),
                "spring.datasource.username=" + sqlContainer.getUsername(),
                "spring.datasource.password=" + sqlContainer.getPassword()
        ).applyTo(configurableApplicationContext.getEnvironment());
    }

}

Now we can create UserRepositoryTest as follows:

package com.sivalabs.myservice.repositories;

import com.sivalabs.myservice.common.PostgreSQLContainerInitializer;
import com.sivalabs.myservice.entities.User;
import lombok.extern.slf4j.Slf4j;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.test.context.ContextConfiguration;
import javax.persistence.EntityManager;
import java.util.Optional;
import static org.assertj.core.api.Assertions.assertThat;

@Slf4j
@DataJpaTest
@AutoConfigureTestDatabase(replace= AutoConfigureTestDatabase.Replace.NONE)
@ContextConfiguration(initializers = {PostgreSQLContainerInitializer.class})
class UserRepositoryTest {

    @Autowired
    EntityManager entityManager;

    @Autowired
    private UserRepository userRepository;

    @Test
    void shouldReturnUserGivenValidCredentials() {
        User user = new User(null, "test@gmail.com", "test", "Test");
        entityManager.persist(user);

        Optional<User> userOptional = userRepository.login("test@gmail.com", "test");

        assertThat(userOptional).isNotEmpty();
    }
}

Well, I guess we learned something about how to write unit tests and integration tests using various SpringBoot features.

We are living in a Microservices world and there is a high chance that our service might talk to other microservices.
How are we going to test those integration points? How are we going to verify the timeout scenarios?
Well, we can certainly use a Mock object and pray GOD that it will work fine in production :-)
Or we can use libraries like MockServer to simulate the service-to-service communication.

Testing MicroService Integrations using MockServer

Assume from our application we want to fetch GitHub profile of a user. We can use GitHub REST API to fetch the user profile.
Also, we want to timeout the call after 2 seconds and if we don't get a response by that time we want to return a default user response.

We can implement this using Hystrix as follows:

application.properties

githuub.api.base-url=https://api.github.com

package com.sivalabs.myservice.config;

import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
@Data
public class ApplicationProperties {

    @Value("${githuub.api.base-url}")
    private String githubBaseUrl;
}

package com.sivalabs.myservice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.circuitbreaker.EnableCircuitBreaker;
import org.springframework.context.annotation.Bean;
import org.springframework.web.client.RestTemplate;

@SpringBootApplication
@EnableCircuitBreaker
public class Application
{
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

Create GithubUser class which holds response from GitHub API.

package com.sivalabs.myservice.model;

import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Data;

@Data
public class GithubUser {
    private Long id;
    private String login;
    private String url;
    private String name;
    @JsonProperty("public_repos")
    private int publicRepos;
    private int followers;
    private int following;
}

Create GithubService which talks to GitHub REST API using RestTemplate as follows:

package com.sivalabs.myservice.services;

import com.netflix.hystrix.contrib.javanica.annotation.HystrixCommand;
import com.netflix.hystrix.contrib.javanica.annotation.HystrixProperty;
import com.sivalabs.myservice.config.ApplicationProperties;
import com.sivalabs.myservice.model.GithubUser;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;

@Service
@Slf4j
public class GithubService {
    private final ApplicationProperties properties;
    private final RestTemplate restTemplate;

    @Autowired
    public GithubService(ApplicationProperties properties, RestTemplate restTemplate) {
        this.properties = properties;
        this.restTemplate = restTemplate;
    }

    @HystrixCommand(fallbackMethod = "getDefaultUser", commandProperties = {
            @HystrixProperty(name = "execution.isolation.thread.timeoutInMilliseconds", value = "2000")
    })
    public GithubUser getGithubUserProfile(String username) {
        log.info("GithubBaseUrl:"+properties.getGithubBaseUrl());
        return this.restTemplate.getForObject(properties.getGithubBaseUrl() + "/users/" + username, GithubUser.class);
    }

    GithubUser getDefaultUser(String username) {
        log.info("---------getDefaultUser-----------");
        GithubUser user = new GithubUser();
        user.setId(-1L);
        user.setLogin("guest");
        user.setName("Guest");
        user.setPublicRepos(0);
        return user;
    }
}

Let us create a GithubController with an endpoint to return the users GitHub profile.

package com.sivalabs.myservice.web.controllers;

import com.sivalabs.myservice.model.GithubUser;
import com.sivalabs.myservice.services.GithubService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/github")
public class GithubController {

    private final GithubService githubService;

    @Autowired
    public GithubController(GithubService githubService) {
        this.githubService = githubService;
    }

    @GetMapping("/users/{username}")
    public GithubUser getGithubUserProfile(@PathVariable String username) {
        return githubService.getGithubUserProfile(username);
    }
}

We can use MockServer to simulate the dependent microservice responses so that we can verify our application behaviour in various scenarios.

We can use TestContainers support to spin up MockServer docker container as follows:

Add the following dependencies:

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>mockserver</artifactId>
    <version>1.11.3</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-netty</artifactId>
    <version>5.5.1</version>
    <scope>test</scope>
</dependency>

In AbstractIntegrationTest add MockServerContainer configuration as follows:

import org.mockserver.client.MockServerClient;
import org.testcontainers.containers.MockServerContainer;

@Slf4j
@ActiveProfiles("test")
@SpringBootTest(webEnvironment = RANDOM_PORT)
@AutoConfigureMockMvc
@ContextConfiguration(initializers = {AbstractIntegrationTest.Initializer.class})
public abstract class AbstractIntegrationTest {
    ...
    ...
    private static MockServerContainer mockServerContainer;

    static {
        ....
        ....
        mockServerContainer = new MockServerContainer();
        mockServerContainer.start();
    }

    protected MockServerClient mockServerClient = new MockServerClient(
            mockServerContainer.getContainerIpAddress(),
            mockServerContainer.getServerPort());


    public static class Initializer
            implements ApplicationContextInitializer<ConfigurableApplicationContext> {
        public void initialize(ConfigurableApplicationContext configurableApplicationContext) {
            TestPropertyValues.of(
                    "spring.datasource.url=" + sqlContainer.getJdbcUrl(),
                    "spring.datasource.username=" + sqlContainer.getUsername(),
                    "spring.datasource.password=" + sqlContainer.getPassword(),
                    "githuub.api.base-url=" + mockServerContainer.getEndpoint()
            ).applyTo(configurableApplicationContext.getEnvironment());
        }
    }

}

Note that we are stating MockServerContainer and injecting the endpoint URL with "githuub.api.base-url="+mockServerContainer.getEndpoint().
Also, we have created MockServerClient which we are going to use for setting up expected responses.

package com.sivalabs.myservice.web.controllers;

import com.sivalabs.myservice.common.AbstractIntegrationTest;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.mockserver.model.Header;
import org.mockserver.verify.VerificationTimes;

import java.util.concurrent.TimeUnit;

import static org.hamcrest.CoreMatchers.is;
import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;
import static org.mockserver.model.JsonBody.json;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class GithubControllerIT extends AbstractIntegrationTest {

    @BeforeEach
    void setup() {
        mockServerClient.reset();
    }

    @Test
    void shouldGetGithubUserProfile() throws Exception {
        String username = "sivaprasadreddy";
        mockGetUserFromGithub(username);
        this.mockMvc.perform(get("/api/github/users/{username}", username))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.login", is(username)))
                .andExpect(jsonPath("$.name", is("K. Siva Prasad Reddy")))
                .andExpect(jsonPath("$.public_repos", is(50)))
                ;
        verifyMockServerRequest("GET", "/users/.*", 1);
    }

    private void mockGetUserFromGithub(String username) {
        mockServerClient.when(
            request().withMethod("GET").withPath("/users/.*"))
            .respond(
                response()
                    .withStatusCode(200)
                    .withHeaders(new Header("Content-Type", "application/json; charset=utf-8"))
                    .withBody(json("{ " +
                            "\"login\": \""+username+"\", " +
                            "\"name\": \"K. Siva Prasad Reddy\", " +
                            "\"public_repos\": 50 " +
                            "}"))
            );
    }

    private void verifyMockServerRequest(String method, String path, int times) {
        mockServerClient.verify(
                request()
                        .withMethod(method)
                        .withPath(path),
                VerificationTimes.exactly(times)
        );
    }
}

Note that we are setting up expected JSON response for <githuub.api.base-url>/users/.* URL pattern on mockServerClient.
So, when we make a call to http://localhost:8080/api/github/users/{username} GithubController will in-turn call GithubService which makes a call to
<githuub.api.base-url>/users/{username} and return the mock JSON response that we set using mockServerClient.

We can also simulate the failures and timeout scenarios as follows:

@Test
void shouldGetDefaultUserProfileWhenFetchingFromGithubFails() throws Exception {
    mockGetUserFromGithubFailure();
    this.mockMvc.perform(get("/api/github/users/{username}", "dummy"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.login", is("guest")))
            .andExpect(jsonPath("$.name", is("Guest")))
            .andExpect(jsonPath("$.public_repos", is(0)))
    ;
    verifyMockServerRequest("GET", "/users/.*", 1);
}

@Test
void shouldGetDefaultUserProfileWhenFetchingFromGithubTimeout() throws Exception {
    mockGetUserFromGithubDelayResponse();
    this.mockMvc.perform(get("/api/github/users/{username}", "dummy"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.login", is("guest")))
            .andExpect(jsonPath("$.name", is("Guest")))
            .andExpect(jsonPath("$.public_repos", is(0)))
    ;
    verifyMockServerRequest("GET", "/users/.*", 1);
}

private void mockGetUserFromGithubDelayResponse() {
    mockServerClient.when(
        request().withMethod("GET").withPath("/users/.*"))
        .respond(response().withStatusCode(200).withDelay(TimeUnit.SECONDS, 10));
}

private void mockGetUserFromGithubFailure() {
    mockServerClient.when(
        request().withMethod("GET").withPath("/users/.*"))
        .respond(response().withStatusCode(404));
}

In shouldGetDefaultUserProfileWhenFetchingFromGithubFails() test we are setting up the mockServer to respond
with 404 error to verify Hystrix fallback method is working or not.

Similarly, In shouldGetDefaultUserProfileWhenFetchingFromGithubTimeout() test we are setting up the mockServer to respond
with delay of 10 SECONDS to verify whether Hystrix timeout is working or not.

Make sure to reset mockServerClient using mockServerClient.reset() for every test in @BeforeEach method to reset any expectations set in previous test run.

Sample application Code for this article can be found at https://github.com/sivaprasadreddy/spring-boot-tutorials/tree/master/testing/springboot-testing-demo

I hope we have covered many common testing scenarios in SpringBoot applications.