DEV Community: Roshan Adhikari

Spring Boot Integration Testing with MockMvc

Roshan Adhikari — Sat, 22 Oct 2022 14:29:34 +0000

In this piece, we will build a REST-ful API using Spring Boot and Spring MVC, then perform integration testing by making requests to our endpoints and verifying the responses. For this project, we will need JUnit, MockMvc, H2, and a few other dependencies. Let's get started!

Dependencies

First, go to the Spring Initializr and generate a Spring Web application using the following dependencies:

Spring Web
Spring Data JPA
H2 Database
Lombok

We will create a REST-ful API, expose some endpoints, and test those endpoints using MockMvc.For persistence support, we will use the H2 in-memory database, and for interacting with the database, we will use the repositories provided by Spring Data JPA. I will be using Lombok for reducing the amount of boilerplate code I would be writing otherwise.

Controllers

For the purposes of brevity, we will be exposing just the following endpoints and HTTP actions:

GET /batteries - Returns a list of all Battery resources in database
GET /batteries/:id - Returns the Battery resource identified by id path variable
POST /batteries - Persists a Battery resource in database and returns the persisted resource

Resource

As you can see from the Controllers section, we will be working on a Battery resource for our API. The Battery resource will have the following fields:

Also, using the JPA annotations @Entity, @Table, @Column, etc., we map the POJO to our database entity of name batteries.

Repository

One of the most useful features of the Spring Data JPA project is the Repository pattern that comes with its implementations out-of-the-box. This way, we can quickly bootstrap a CRUD functionality without having to writing queries by ourselves.
Let us define the repository for our Battery entity by extending the JpaRepository interface.

Having defined this repository, we can now access a bunch of predefined methods that implement CRUD functionality (e.g., save, saveAll, deleteById, delete, etc.)

Bootstrap the database

To test our application, we will need some preloaded records. Let us create a Bootstrap configuration class that loads records into our database every time the application starts.

When a class is annotated with @Configuration, it means that the Spring IOC container can expect some bean definition inside the class. And so we give a bean definition using the @Bean annotation on the initDb method that returns an object of type CommandLineRunner.

CommandLineRunner is a functional interface with a method named run. When the Spring context is loaded, Spring Boot invokes the run method of all beans of type CommandLineRunner.

Application properties

For our application to work, we need to pass some application properties, including those for the database URL, username, password, and driver class name. Additionally, you can pass properties to enable the H2 console through which you can access the database using a GUI.

Testing our API

The spring-boot-starter-test starter module included in our pom.xml file includes JUnit, AssertJ, Hamcrest, etc. All of these libraries help us write effective test cases for our projects.
For this particular project, start with the main test class:

The @SpringBootTest annotation is used on tests classes for Spring Boot, and it loads the complete Spring application context.
Using @AutoConfigureMockMvc, we can enable auto-configuration of the Spring MVC test framework. MockMvc does request handling but uses mock request and response objects. No actual server is started.

Testing GET /batteries/:id

As you can see, we have imported some static methods from MockMvcRequestBuilders, MockMvcResultHandlers, and MockMvcResultMatchers. These static methods are then used for making HTTP requests (get, post, etc.), reading JSON responses (jsonPath), and printing the responses (print).
With the above test case, we verify that the response for GET /batteries/1 HTTP action contains the same id, name, postcode, and capacity values as in our database (the one we preloaded).

Testing GET /batteries

Similar to the previous test, we make a GET request to our endpoint and then print the response. Then we continue our tests through andExpect. First, we verify that the response status is 200 OK. Then, we verify that the response is a list of JSON objects. Finally, we verify that the size of list is equal to the size of records that exist in the database.

Testing POST /batteries

To send a request body along with our POST request, we use the autowired ObjectMapper instance to map the Battery object onto a String. The string object is then passed as the content of our POST request, and we specify the type of request body as JSON using contentType method.
Then, we use andExpect to verify our expectations with the JSON response. The response status should should be 201 CREATED. And since our API returns the very object that was persisted, the name, postcode, and capacity parameters should match.

Conclusion

We have successfully created and tested our REST-ful API using MockMvc and several other utility testing libraries. The full project code has been pushed to GitHub, feel free to check it out.

