testcontainers-floci-go

Go Testcontainers module for Floci — the open-source, drop-in replacement for LocalStack Community Edition.

Floci emulates 42 AWS services in a single container with:

~24 ms startup time (native image)
~13 MiB idle memory
~90 MB Docker image
No auth tokens, no feature gates, MIT license

Installation

go get github.com/floci-io/testcontainers-floci-go

Requires Go 1.25+ and a running Docker daemon.

Quick start

package myservice_test

import (
    "context"
    "strings"
    "testing"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"

    floci "github.com/floci-io/testcontainers-floci-go"
)

func TestS3(t *testing.T) {
    ctx := context.Background()

    fc, err := floci.NewFlociContainer().Start(ctx)
    if err != nil {
        t.Fatal(err)
    }
    t.Cleanup(func() { _ = fc.Stop(ctx) })

    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion(fc.GetRegion()),
        config.WithBaseEndpoint(fc.GetEndpoint()),
        config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(
            fc.GetAccessKey(), fc.GetSecretKey(), "",
        )),
    )
    if err != nil {
        t.Fatal(err)
    }

    client := s3.NewFromConfig(cfg, func(o *s3.Options) {
        o.UsePathStyle = true // required for local endpoints
    })

    _, err = client.CreateBucket(ctx, &s3.CreateBucketInput{
        Bucket: aws.String("my-bucket"),
    })
    if err != nil {
        t.Fatal(err)
    }

    _, err = client.PutObject(ctx, &s3.PutObjectInput{
        Bucket: aws.String("my-bucket"),
        Key:    aws.String("hello.txt"),
        Body:   strings.NewReader("hello from floci"),
    })
    if err != nil {
        t.Fatal(err)
    }

    out, err := client.ListObjectsV2(ctx, &s3.ListObjectsV2Input{
        Bucket: aws.String("my-bucket"),
    })
    if err != nil {
        t.Fatal(err)
    }

    t.Logf("objects: %d", len(out.Contents))
}

S3 note: always use strings.NewReader or bytes.NewReader (seekable) when uploading objects. bytes.NewBufferString is not seekable and causes the AWS SDK to attempt trailing checksums, which require TLS and fail against a plain HTTP local endpoint.

Sharing a container across tests

Use TestMain to start the container once for the whole package:

package myservice_test

import (
    "context"
    "os"
    "testing"

    floci "github.com/floci-io/testcontainers-floci-go"
)

var fc *floci.StartedFlociContainer

func TestMain(m *testing.M) {
    ctx := context.Background()
    var err error
    fc, err = floci.NewFlociContainer().Start(ctx)
    if err != nil {
        panic(err)
    }
    code := m.Run()
    _ = fc.Stop(ctx)
    os.Exit(code)
}

Service configuration

Each of Floci's 42 services can be configured individually using typed config structs. Pass any struct to the corresponding With*Config method — unset fields keep their defaults.

S3

fc, _ := floci.NewFlociContainer().
    WithS3Config(floci.S3Config{
        Enabled:                     true,
        DefaultPresignExpirySeconds: 7200,
    }).
    Start(ctx)

SQS

fc, _ := floci.NewFlociContainer().
    WithSqsConfig(floci.SqsConfig{
        Enabled:                  true,
        DefaultVisibilityTimeout: 60,
        MaxMessageSize:           262144,
    }).
    Start(ctx)

DynamoDB

fc, _ := floci.NewFlociContainer().
    WithDynamoDbConfig(floci.DynamoDbConfig{Enabled: true}).
    Start(ctx)

Lambda

fc, _ := floci.NewFlociContainer().
    WithDedicatedNetwork(). // required for Lambda to reach Floci
    WithLambdaConfig(floci.LambdaConfig{
        Enabled:               true,
        DefaultMemoryMb:       256,
        DefaultTimeoutSeconds: 30,
        HotReloadEnabled:      true,
        ExposeRuntimePorts:    true, // invoke Lambdas from the host
    }).
    Start(ctx)

RDS (PostgreSQL / MySQL / MariaDB)

fc, _ := floci.NewFlociContainer().
    WithDedicatedNetwork().
    WithRdsConfig(floci.RdsConfig{
        Enabled:              true,
        DefaultPostgresImage: "postgres:16-alpine",
    }).
    Start(ctx)

ElastiCache (Redis / Valkey)

fc, _ := floci.NewFlociContainer().
    WithDedicatedNetwork().
    WithElastiCacheConfig(floci.ElastiCacheConfig{
        Enabled:      true,
        DefaultImage: "valkey/valkey:8",
    }).
    Start(ctx)

OpenSearch

fc, _ := floci.NewFlociContainer().
    WithDedicatedNetwork().
    WithOpenSearchConfig(floci.OpenSearchConfig{
        Enabled: true,
        Mock:    false,
    }).
    Start(ctx)

MSK (Kafka via Redpanda)

fc, _ := floci.NewFlociContainer().
    WithDedicatedNetwork().
    WithMskConfig(floci.MskConfig{
        Enabled:      true,
        DefaultImage: "redpandadata/redpanda:latest",
    }).
    Start(ctx)

All available config structs

