testcontainers-floci-go

May 12, 2026 · View on GitHub

A Testcontainers module for Floci — a free, open-source local AWS emulator.

Requirements

  • Go 1.25+ (current latest; required by testcontainers-go v0.42.0 — if you need Go 1.22/1.23/1.24 support, pin an older version of this module)
  • Docker

Installation

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

Quickstart

package myservice_test

import (
    "context"
    "testing"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/credentials"
    floci "github.com/floci-io/testcontainers-floci-go"
)

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

    fc, err := floci.NewFlociContainer().Start(ctx)
    if err != nil {
        t.Fatalf("starting floci: %v", 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.Fatalf("loading AWS config: %v", err)
    }

    // Use cfg to build any aws-sdk-go-v2 client (S3, SQS, DynamoDB, etc.)
    _ = cfg
}

Configuration

All services are enabled by default. Use With<Service>Config to tune or disable specific services:

fc, err := floci.NewFlociContainer().
    WithRegion("eu-west-1").
    WithS3Config(floci.S3Config{
        Enabled:                     true,
        DefaultPresignExpirySeconds: 7200,
    }).
    WithSqsConfig(floci.SqsConfig{
        Enabled:                  true,
        DefaultVisibilityTimeout: 60,
        MaxMessageSize:           131072,
    }).
    Start(ctx)

Container-based services (Lambda, RDS, ElastiCache, etc.)

Services that spin up their own Docker containers need a shared network:

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

Supported services

ServiceConfig type
ACMAcmConfig
API GatewayApiGatewayConfig / ApiGatewayV2Config
AppConfigAppConfigConfig / AppConfigDataConfig
AthenaAthenaConfig
Bedrock RuntimeBedrockRuntimeConfig
CloudFormationCloudFormationConfig
CloudWatch LogsCloudWatchLogsConfig
CloudWatch MetricsCloudWatchMetricsConfig
CodeBuildCodeBuildConfig
CodeDeployCodeDeployConfig
CognitoCognitoConfig
DynamoDBDynamoDbConfig
EC2Ec2Config
ECREcrConfig
ECSEcsConfig
EKSEksConfig
ElastiCacheElastiCacheConfig
ELBv2ElbV2Config
EventBridgeEventBridgeConfig
FirehoseFirehoseConfig
GlueGlueConfig
IAMIamConfig
KinesisKinesisConfig
KMSKmsConfig
LambdaLambdaConfig
MSKMskConfig
OpenSearchOpenSearchConfig
PipesPipesConfig
RDSRdsConfig
Resource Groups TaggingResourceGroupsTaggingConfig
S3S3Config
SchedulerSchedulerConfig
Secrets ManagerSecretsManagerConfig
SESSesConfig / SesV2Config
SNSSnsConfig
SQSSqsConfig
SSMSsmConfig
Step FunctionsStepFunctionsConfig

Examples

Running the tests

go test -v ./...

Requires Docker running locally and the floci/floci:latest image available (pulled automatically on first run).

Reference