Build a Markdown-based Blog with Spring Boot - Part 6

Roshan Adhikari — Fri, 02 Jul 2021 08:04:31 +0000

This will be the final part of this series. For previous parts, please check: Part 1 | Part 2 | Part 3 | Part 4 | Part 5

Recap

By now, we have a complete blogging system set up. We add Markdown files to the resources/posts directory and our ContextEventListener class, upon a ContextRefreshedEvent, populates the database with the content from new Markdown files. Then, on the client side, when we request for a specific blog post by its ID, the PostController.getPostById method adds the respective post as a model attribute and returns the appropriate view to render.

What now?

We need to host our database in RemoteMySQL, push our repository to GitHub,and then deploy the repository to Heroku. But before that, let's add some new files to our repository.

Specify the Java Runtime

We need to specify the Java Runtime version to be used for our application. In the root directory of our project, create a new file system.properties and specify the Runtime version as 11.

Create a Heroku profile

We used the application.properties file for our development environment; but for deployment to Heroku, we will need a new set of properties. Create a application-heroku.properties file inside the resources directory.

We specify the datasource URL, username, and password as environment variables from within our Heroku environment. We also set the automatic database initialization provided by Hibernate to update; so, Hibernate checks for the tables and if a table doesn't exist, then it creates new tables.

So basically, we will provide four configuration variables (or Config Vars) to our Heroku deployment.

DATASOURCE_URL

DATASOURCE_USERNAME

DATASOURCE_PASSWORD

spring_profiles_active

If we set the variable spring_profiles_active to Heroku, Spring Boot automatically loads the appropriate properties file (i.e., application-heroku.properties).

RemoteMySQL

Now onto our production database, register for an account in RemoteMySQL. After you are a registered user, you can create a new database; after which RemoteMySQL provides you with details about your credentials, including the username, database name, password, port, host, etc. Keep these secure as we need to pass these as Config Vars to our Heroku deployment.

In the DATABASES section, go to the Action tab of your database (the one you created just now), and click on phpMyAdmin. RemoteMySQL provided a GUI for interacting with our relations.

In the phpMyAdmin page, login with username and password that you received just now.

GitHub

Before proceeding any further, make sure you've committed your changes and pushed them to the remote repository.

Heroku

If you're new to Heroku, first register for an account. Then, from the dashboard, create a new application with New > Create new app.

Now we can specify our deployment method. In the following page, select GitHub as the deployment method and select the repository and connect it to Heroku. Then just below, select the branch to trigger automatic deployment and click the Enable Automatic Deploys button. For me, it is the main branch.

This means that whenever I push something (for instance a new Markdown file inside resources/posts directory), Heroku reflects those changes in the deployed application. We do not need to redeploy the application.

Following this, go to the Settings tab and click the Reveal Config Vars button. Now we can add all the required configuration variables we discussed above.

Set the DATASOURCE_URL variable as jdbc:mysql://remotemysql.com:3306/your-database-name

Set the DATASOURCE_USERNAME variable as the username you received from RemoteMySQL.

Set the DATASOURCE_PASSWORD variable as the password you received from RemoteMySQL.

Set spring_profiles_active variable as heroku

Finally, go back to the Deploy and click on the Deploy Branch button to manually deploy the application for the first time.

Live deployment

If the build process didn't end up in an error, you should be able to open the application and see your blog posts live.

Adding new blog posts

Too see if the deployment mechanism works, let us create a new Markdown file, 6_After_Deployment_Blog.md, inside the resources/posts directory in our local repository.

Now, commit the change and push it to the remote repository's main branch. Note that I am pushing to my main branch because that's the branch I set to trigger automatic deploys in Heroku. If you had set another branch, then you should push your changes to that branch.

After you've pushed your changes, you should see a "Build started by ..." message in the logs of your Heroku application. This means that our application's automatic deployment feature is working as intended.

To check the logs of your application, go to dashboard.heroku.com/apps/<your-app-name>/logs

After the build completes, open your deployment to see if the new post is available. In my case, it is.

Wrapping up