Struct	AWS service
`AcmConfig`	AWS Certificate Manager
`ApiGatewayConfig`	API Gateway (v1)
`ApiGatewayV2Config`	API Gateway (v2)
`AppConfigConfig`	AppConfig
`AppConfigDataConfig`	AppConfig Data
`AthenaConfig`	Athena
`BedrockRuntimeConfig`	Bedrock Runtime
`CloudFormationConfig`	CloudFormation
`CloudWatchLogsConfig`	CloudWatch Logs
`CloudWatchMetricsConfig`	CloudWatch Metrics
`CodeBuildConfig`	CodeBuild
`CodeDeployConfig`	CodeDeploy
`CognitoConfig`	Cognito
`DynamoDbConfig`	DynamoDB
`Ec2Config`	EC2
`EcrConfig`	ECR
`EcsConfig`	ECS
`EksConfig`	EKS
`ElastiCacheConfig`	ElastiCache
`ElbV2Config`	ELB v2
`EventBridgeConfig`	EventBridge
`FirehoseConfig`	Kinesis Firehose
`GlueConfig`	Glue
`IamConfig`	IAM
`KinesisConfig`	Kinesis
`KmsConfig`	KMS
`LambdaConfig`	Lambda
`MskConfig`	MSK (Kafka)
`OpenSearchConfig`	OpenSearch
`PipesConfig`	EventBridge Pipes
`RdsConfig`	RDS
`ResourceGroupsTaggingConfig`	Resource Groups Tagging
`S3Config`	S3
`SchedulerConfig`	EventBridge Scheduler
`SecretsManagerConfig`	Secrets Manager
`SesConfig`	SES
`SesV2Config`	SES v2
`SnsConfig`	SNS
`SqsConfig`	SQS
`SsmConfig`	SSM Parameter Store
`StepFunctionsConfig`	Step Functions

Container options

fc, _ := floci.NewFlociContainer().
    WithImage("floci/floci:latest").   // pin a specific tag
    WithRegion("eu-west-1").
    WithAccountID("111122223333").
    WithAvailabilityZone("eu-west-1a").
    WithDedicatedNetwork().            // isolated Docker network for stateful services
    Start(ctx)

Connection details

Method	Returns
`GetEndpoint()`	`http://host:port` — pass as base endpoint to AWS SDK clients
`GetRegion()`	AWS region string
`GetAccessKey()`	Access key (`"test"`)
`GetSecretKey()`	Secret key (`"test"`)
`GetAccountID()`	AWS account ID
`GetAvailabilityZone()`	Availability zone
`GetDedicatedNetworkName()`	Docker network name (empty if none)
`GetMappedPort(ctx, port)`	Host port mapped from the given container port

Dedicated network

Services that spawn real Docker containers (Lambda, RDS, ElastiCache, MSK, OpenSearch, ECR, EKS) need a Docker network to communicate with Floci. Call WithDedicatedNetwork() to have the module create and manage one automatically:

fc, _ := floci.NewFlociContainer().
    WithDedicatedNetwork().
    WithLambdaConfig(floci.LambdaConfig{Enabled: true}).
    Start(ctx)

// The network name is passed to Floci automatically via FLOCI_SERVICES_DOCKER_NETWORK.
// fc.GetDedicatedNetworkName() returns it if you need it elsewhere.

The network is removed when Stop is called.

Docker image variants

Tag	Description
`floci/floci:latest`	Native image — sub-second startup (recommended)
`floci/floci:x.y.z`	Pinned release
`floci/floci:latest-compat`	Includes Python 3, AWS CLI, and boto3
`floci/floci:nightly`	Latest nightly build from `main`

Requirements

Go 1.25+
Docker (running locally or in CI)
github.com/testcontainers/testcontainers-go v0.42.0

Examples

examples/s3 — create a bucket, upload documents, list objects
examples/dynamodb — DynamoDB tables and items
examples/sqs — queues, send and receive messages
examples/sns — topics and subscriptions
examples/lambda — deploy and invoke a function

Running the tests

go test -v ./...

Requires Docker running locally; the floci/floci:latest image is pulled automatically on first run.

Related projects

Floci — the emulator itself
testcontainers-floci — Java / Spring Boot module
testcontainers-floci-node — Node.js module
testcontainers-floci-python — Python module
Testcontainers for Go

License

MIT

Navigation Menu

Uh oh!

Uh oh!

testcontainers-floci-go

Installation

Quick start

Sharing a container across tests

Service configuration

S3

SQS

DynamoDB

Lambda

RDS (PostgreSQL / MySQL / MariaDB)

ElastiCache (Redis / Valkey)

OpenSearch

MSK (Kafka via Redpanda)

All available config structs

Container options

Connection details

Dedicated network

Docker image variants

Requirements

Examples

Running the tests

Related projects

License

Uh oh!

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

testcontainers-floci-go

Installation

Quick start

Sharing a container across tests

Service configuration

S3

SQS

DynamoDB

Lambda

RDS (PostgreSQL / MySQL / MariaDB)

ElastiCache (Redis / Valkey)

OpenSearch

MSK (Kafka via Redpanda)

All available config structs

Container options

Connection details

Dedicated network

Docker image variants

Requirements

Examples

Running the tests

Related projects

License