1. Overview
Unit tests shouldn’t depend on network connections. When testing code that interacts with Amazon SQS, the cleanest method is to use dependency injection for the AWS SDK for Java clients, like SqsClient or SqsAsyncClient.
In our tests, we can then replace the real client with a mock object. This allows us to verify that our code constructs the exact SendMessageRequest we expect, without ever actually sending a message to AWS. This approach keeps your tests fast, deterministic, and credential-free.
In this tutorial, we’ll discuss how to mock Amazon SQS in unit tests.
2. Dependencies
Let’s start by adding the Amazon SQS dependency to our project’s pom.xml file:
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>sqs</artifactId>
<version>2.35.10</version>
</dependency>
This dependency provides us with the SqsClient, SqsAsyncClient, and related request/response models, which we’ll use to interact with the Amazon SQS service.
3. The Service Under Test
Before writing tests, we need a component to test. Let’s create a simple service, SqsMessagePublisher, whose sole responsibility is to send a message to a specified SQS queue.
A crucial design element of this service is its use of dependency injection. Instead of creating an instance of SqsClient inside the class, we accept it as a constructor parameter. This design choice is fundamental, as it decouples our business logic from the concrete implementation of the SQS client. This separation is what makes the class easily testable, allowing us to provide a mock client in our tests instead of a real one.
public class SqsMessagePublisher {
private final SqsClient sqsClient;
public SqsMessagePublisher(SqsClient sqsClient) {
this.sqsClient = sqsClient;
}
public String publishMessage(String queueUrl, String messageBody) {
SendMessageRequest request = SendMessageRequest.builder()
.queueUrl(queueUrl)
.messageBody(messageBody)
.build();
SendMessageResponse response = sqsClient.sendMessage(request);
return response.messageId();
}
}
The publishMessage() method takes a queue URL and a message body, constructs a SendMessageRequest, sends it using the injected SqsClient, and returns the message ID from the response. Our goal in the unit test will be to verify that the SendMessageRequest object passed to sqsClient.sendMessage() is constructed with the correct queue URL and message body.
4. Mocking the Synchronous SqsClient
With our service in place, we can now write a unit test. We’ll use JUnit 5 as our test runner and Mockito to create a mock version of the SqsClient.
4.1. Test Setup
First, let’s set up the test class. We’ll use three key annotations:
- @ExtendWith(MockitoExtension.class): This annotation integrates Mockito with the JUnit 5 test lifecycle, enabling the use of other Mockito annotations
- @Mock: This creates a mock implementation of the annotated field. In our case, it will create a mock SqsClient
- @InjectMocks: This creates an instance of the annotated class and injects any fields annotated with @Mock into it. This automatically wires our mock SQS client into our SqsMessagePublisher instance
@ExtendWith(MockitoExtension.class)
class SqsMessagePublisherUnitTest {
@Mock
private SqsClient sqsClient;
@InjectMocks
private SqsMessagePublisher messagePublisher;
// Tests will go here
}
4.2. Writing the Test
The core of our test is to verify that our service calls the SQS client with the correct parameters. To do this, we first stub the client’s response to prevent a NullPointerException. Then, we use an ArgumentCaptor to capture the request sent to the mock client and assert its contents:
@Test
void whenPublishMessage_thenMessageIsSentWithCorrectParameters() {
// Arrange
String queueUrl = "https://sqs.us-east-1.amazonaws.com/123456789012/MyQueue";
String messageBody = "Hello, SQS!";
String expectedMessageId = "test-message-id-123";
SendMessageResponse mockResponse = SendMessageResponse.builder()
.messageId(expectedMessageId)
.build();
when(sqsClient.sendMessage(any(SendMessageRequest.class))).thenReturn(mockResponse);
// Act
String actualMessageId = messagePublisher.publishMessage(queueUrl, messageBody);
// Assert
assertThat(actualMessageId).isEqualTo(expectedMessageId);
ArgumentCaptor<SendMessageRequest> requestCaptor = ArgumentCaptor.forClass(SendMessageRequest.class);
verify(sqsClient).sendMessage(requestCaptor.capture());
SendMessageRequest capturedRequest = requestCaptor.getValue();
assertThat(capturedRequest.queueUrl()).isEqualTo(queueUrl);
assertThat(capturedRequest.messageBody()).isEqualTo(messageBody);
}
In the “Arrange” phase, we use when().thenReturn() to tell our mock sqsClient what to return. In the “Assert” phase, verify(sqsClient).sendMessage() confirms the method was called, and the ArgumentCaptor allows us to inspect the SendMessageRequest that was passed to it.
5. Mocking the Synchronous SqsClient
The same testing strategy works for the non-blocking SqsAsyncClient:
public class SqsAsyncMessagePublisher {
private final SqsAsyncClient sqsAsyncClient;
public SqsAsyncMessagePublisher(SqsAsyncClient sqsAsyncClient) {
this.sqsAsyncClient = sqsAsyncClient;
}
public CompletableFuture<String> publishMessage(String queueUrl, String messageBody) {
SendMessageRequest request = SendMessageRequest.builder()
.queueUrl(queueUrl)
.messageBody(messageBody)
.build();
return sqsAsyncClient.sendMessage(request)
.thenApply(SendMessageResponse::messageId);
}
}
When testing, the only change is in how we stub the response. Since the async client returns a CompletableFuture, we must wrap our mock response in one using CompletableFuture.completedFuture():
@ExtendWith(MockitoExtension.class)
class SqsAsyncMessagePublisherUnitTest {
@Mock
private SqsAsyncClient sqsAsyncClient;
@InjectMocks
private SqsAsyncMessagePublisher messagePublisher;
@Test
void whenPublishMessage_thenMessageIsSentAsynchronously() throws Exception {
// Arrange
String queueUrl = "https://sqs.us-east-1.amazonaws.com/123456789012/MyAsyncQueue";
String messageBody = "Hello, Async SQS!";
String expectedMessageId = "test-async-message-id-456";
SendMessageResponse mockResponse = SendMessageResponse.builder()
.messageId(expectedMessageId)
.build();
when(sqsAsyncClient.sendMessage(any(SendMessageRequest.class)))
.thenReturn(CompletableFuture.completedFuture(mockResponse));
// Act
String actualMessageId = messagePublisher.publishMessage(queueUrl, messageBody).get();
// Assert
assertThat(actualMessageId).isEqualTo(expectedMessageId);
ArgumentCaptor<SendMessageRequest> requestCaptor = ArgumentCaptor.forClass(SendMessageRequest.class);
verify(sqsAsyncClient).sendMessage(requestCaptor.capture());
SendMessageRequest capturedRequest = requestCaptor.getValue();
assertThat(capturedRequest.queueUrl()).isEqualTo(queueUrl);
assertThat(capturedRequest.messageBody()).isEqualTo(messageBody);
}
}
The verification logic with ArgumentCaptor remains identical, demonstrating the robustness of this testing pattern.
6. A Note on Integration Testing
These unit tests are perfect for verifying our application’s logic in isolation. However, they cannot validate real-world concerns like IAM permissions, network connectivity, or correct queue configuration.
For that, we need integration tests. A common approach is to use tools like Testcontainers with LocalStack, which provides a local emulation of AWS services. This allows you to test the full integration with a real SQS endpoint without needing actual AWS credentials.
7. Conclusion
In this article, we demonstrated how to unit test code that interacts with Amazon SQS. By using dependency injection, we can easily substitute the real SQS client with a mock in our tests.
With Mockito, we stubbed the client’s behavior and used an ArgumentCaptor to verify that our code constructed the correct request. This powerful technique works for both synchronous and asynchronous clients, enabling us to write fast, reliable, and isolated unit tests.
As always, the code is available over on GitHub.
