LocalStack Module

Testcontainers module for LocalStack, 'a fully functional local AWS cloud stack', to develop and test your cloud and serverless apps without actually using the cloud.

Usage example

You can start a LocalStack container instance from any Java application by using:

Container creation

LocalStackContainer localstack = new LocalStackContainer(LocalstackTestImages.LOCALSTACK_IMAGE)
    .withServices("s3")

Environment variables listed in the LocalStack configuration documentation may be used to customize LocalStack's configuration. Use the .withEnv(key, value) method on LocalStackContainer to apply configuration settings.

Note

Starting March 23, 2026, localstack/localstack requires authentication via a LOCALSTACK_AUTH_TOKEN environment variable. Without it, the container will fail to start.

Use .withEnv("LOCALSTACK_AUTH_TOKEN", System.getenv("LOCALSTACK_AUTH_TOKEN")) to pass the token. See the LocalStack blog post for more details.

Creating a client using AWS SDK

AWS SDK V2

S3Client s3 = S3Client
    .builder()
    .endpointOverride(localstack.getEndpoint())
    .credentialsProvider(
        StaticCredentialsProvider.create(
            AwsBasicCredentials.create(localstack.getAccessKey(), localstack.getSecretKey())
        )
    )
    .region(Region.of(localstack.getRegion()))
    .build();

Adding this module to your project dependencies

Add the following dependency to your pom.xml/build.gradle file:

GradleMaven

testImplementation "org.testcontainers:testcontainers-localstack:2.0.4"

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-localstack</artifactId>
    <version>2.0.4</version>
    <scope>test</scope>
</dependency>