This concludes the series. We have built a blog application that reads Markdown files and populates the database with its content. Whenever we push a new Markdown file to our GitHub repository, Heroku automatically deploys the changes in our application.

Note that there are several limitations with the free database we use from RemoteMySQL. Read them here.

All of the code associated with the project have been published in the GitHub repository.

The blog is deployed here, if you want to take a look.

Build a Markdown-based Blog with Spring Boot - Part 5

Roshan Adhikari — Thu, 01 Jul 2021 06:36:54 +0000

Welcome to another instalment of the "Build a Markdown Blog with Spring Boot" series. You can find the previous parts right here: Part 1 | Part 2 | Part 3 | Part 4

Recap

Right before this part, we have finished building how the blog works -- we use Markdown files stored in resources/posts directory to populate our database and then fetch the posts on respective requests using our PostController class.

Now, we need to render the posts. For this, we use Thymeleaf and Bootstrap. We already have a Thymeleaf dependency specified in our POM.

Bootstrap WebJar

For Bootstrap, we just need to add its WebJar in the pom.xml file.

Again, load the Maven changes in your POM file. Now we're ready to use Bootstrap in our Thymeleaf templates.

Header for our templates

Inside the resources/templates directory, create a new template: header.html. This will be the header portion of our blog that will be present in every page.

Notice how we specify both href and th:href attributes when linking Bootstrap. This is the reason why Thymeleaf is a natural template engine: Templates written in Thymeleaf can be rendered with or without the server running. When we run the server, Thymeleaf reads the th:href attribute and links Bootstrap using the WebJar resource. When the server isn't running, the browser uses the href attribute to link Bootstrap.

Creating a home page

Next, create a template, posts.html, that will serve as our home page.

Here, for each post retrieved from the database, a card element is created. We also use the #temporals utility provided by Thymeleaf to format our LocalDateTime instance so that we can render the month name, day, and year in the format: July 1, 2021.

You can additionally use a pagination element from Bootstrap to fetch paginated posts. (In this article, we will do it the manual way -- using request queries to specify the size and page.)

The one where we render a post

Now onto our post.html template. This will be the page that renders a single blog post in full.

In this template, we employ some error-handling mechanism. Go back to the PostController.getPostById method. Notice how if a post by a given ID doesn't exist, we add an error attribute with no-post value in the model.

In post.html if the model contains the error attribute, we change the title as well as the body to indicate an error. Otherwise, we render the respective blog post.

This is it for the coding portion of this series. To test if the pagination works, add some more Markdown files in the resources/posts directory, and fetch them from the website.

Running the application

Run the Spring Boot application and wait until the JVM starts running.

Visit localhost:8080 to see your most recent blog posts.

To modify the pagination parameters, we can use query strings in our request. For instance, localhost:8080/posts?page=0&size=3 should render the three most recent blog posts.

To render a blog post in full, we can use the ID of that post, or simply click the Read more hyperlink.

Code

We have successfully built the blog application that we set out to build. In the following article, we will see how we can deploy our application to Heroku, host our database on RemoteMySQL, and use Heroku's Automatic Deployment feature to update our blog whenever we add a new blog post.

This session's code has been pushed to the GitHub repository; for previous sessions, check here.

Build a Markdown-based Blog with Spring Boot - Part 4

Roshan Adhikari — Thu, 27 May 2021 09:51:41 +0000

Before continuing with part 4 of this series, make sure you have checked out the previous three parts as well: Part 1 | Part 2 | Part 3

Up to this point, we have a database ready, and we have established conventions for how and where we store our Markdown files. These Markdown files will be parsed, line by line, and rendered as HTML string before we persist it in the database. For parsing and rendering, we have already defined some utility classes -- MdFileReader and MdToHtmlRenderer.

For this session, we will write a class that implements the ApplicationListener interface such that on every firing of the ContextRefreshedEvent, our event-listener class' onApplicationEvent method is invoked. Within the onApplicationEvent method, we look for new Markdown files, and if any such new file exists, we persist it in the database.

But before that, we need to add another dependency -- jsoup.

Adding jsoup dependency

