Emulating AWS Seamlessly: A Practical Guide to LocalStack for Java Testing

Table of Contents

Article

In the world of modern cloud-native development, building applications that leverage AWS services is the norm. However, testing these applications can be a significant hurdle. Spinning up real AWS resources for every test run is slow, expensive, and can lead to accidental costs or "test pollution" between environments.

This is where LocalStack comes to the rescue. LocalStack is a powerful cloud service emulator that runs in a single container on your laptop or CI/CD pipeline. It provides a fully functional local cloud stack, allowing you to develop and test your AWS applications without connecting to a real AWS account.

In this guide, we'll walk through how to integrate LocalStack into your Java testing strategy.

Why Use LocalStack for Java Testing?

Cost Efficiency: Zero cost for API calls against local services.
Speed & Isolation: Tests run incredibly fast against local emulations and are completely isolated from your production and development AWS accounts.
Offline Development: Develop and test your application even without an internet connection.
CI/CD Integration: Easily incorporate AWS-dependent tests into your continuous integration pipelines.
Rapid Iteration: Quickly test different scenarios without waiting for cloud resource provisioning.

Hands-On Tutorial: Testing an S3 Application with LocalStack and JUnit 5

Let's build a simple Java application that interacts with Amazon S3 and write a test for it using LocalStack.

Step 1: Project Setup and Dependencies

We'll use Maven for this example. Add the following dependencies to your pom.xml. The Testcontainers LocalStack module is the de facto standard for managing LocalStack in Java tests.

<dependencies>
<!-- AWS SDK for S3 -->
<dependency>
<groupId>software.amazon.awssdk</groupId>
<artifactId>s3</artifactId>
<version>2.20.0</version>
</dependency>
<!-- Testcontainers for JUnit 5 Integration -->
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers</artifactId>
<version>1.19.3</version>
<scope>test</scope>
</dependency>
<!-- Testcontainers LocalStack Module -->
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>localstack</artifactId>
<version>1.19.3</version>
<scope>test</scope>
</dependency>
<!-- JUnit 5 -->
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.10.0</version>
<scope>test</scope>
</dependency>
</dependencies>

Step 2: The Class Under Test

Here is a simple service class that uses the AWS SDK for Java v2 to perform S3 operations.

// File: src/main/java/com/example/S3Service.java
package com.example;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
public class S3Service {
private final S3Client s3Client;
// Constructor injection for flexibility in testing
public S3Service(S3Client s3Client) {
this.s3Client = s3Client;
}
public void putObject(String bucketName, String key, String content) {
PutObjectRequest putObjectRequest = PutObjectRequest.builder()
.bucket(bucketName)
.key(key)
.build();
s3Client.putObject(putObjectRequest, RequestBody.fromString(content));
}
public String getObject(String bucketName, String key) {
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
.bucket(bucketName)
.key(key)
.build();
return s3Client.getObjectAsBytes(getObjectRequest).asString(StandardCharsets.UTF_8);
}
}

Step 3: Writing the JUnit 5 Test with Testcontainers

This is where the magic happens. We use Testcontainers to start a LocalStack container before our tests run and configure the AWS SDK to connect to it.

// File: src/test/java/com/example/S3ServiceTest.java
package com.example;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.localstack.LocalStackContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.utility.DockerImageName;
import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
import static org.assertj.core.api.Assertions.assertThat;
import static org.testcontainers.containers.localstack.LocalStackContainer.Service.S3;
// JUnit 5: Enable Testcontainers support
@Testcontainers
class S3ServiceTest {
// Define the LocalStack container. It will be shared across test methods.
@Container
private static final LocalStackContainer LOCAL_STACK =
new LocalStackContainer(DockerImageName.parse("localstack/localstack:3.0"))
.withServices(S3); // Specify which services we need
private S3Client s3Client;
private S3Service s3Service;
@BeforeEach
void setUp() {
// Build an S3Client that points to the LocalStack container
this.s3Client = S3Client.builder()
.endpointOverride(LOCAL_STACK.getEndpointOverride(S3)) // Override the AWS endpoint
.credentialsProvider(
StaticCredentialsProvider.create(
AwsBasicCredentials.create(
LOCAL_STACK.getAccessKey(),
LOCAL_STACK.getSecretKey()
)
)
)
.region(Region.of(LOCAL_STACK.getRegion()))
.build();
this.s3Service = new S3Service(s3Client);
// Create a bucket for our tests
String testBucket = "test-bucket";
s3Client.createBucket(CreateBucketRequest.builder().bucket(testBucket).build());
}
@Test
void shouldStoreAndRetrieveObjectFromS3() {
// Given
String bucketName = "test-bucket";
String key = "test-file.txt";
String expectedContent = "Hello, LocalStack!";
// When
s3Service.putObject(bucketName, key, expectedContent);
String retrievedContent = s3Service.getObject(bucketName, key);
// Then
assertThat(retrievedContent).isEqualTo(expectedContent);
}
}

Key Concepts Explained:

@Testcontainers: This JUnit 5 extension automatically manages the lifecycle of the containers marked with @Container.
LocalStackContainer: This class from Testcontainers pulls the official LocalStack Docker image and starts it.
Endpoint Override: This is the most critical part. We configure the S3Client to use the endpoint URL provided by the running LocalStack container instead of the real s3.amazonaws.com.
Fake Credentials: LocalStack doesn't care about real credentials, but the AWS SDK requires them. We use the dummy credentials provided by the LOCAL_STACK container itself.

Beyond the Basics: Pro-Tips

Testing Other Services: The pattern is the same for any AWS service (DynamoDB, SQS, Lambda, etc.). Just add the service to the .withServices() call and use the appropriate SDK client.
Using Fixed Ports: For debugging, you might want to expose fixed ports. You can use .withEnv("SERVICES", "s3") and .withExposedPorts(4566) (4566 is LocalStack's default edge port).
Optimizing Startup Time: To avoid the container startup time on every test run, consider using a Singleton Container Pattern to share a single LocalStack instance across multiple test classes.
LocalStack Configuration: You can use a docker-compose.yml file to start LocalStack with specific configurations and then point your tests to it instead of using Testcontainers.

Conclusion

By integrating LocalStack with Testcontainers and JUnit 5, you can write fast, reliable, and isolated integration tests for your AWS-dependent Java code. This setup mirrors a production-like environment on your local machine, significantly improving development speed and code quality while keeping costs at absolute zero. It's an essential tool for any Java developer building on AWS.