0
# Testcontainers LocalStack
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.testcontainers:localstack
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `pom.xml` or `build.gradle`:
10

11
```xml
12
<dependency>
13
    <groupId>org.testcontainers</groupId>
14
    <artifactId>localstack</artifactId>
15
    <version>1.21.3</version>
16
    <scope>test</scope>
17
</dependency>
18
```
19

20
```groovy
21
testImplementation "org.testcontainers:localstack:1.21.3"
22
```
23

24
## Core Imports
25

26
```java
27
import org.testcontainers.containers.localstack.LocalStackContainer;
28
import org.testcontainers.containers.localstack.LocalStackContainer.Service;
29
import org.testcontainers.containers.localstack.LocalStackContainer.EnabledService;
30
import org.testcontainers.utility.DockerImageName;
31
```
32

33
## Basic Usage
34

35
```java
36
import org.testcontainers.containers.localstack.LocalStackContainer;
37
import org.testcontainers.containers.localstack.LocalStackContainer.Service;
38
import org.testcontainers.utility.DockerImageName;
39

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

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

47
// Use with AWS SDK v1
48
AmazonS3 s3 = AmazonS3ClientBuilder
49
    .standard()
50
    .withEndpointConfiguration(
51
        new AwsClientBuilder.EndpointConfiguration(
52
            localstack.getEndpointOverride(Service.S3).toString(),
53
            localstack.getRegion()
54
        )
55
    )
56
    .withCredentials(
57
        new AWSStaticCredentialsProvider(
58
            new BasicAWSCredentials(localstack.getAccessKey(), localstack.getSecretKey())
59
        )
60
    )
61
    .build();
62

63
// Use with AWS SDK v2
64
S3Client s3Client = S3Client.builder()
65
    .endpointOverride(localstack.getEndpointOverride(Service.S3))
66
    .credentialsProvider(StaticCredentialsProvider.create(
67
        AwsBasicCredentials.create(localstack.getAccessKey(), localstack.getSecretKey())
68
    ))
69
    .region(Region.of(localstack.getRegion()))
70
    .build();
71
```
72

73
## Architecture
74

75
LocalStack Testcontainers module provides:
76

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

83
## Capabilities
84

85
### Container Creation and Configuration
86

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

89
```java { .api }
90
// Main constructor
91
public LocalStackContainer(DockerImageName dockerImageName);
92

93
// Service configuration
94
public LocalStackContainer withServices(Service... services);
95
public LocalStackContainer withServices(EnabledService... services);
96
```
97

98
[Container Configuration](./container-configuration.md)
99

100
### Service Management
101

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

104
```java { .api }
105
// Service enumeration with 23+ AWS services
106
public enum Service implements EnabledService {
107
    S3("s3", 4572),
108
    LAMBDA("lambda", 4574),
109
    SQS("sqs", 4576),
110
    // ... all other services
111
}
112

113
// Custom service interface
114
public interface EnabledService {
115
    static EnabledService named(String name);
116
    String getName();
117
    default int getPort();
118
}
119
```
120

121
[Service Management](./service-management.md)
122

123
### Endpoint Access
124

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

127
```java { .api }
128
public URI getEndpointOverride(EnabledService service);
129
public URI getEndpoint();
130
public String getAccessKey();
131
public String getSecretKey();
132
public String getRegion();
133
```
134

135
[Endpoint Access](./endpoint-access.md)
136

137
## Types
138

139
```java { .api }
140
// Main container class
141
public class LocalStackContainer extends GenericContainer<LocalStackContainer> {
142
    public static final int PORT = 4566;
143
    
144
    // Constructors
145
    public LocalStackContainer(DockerImageName dockerImageName);
146
    
147
    // Service configuration
148
    public LocalStackContainer withServices(Service... services);
149
    public LocalStackContainer withServices(EnabledService... services);
150
    
151
    // Endpoint methods
152
    public URI getEndpointOverride(EnabledService service);
153
    public URI getEndpoint();
154
    public String getAccessKey();
155
    public String getSecretKey(); 
156
    public String getRegion();
157
}
158

159
// Service interface
160
public interface EnabledService {
161
    static EnabledService named(String name);
162
    String getName();
163
    default int getPort();
164
}
165

166
// Service enumeration
167
public enum Service implements EnabledService {
168
    // 23+ AWS service constants with names and ports
169
}
170
```