Remember how we have a synopsis attribute in the Post entity? We will use that attribute (or field, in the database) and set it to the first 150 characters of the actual post's body. However, after parsing the Markdown and rendering HTML from it, the post's body would look like, say,

<h1>Hello World!</h1><br /><p>This is the post's actual body, rendered in HTML!</p>

As you can imagine, most of the rendered text is actually HTML elements and symbols. Hence, we need to select the first 150 characters from the actual text, excluding the HTML elements and symbols.

We will need jsoup for doing exactly that. To add jsoup as one of our dependencies, make sure to add the following segment to your pom.xml file.

Like before, load the Maven changes in your POM file.

Then, we can proceed to our event-listener class.

ContextEventListener class

Begin by creating the class that implements ApplicationListener interface that takes in as type parameter the ContextReferencedEvent type. With this, our class would need to override the onApplicationEvent method.

We also need some instance variables for purposes that will be apparent soon.

With @Value, we inject into the postFiles, an array of Resource type, any files that exist in the classpath inside posts directory.

Next, we can implement our onApplicationEvent method.

In this method, we start by iterating over each file in the postFiles array. We check to see if a post with the same ID as the file exists in the database. If it does not, we persist the post in the database. Before saving the post, we set it's attributes.

Notice how we are using static utility methods from PostUtil and AuthorUtil classes for operations concerning posts and authors respectively.

PostUtil and AuthorUtil classes

In the PostUtil class, we define methods: getHtmlContentFromMdLines and getSynopsisFromHtmlContent.

The getHtmlContentFromMdLines returns a String of HTML content rendered using the List of Markdown lines passed as argument.

The getSynopsisFromHtmlContent method returns the first 150 characters of the text content parsed from the HTML content passed as argument. If the text content is fewer than 150 characters in length, the entire String is returned.

In the AuthorUtil class, we define method: bootstrapAuthor. If no author exists in the database, it creates a new author, before persisting it in the database, and returns it. Otherwise, it returns the first author that exists in the database.

Get it running

Now, when we run our Spring Boot application, or whenever we cause the Spring Context to refresh, a ContextRefreshedEvent is fired. This looks for a new blog post in the resources/posts/ directory and persists it.

To test this, let us create a posts directory inside the resources directory.

Inside it, I will create a new file, 1_Hello_World!.md, with the following content.

# Hello World!
This is my *first* blog post. <br>
Be sure to read future parts of this blog post series, <br>
titled **Build a Markdown-based Blog with Spring Boot**.

Then, let's run our Spring Boot application. After the JVM is up and running, we can check our database to see that our new blog post has been persisted successfully, along with the author.

Code

We have now created an application that persists new blog posts to our database. Now, we will work towards displaying blog posts using the Thymeleaf template engine. But that's for the next post.

The GitHub repository has been updated with this session's code, do check it out. Or if you need to check previous sessions' code, please do so as well.

Build a Markdown-based Blog with Spring Boot - Part 3

Roshan Adhikari — Mon, 24 May 2021 07:11:59 +0000

This piece is a part of a series of blog posts regarding this topic. If you haven't read the first two, please do so: Part 1 and Part 2.

By now, we have defined POJO classes for our entities, repository interfaces for those entities, and controllers for handling various HTTP requests.

Now, we should try and work with our database. For this, we need to specify various database-specific properties in the application.properties file inside resources directory.

Defining application properties

Inside the application.properties file, we specify our database URL, username, password, and the database initialization method.

The first three property names are pretty self-explanatory, and so are their values.

The last property, spring.jpa.hibernate.ddl-auto, specifies the database schema generation method. With a value of create-drop, we instruct Hibernate to drop the database schema and recreate it afterward using the entity model as a reference. More about schema generation strategies here.

Now when we run our @SpringBootApplication class (MdBlogApplication in my case), the database should be created with the name that we specified in the database URL.

After this, we get to read and parse Markdown files for our blog posts. First, lets add CommonMark as one of our dependencies.

Adding CommonMark to POM

CommonMark will help us to parse Markdown content from our Markdown files and render HTML blog posts from said content.

After adding the CommonMark dependency, IntelliJ IDEA will display a small icon allowing us to load Maven changes. This way, the related files will be downloaded and integrated into our classpath.

