Go Wrapper for using localstack in go testing

Installation

Please make sure that you have Docker installed.

go get github.com/elgohr/go-localstack

Usage

Authentication

Starting March 23, 2026, localstack requires a token.
In this way users must

1. Sign up for a free LocalStack account at localstack.cloud
2. Generate an auth token from the LocalStack Web App
3. Use localstack.NewAuthenticatedInstance("LOCALSTACK_AUTH_TOKEN") for passing the token

Old images can still be used without token via localstack.NewInstance(localstack.WithVersion(localstack.LastVersionBeforeAuthToken)).

Examples

With SDK V2 (using EndpointResolverV2). Please have a look at resolvers for a complete list of resolvers.

func ExampleLocalstackSdkV2EndpointResolverV2(t *testing.T) {
    l, err := localstack.NewAuthenticatedInstance("LOCALSTACK_AUTH_TOKEN")
    if err != nil {
        t.Fatalf("Could not connect to Docker %v", err)
    }
    if err := l.Start(); err != nil {
        t.Fatalf("Could not start localstack %v", err)
    }
    t.Cleanup(func() {
        if err := l.Stop(); err != nil {
            t.Fatalf("Could not stop localstack %v", err)
        }
    })
    
    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("dummy", "dummy", "dummy")),
    )
    if err != nil {
        t.Fatalf("Could not get config %v", err)
    }
    resolver := localstack.NewDynamoDbResolverV2(i)
    client := dynamodb.NewFromConfig(cfg, dynamodb.WithEndpointResolverV2(resolver))
	
    myTestWithV2Client(client)
}

With SDK V2 (using EndpointResolverV1)

func ExampleLocalstackSdkV2(t *testing.T) {
    l, err := localstack.NewAuthenticatedInstance("LOCALSTACK_AUTH_TOKEN")
    if err != nil {
        t.Fatalf("Could not connect to Docker %v", err)
    }
    if err := l.Start(); err != nil {
        t.Fatalf("Could not start localstack %v", err)
    }
    t.Cleanup(func() {
        if err := l.Stop(); err != nil {
            t.Fatalf("Could not stop localstack %v", err)
        }
	})
    
    cfg, err := config.LoadDefaultConfig(ctx,
        config.WithRegion("us-east-1"),
        config.WithEndpointResolverWithOptions(aws.EndpointResolverWithOptionsFunc(func(_, _ string, _ ...interface{}) (aws.Endpoint, error) {
            return aws.Endpoint{
			    PartitionID:       "aws", 
			    URL:               l.EndpointV2(localstack.SQS), 
			    SigningRegion:     "us-east-1", 
			    HostnameImmutable: true,
		    }, nil
        })),
        config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("dummy", "dummy", "dummy")),
    )
    if err != nil {
        t.Fatalf("Could not get config %v", err)
    }
    
    myTestWithV2(cfg)
}

With SDK V1

func TestWithLocalStack(t *testing.T) {
    l, err := localstack.NewAuthenticatedInstance("LOCALSTACK_AUTH_TOKEN")
    if err != nil {
        t.Fatalf("Could not connect to Docker %v", err)
    }
    if err := l.Start(); err != nil {
        t.Fatalf("Could not start localstack %v", err)
    }
    t.Cleanup(func() {
        if err := l.Stop(); err != nil {
            t.Fatalf("Could not stop localstack %v", err)
        }
    })

    myTestWith(&aws.Config{
        Credentials: credentials.NewStaticCredentials("not", "empty", ""),
        DisableSSL:  aws.Bool(true),
        Region:      aws.String(endpoints.UsWest1RegionID),
        Endpoint:    aws.String(l.Endpoint(localstack.SQS)),
    })
}