or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

container-configuration.mdendpoint-access.mdindex.mdservice-management.md
tile.json

tessl/maven-org-testcontainers--localstack

Testcontainers module for LocalStack - a fully functional local AWS cloud stack for developing and testing cloud and serverless applications without using actual AWS services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.testcontainers/localstack@1.21.x

To install, run

npx @tessl/cli install tessl/maven-org-testcontainers--localstack@1.21.0

index.mddocs/

Testcontainers LocalStack

Testcontainers LocalStack module provides a Java integration for LocalStack, a fully functional local AWS cloud stack for developing and testing cloud and serverless applications without using actual AWS services. The module enables developers to create lightweight, throwaway instances of AWS services for testing purposes.

Package Information

  • Package Name: org.testcontainers:localstack
  • Package Type: maven
  • Language: Java
  • Installation: Add to your pom.xml or build.gradle:
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>localstack</artifactId>
    <version>1.21.3</version>
    <scope>test</scope>
</dependency>
testImplementation "org.testcontainers:localstack:1.21.3"

Core Imports

import org.testcontainers.containers.localstack.LocalStackContainer;
import org.testcontainers.containers.localstack.LocalStackContainer.Service;
import org.testcontainers.containers.localstack.LocalStackContainer.EnabledService;
import org.testcontainers.utility.DockerImageName;

Basic Usage

import org.testcontainers.containers.localstack.LocalStackContainer;
import org.testcontainers.containers.localstack.LocalStackContainer.Service;
import org.testcontainers.utility.DockerImageName;

// Create LocalStack container with specific services
DockerImageName localstackImage = DockerImageName.parse("localstack/localstack:3.5.0");

@ClassRule
public static LocalStackContainer localstack = new LocalStackContainer(localstackImage)
    .withServices(Service.S3, Service.SQS, Service.LAMBDA);

// Use with AWS SDK v1
AmazonS3 s3 = AmazonS3ClientBuilder
    .standard()
    .withEndpointConfiguration(
        new AwsClientBuilder.EndpointConfiguration(
            localstack.getEndpointOverride(Service.S3).toString(),
            localstack.getRegion()
        )
    )
    .withCredentials(
        new AWSStaticCredentialsProvider(
            new BasicAWSCredentials(localstack.getAccessKey(), localstack.getSecretKey())
        )
    )
    .build();

// Use with AWS SDK v2
S3Client s3Client = S3Client.builder()
    .endpointOverride(localstack.getEndpointOverride(Service.S3))
    .credentialsProvider(StaticCredentialsProvider.create(
        AwsBasicCredentials.create(localstack.getAccessKey(), localstack.getSecretKey())
    ))
    .region(Region.of(localstack.getRegion()))
    .build();

Architecture

LocalStack Testcontainers module provides:

  • Container Management: Extends GenericContainer for Docker lifecycle management
  • Service Configuration: Support for 23+ AWS services via enum or custom service names
  • Version Compatibility: Automatic legacy mode detection for older LocalStack versions
  • Network Integration: Automatic hostname resolution for Docker networks
  • AWS SDK Integration: Seamless integration with both AWS SDK v1 and v2

Capabilities

Container Creation and Configuration

Core functionality for creating and configuring LocalStack containers with service specifications and Docker image management.

// Main constructor
public LocalStackContainer(DockerImageName dockerImageName);

// Service configuration
public LocalStackContainer withServices(Service... services);
public LocalStackContainer withServices(EnabledService... services);

Container Configuration

Service Management

Comprehensive AWS service support with predefined service constants and custom service definition capabilities.

// Service enumeration with 23+ AWS services
public enum Service implements EnabledService {
    S3("s3", 4572),
    LAMBDA("lambda", 4574),
    SQS("sqs", 4576),
    // ... all other services
}

// Custom service interface
public interface EnabledService {
    static EnabledService named(String name);
    String getName();
    default int getPort();
}

Service Management

Endpoint Access

Methods for obtaining service endpoints and connection details for AWS SDK client configuration.

public URI getEndpointOverride(EnabledService service);
public URI getEndpoint();
public String getAccessKey();
public String getSecretKey();
public String getRegion();

Endpoint Access

Types

// Main container class
public class LocalStackContainer extends GenericContainer<LocalStackContainer> {
    public static final int PORT = 4566;
    
    // Constructors
    public LocalStackContainer(DockerImageName dockerImageName);
    
    // Service configuration
    public LocalStackContainer withServices(Service... services);
    public LocalStackContainer withServices(EnabledService... services);
    
    // Endpoint methods
    public URI getEndpointOverride(EnabledService service);
    public URI getEndpoint();
    public String getAccessKey();
    public String getSecretKey(); 
    public String getRegion();
}

// Service interface
public interface EnabledService {
    static EnabledService named(String name);
    String getName();
    default int getPort();
}

// Service enumeration
public enum Service implements EnabledService {
    // 23+ AWS service constants with names and ports
}