Now we are ready to parse some Markdown!

Conventions for Markdown files

From this point on, we will assume that our blog posts will be stored as Markdown files in the resources/posts/ directory.

Each Markdown file will be named with the following format in mind: 1_Hello_World!.md

Let's deconstruct the file name:

1: This is the ID for the post. It should be unique because our entity Post has a unique, auto-generating ID field.

_: We will use underscores (_) as the delimiter for separating the ID from the title of the post, and for separating the words in the title.

Hello_World!: The title of our blog post.

.md: The extension for the Markdown file.

The reasons for using these conventions will be apparent as soon as we begin reading lines from the Markdown files.

Reading lines from Markdown files

We need to write a utility class with methods that serve to read individual lines from a Markdown file, retrieve ID from a file name, and retrieve title from a file name.

For now, let us implement the method to read individual lines.

The readLinesFromMdFile method takes a file name as an argument and creates an InputStream from the ClassPathResource available under that name inside resources/posts/ directory.

We create a BufferedReader instance using the InputStream, and then collect individual lines in the file into a List instance, which is returned from the method.

Now onto retrieving the ID and title portions from the file name.

In the getTitleFromFileName method, we separate the extension (.md) from the rest of the file name, and split the remainder string excluding the ID portion.

In the getIdFromFileName method, again, we separate the extension from the rest of the file name. Then, we parse the ID portion as a long value.

Now we can finally render HTML content from a List of Markdown lines.

Rendering HTML

We need to write another utility class with a method that parses the passed List of Markdown lines and returns a String of rendered HTML content.

In the renderHtml method, we use CommonMark types like Parser to parse Markdown content, and HtmlRenderer to render the parsed Markdown content as HTML.

Finally, we return a String that represents our HTML blog post.

Code

This is it for part 3. In the next piece, we will pick up the project from this point on.

The GitHub repository has been updated for this part, as well as other parts.

Build a Markdown-based Blog with Spring Boot - Part 2

Roshan Adhikari — Sat, 22 May 2021 11:53:07 +0000

If you haven't read the first part, please do so.

At the end of the first part, we had defined the POJO classes for the two entities (Author and Post) in our project.

We begin the second part by defining the repository interfaces for those entities.

Defining repositories

Spring Data provides several Repository abstractions that aim at reducing the amount of human-generated code for data-access layers. Two of such abstractions that we need for our blog are CrudRepository and PagingAndSortingRepository.

The CrudRepository interface provides various methods for performing CRUD operations on an entity. On the other hand, the PagingAndSortingRepository is an extension of the CrudRepository that provides additional methods for retrieving entities using the paging and sorting abstraction.

The repositories for our entities are defined as follows.

Since we don't need to implement paging or sorting for the Author entity, we can extend CrudRepository for AuthorRepository. On the other hand, since we will be retrieving posts using the paging and sorting abstraction, we need to extend PagingAndSortingRepository for PostRepository.

Note how both CrudRepository and PagingAndSortingRepository take as type arguments the domain class to manage and the type of ID of the domain class.

Another thing to note is that we don't need to annotate either repository interfaces with @Repository or @Component. This is because CrudRepository and PagingAndSorting interfaces are annotated with @NoRepositoryBean, making them intermediate interfaces. Intermediate interfaces are not picked up by the Spring container and as such are not instantiated as beans.

However, any derivatives of such interfaces that are not annotated with @NoRepositoryBean -- in our case, AuthorRepository and PostRepository -- are automatically instantiated by the Spring container.

Defining controllers

Now onto defining controllers for the blog. These will handle requests to our web application and are responsible for delivering the appropriate view to the client.

We need to define two classes -- RootController and PostController -- each of which will handle respective requests.

RootController

RootController will be mapped to handle GET / requests.

As we see, all GET requests to the / route will be redirected to the /posts route.

PostController

