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