How to Use the LocalStack Module With Testcontainers in CI

The LocalStack module starts an AWS emulator and exposes its endpoint, so SDK clients point at LocalStack with dummy credentials.

Use LocalStackContainer to emulate S3, SQS, and more. Enable the services you need, read getEndpoint(), and configure the AWS SDK to use that endpoint with placeholder credentials. For LocalStack-specific failures, see the LocalStack CI error guides.

Steps

• Add the localstack module and pin an image tag.
• Enable the services you need (e.g. S3).
• Read getEndpoint() and getRegion().
• Point the AWS SDK at that endpoint with dummy credentials.

Java example

@Container
static LocalStackContainer localstack =
    new LocalStackContainer(
        DockerImageName.parse("localstack/localstack:3"))
        .withServices(LocalStackContainer.Service.S3);

// endpoint: localstack.getEndpoint()
// region:   localstack.getRegion()
// creds:    accessKey/secretKey = localstack.getAccessKey()/getSecretKey()

Gotchas

• Point the SDK at getEndpoint(), not real AWS, or calls go to production.
• For "InvalidClientTokenId" or endpoint-connection errors, consult the LocalStack CI error guides.

Related guides