PostController will be mapped to handle GET /posts/* requests.

At this point, there are no handler methods defined in the class. We define an instance variable named PAGINATIONSIZE that indicates the size of pagination -- i.e., the number of posts to render at once.

Then, we inject an implementation of PostRepository.

We will define two additional methods that handle requests made to GET /posts and GET /posts/{id}.

The getPaginatedPosts method takes three parameters -- the requested page, size of each page, and the model to add attributes to.

We obtain an instance of PageRequest using three arguments -- page, size, and the order of posts.

The order of posts should be in decreasing order of their ID since larger the ID, more recent the post was authored. This is because when we retrieve our posts, we need them in the order of their decreasing recency.

Then, since PostRepository extends the PagingAndSortingRepository, its findAll method can take the said instance of PageRequest, which in turn returns a Page of posts. This instance of type Page can be converted to a List type, and that is exactly what we did.

Then, using the total number of posts available, we compute the total number of pages to be made available to the client.

Finally, we add these values as attributes to our Model parameter.

Next, we define a getPostById method.

The getPostById method takes two parameters -- ID of the post to retrieve and the model to add attributes to.

Using the findById method of PostRepository, we retrieve an Optional instance of type Post. This provides a sense of null-safety as we reduce our chances of running into Null Pointer Exceptions.

Only if the Optional instance contains a non-null value (i.e., if a post of that ID exists), do we add the post as a model attribute.

Code

This is it for part 2. Stay tuned for more parts where we continue building our Markdown blog.

As always, all of the code up to this point has been pushed to the GitHub repository.

Build a Markdown-based Blog with Spring Boot - Part 1

Roshan Adhikari — Wed, 19 May 2021 16:09:47 +0000

In this piece, we will be building a personal blog containing articles written in Markdown.

We will use Spring Boot to develop the project and few other tools and libraries. We will push our project to a GitHub repository and use Heroku's Automatic Deployment feature to publish posts to our blog.

Additionally, we will use the RemoteMySQL service to host our remote MySQL database. To communicate with the database, we will need MySQL connector for Java and Spring Data JPA.

For rendering our view, we will use Thymeleaf.

This article is one part of a series of posts that I intend to publish on this topic.

For the entirety of this tutorial, I will use IntelliJ IDEA Community Edition as the IDE.

There may be some IntelliJ-specific shortcuts and hotkeys here and there, but you can follow along using your IDE of choice.

Now let's get going!

Generating Project

Just like how every fun Spring Boot adventure begins, go to start.spring.io (Spring Initializr) and configure our project.

Select the Maven Project option and Java as the language.

Choose a non-snapshot version of Spring Boot (I chose 2.4.5).

Then, fill up your Project Metadata -- including the Group, Artifact, Name, Description, and Package name.

We will be using Jar packaging, so select Jar. Then, choose 11 as the Java version.

For dependencies, we will need the following:

Spring Data JPA
MySQL Driver
Thymeleaf
Spring Web
Lombok

Finally, generate the project structure by clicking the Generate button.

Extract the resulting .zip file and you're ready to go!

Opening the project

Once the .zip file has been extracted, the project can be imported into the IDE.

Using IntelliJ IDEA, you can open the project by pointing IntelliJ to the root folder of the project (one that contains the pom.xml file as an immediate child).

After you've opened the project, take a look at the directory and file structure generated by Spring Intializr.

The pom.xml file is crucial for a Maven project.

It is filled with the dependencies that we selected from our little configuration session with Spring Initialzr.

Since Spring Boot is an opinionated framework, within its starter dependencies are a collection of other dependencies that have been curated by Spring Boot itself.

Defining entities

Our blog needs two entities -- posts and authors.

The author entity describes an author of a post with their name, email, and website.

The post entity describes a post, with its title, content, timestamp of creation, synopsis (first 150 characters of the post), and the ID of the author.

Both entities are identified by a unique, auto-generating ID.

Defining POJOs

The Plain Old Java Object (POJO) definitions for the entities are as described below.

We use JPA annotations to specify a one-to-many relationship between authors and posts.

Furthermore, to map Java's LocalDateTime typed attribtue to MySQL's datetime typed column, we need to convert between the two types (from LocalDateTime to TimeStamp and vice-versa).

For that, we define a new LocalDateTimeConverter class as following.

Code

I will end things at this much for now. We will continue the project from the next part of this series.

The project has been pushed to a GitHub repository, and you can find the code here.