Test Spring Applications Using AWS With Testcontainers and LocalStack

If your Spring application uses AWS components like S3, SNS, or SQS you might wonder how to write effective integration tests. Should I mock the entire interaction with AWS? Should I duplicate the AWS infrastructure for testing? Is there maybe a local AWS clone available? With this blog post, you'll learn how to write integration tests for your Spring Boot application integrating AWS service with the help of Testcontainers and LocalStack. The demo application uses both SQS and S3 to process order events for which we'll write an integration test.

UPDATE: With more recent versions of LocalStack, Testcontainers, and Spring Cloud AWS, the required integration test setup is more streamlined. More about this in an upcoming blog post.

Spring Boot Application Setup

The application is a basic Spring Boot project using Java 11 and Spring Cloud. We're using the spring-boot-starter-aws-messaging to have almost no setup for connecting to an SQS queue. Furthermore, this messaging starter has a transitive dependency to spring-cloud-starter-aws that provides the core AWS support:

For writing integration tests we need the following test dependencies:

Let's have a look at why we need these dependencies and what they are doing.

As our demo application makes use of AWS services (S3 and SQS), we have to provide this infrastructure for the integration tests. We can either duplicate the AWS services for our tests or provide a mock infrastructure. Option one is using real AWS services for our tests and hence making sure the application can work with them. It has the downside of additional AWS costs and once two developers execute the integration tests, they might run into issues.

With option two we have the drawback of using a mock infrastructure and a more artificial environment (e.g. almost no latency, not using the real AWS services, …).  On the other hand, it's cheap and can run on multiple machines in parallel. For this tutorial we're choosing option two and make use of LocalStack:

• Easy-to-use test/mocking framework for developing AWS applications
• It spins up an environment with the same functionality and APIs as AWS
• Available as Docker containers and supports all core AWS services in the community edition

To manage the lifecycle of the LocalStack Docker container, we're using Testcontainers:

• De-facto standard when it comes to spinning up containers for JUnit tests (introduction article)
• Comes with an own LocalStack module

Next, as we want to verify the main functionality of the application (processing of SQS messages), we have to test asynchronous code. Fortunately, there is a great Java library available for this Awaitility:

• Java Utility library to test asynchronous code
• Express expectations using a DSL

Finally, the Spring Boot Starter Test serves multiple purposes:

• Swiss-army knife for testing Spring applications
• Includes basic testing infrastructure: test engine, assertion libraries, mocking library, etc.
• Exclude the junit-vintage-engine to only use JUnit 5

Spring Boot Application Walkthrough

First, let's have a look at how the connection to AWS is configured. The Java AWS SDK offers multiple ways (e.g. system properties, env variables, etc.) to configure the AWS credentials. As we are using the Spring Cloud Starter for AWS, we can additionally configure them the Spring Boot-way by specifying both the access and secret key inside our application.yml :

Apart from this, we're also specifying the AWS region and both SQS and S3 logical resource names. If we're using the Parameter Store of the AWS Systems Manager (SSM), we can also define such configuration values in AWS. As the application is not running inside an AWS stack (e.g. EC2), automatic stack detection is disabled with cloud.aws.stack.auto.

The actual processing logic of this demo application happens inside the SQS listener. As we are using the messaging starter for AWS, we can easily subscribe to an SQS queue using @SqsListener. The logic for each incoming message is dead-simple. We'll log each incoming OrderEvent and upload it to S3.

The OrderEvent is a POJO containing information about the order:

While the raw SQS payload is a String, the AWS messaging dependency allows us to serialize it to a Java object. We are already doing this, as the processMessage method takes OrderEvent as a parameter. Behind the scenes, this conversion is done using the MappingJackson2MessageConverter.

By default, this message converter instantiates its own Jackson ObjectMapper. As the OrderEvent uses a Java 8 LocalDateTime we need the Java Time Module registered inside the ObjectMapper.

To override this default behavior, we can provide our own MappingJackson2MessageConverter and set the ObjectMapper. We're using the auto-configured ObjectMapper from Spring Boot for this as it contains all required Jackson modules out-of-the-box:

The second bean inside this configuration is optional, but we'll use the QueueMessagingTemplate to send a message to SQS during test execution.

Next, let's see how we can write integration tests for our Spring application using these AWS components with Testcontainers and LocalStack.

Integration Test Setup with Testcontainers and LocalStack

Now we can focus on testing this application logic with an integration test. During the test execution, we need access to SQS and S3. For this we'll use the LocalStack module of Testcontainers and use the JUnit Jupiter extension to manage the lifecycle of the LocalStack Docker container:

As our application expects an SQS queue to subscribe to and an S3 bucket to write data to, we need to create both resources. We can perform additional setup tasks inside the Docker container using the execInContainer method from Testcontainers. We can use this mechanism to create the infrastructure using awslocal (thin AWS CLI wrapper of LocalStack).

As part of the JUnit Jupiter lifecycle@BeforeAll, we prepare the LocalStack environment before any test is executed.

As the queue and bucket names differ from the ones we used for the production profile, we can specify the new names inside src/test/resources/application.yml:

Verify the AWS SQS Message Processing of The Spring Application

The remaining setup for our test is to configure the AWS clients properly. Without manually specifying the required clients as Spring beans, the auto-configure mechanism would try to connect to the real AWS cloud during application startup.

As we don't want to connect to the actual AWS services and rather use our mocked environment of LocalStack, we can provide the beans for ourselves a @TestConfiguration class :

Both clients will now point to the local AWS S3 and AWS SQS instances. As our @TestConfiguration class is an inner static class of our integration test, it will be detected automatically. There's no need to explicitly use @Import(AwsTestConfig.class) unless we outsource it to a dedicated file.

Finally, we can now write the test for our order event processing.

First, we put a message into the local AWS SQS queue using the QueueMessagingTemplate and then expect to find an object in the S3 bucket with the given order id:

The given() part comes from Awaitility. As this message processing happens asynchronously, we can't expect the object to be present in S3 right after we put the message in the queue. Therefore we'll wait for five seconds to find the object in S3 and otherwise fail the test.

The .ignoreException() part is necessary, as the S3 client will throw this exception whenever it can't find the request object, which might be the case in the first milliseconds of trying to find it.

Summary

With the setup above you are now able to write integration tests for your Spring application and can include AWS components using LocalStack and Testcontainers. Furthermore, this setup also works for any other AWS component that LocalStack supports e.g. DynamoDB or SNS.

The demo application is available on GitHub.

If you’re interested in learning more about building applications with Spring Boot and AWS from top to bottom, make sure to take a look at the Stratospheric project. With this book, you'll learn all you need to know to get your Spring Boot application into production with AWS and how to effectively integrate multiple AWS services. (PS: I'm co-authoring this book)

Have fun writing integration tests for your Spring application using AWS with LocalStack and Testcontainers,

Phil