Skip to content

S3Mock

Not available until the next release main

Introduction

The Testcontainers module for S3Mock — a popular open-source library by Adobe that mocks the AWS S3 API for use in tests. S3Mock runs as a lightweight Docker container and fully implements the S3 API, allowing tests to interact with S3 buckets and objects without real AWS credentials or network access.

Adding this module to your project dependencies

Please run the following command to add the S3Mock module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/s3mock

Usage example

ctx := context.Background()

s3mockContainer, err := s3mock.Run(ctx,
    "adobe/s3mock:3.9.1",
    s3mock.WithInitialBuckets("mybucket"),
)
defer func() {
    if s3mockContainer != nil {
        if err := testcontainers.TerminateContainer(s3mockContainer); err != nil {
            log.Printf("failed to terminate container: %s", err)
        }
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

Configuring the AWS SDK v2

S3Mock fully implements the AWS S3 API. Point the AWS SDK v2 at the container's EndpointURL to use it in tests — no real credentials are required.

First implement a custom EndpointResolverV2 that routes all S3 calls to the container:

type s3EndpointResolver struct {
    endpointURL string
}

// ResolveEndpoint routes the S3 API call to the S3Mock container endpoint URL.
func (r *s3EndpointResolver) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (smithyendpoints.Endpoint, error) {
    params.Endpoint = aws.String(r.endpointURL)
    return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params)
}

Then create the S3 client:

endpointURL, err := s3mockContainer.EndpointURL(ctx)
if err != nil {
    log.Printf("failed to get endpoint URL: %s", err)
    return
}

awsCfg, err := config.LoadDefaultConfig(ctx,
    config.WithRegion("us-east-1"),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("test", "test", "")),
)
if err != nil {
    log.Printf("failed to load AWS config: %s", err)
    return
}

client := s3.NewFromConfig(awsCfg, func(o *s3.Options) {
    o.EndpointResolverV2 = &s3EndpointResolver{endpointURL: endpointURL}
    o.UsePathStyle = true
})

Module Reference

Run function

  • Not available until the next release main

The S3Mock module exposes one entrypoint function to create the S3Mock container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "adobe/s3mock:3.9").

Container Options

When starting the S3Mock container, you can pass options in a variadic way to configure it.

WithInitialBuckets

  • Not available until the next release main

Use WithInitialBuckets to pre-create one or more S3 buckets when the container starts:

ctr, err := s3mock.Run(ctx, "adobe/s3mock:3.9.1",
    s3mock.WithInitialBuckets("bucket1", "bucket2"),
)

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Container Methods

EndpointURL

  • Not available until the next release main

Returns the HTTP endpoint URL for the S3Mock container (mapped from container port 9090). Use this URL as the base endpoint when configuring the AWS SDK.

endpointURL, err := ctr.EndpointURL(ctx)

HTTPSEndpointURL

  • Not available until the next release main

Returns the HTTPS endpoint URL for the S3Mock container (mapped from container port 9191).

httpsURL, err := ctr.HTTPSEndpointURL(ctx)