Spring Boot Functional Tests with Selenium and Testcontainers

Ensuring your application is working properly is a critical part of continuous integration and delivery. Unit tests help you to test your methods' business logic for both normal & edge cases. When it comes to guaranteeing that your users are able to correctly work with your application, we need something different. If your application exposes a frontend with user interaction, we can write functional tests to ensure different use cases are working. With this blog post, I'll provide an example of how to write Functional Tests for Spring Boot applications using Selenium and Testcontainers.

Spring Boot project setup

The Maven application uses the following dependencies:

The application to test for this example is rather simple. I'm using Thymeleaf and Spring MVC and want to write a test for the following view:

As a counterpart to the view above, the following controller provides the model:

I agree that this example does not reflect a typical enterprise application. Nevertheless, the following test setup works for any application which serves the frontend (e.g. Spring MVC or bundling SPA within the application).

Functional tests with Selenium and Testcontainers

To properly use Selenium to access the frontend of our application and write functional tests, we need a WebDriver. You can either manually download such a driver for the browser you want to test (e.g. Chrome or Firefox) or use Testcontainers.

The Testcontainers project provides a module to launch container-based WebDriver to avoid manual effort. Testcontainers also comes with a JUnit 5 Jupiter module to use JUnit extensions during the tests. This is quite useful as we otherwise would have to manage the lifecycle of the containers for our own.

Enabling the TestcontainersExtension is as simple as adding @Testcontainers to our class. Next, we can define a BrowserWebDriverContainer and add all required configurations. The JUnit extension from Testcontainers will now detect each container annotated with @Container and manage its lifecycle:

As we'll write a functional test, we have to bootstrap the whole Spring Boot application with @SpringBootTest. Once everything is up- and running, we can request the RemoteWebDriver instance from the container and perform any action with Selenium.

As the web driver runs within a Docker container and its own network,  accessing the Spring Boot application using localhost does not work. Instead, we can have to refer to http://host.docker.internal:" + port + "/index to be able to access our Thymeleaf application.

Please note: Depending on your operating system or Docker setup, host.docker.internal might not work. In that case, try 172.17.0.1 or container.getTestHostIpAddress().

Custom JUnit Jupiter Screenshot extension

Another useful functionality is to make screenshots once a test fails. As the functional tests are usually executed within a CI/CD pipeline, we need a visual output once a test fails.

This is a perfect use case for a custom JUnit 5 extension. We can write an extension that implements the AfterEachCallback to perform actions after each test. The ExtensionContext contains the information on whether an exception was thrown during test execution.

We can use this information and request a screenshot from the RemoteWebDriver once an exception occurred.

We can store the output of the screenshot to target/selenium-screenshots and archive this folder within our CI/CD pipeline.

You can find the source code for this example on GitHub. For more content on writing integration tests for your Spring Boot application, have a look at the following blog posts:

• Spring Boot Integration Tests with WireMock and JUnit 5
• Write Spring Boot integration tests with Testcontainers (JUnit 4.12 & 5)

Have fun testing your application with Testcontainers, Selenium and Spring Boot,

Phil