localstack

README

go-localstack

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

With SDK V2

func ExampleLocalstackWithContextSdkV2() {
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()
    
    l, err := localstack.NewInstance()
    if err != nil {
        log.Fatalf("Could not connect to Docker %v", err)
    }
    if err := l.StartWithContext(ctx); err != nil {
        log.Fatalf("Could not start 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 {
        log.Fatalf("Could not get config %v", err)
    }
    
    myTestWithV2(cfg)
}

With SDK V1

func TestWithLocalStack(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()

    l, err := localstack.NewInstance()
    if err != nil {
        log.Fatalf("Could not connect to Docker %v", err)
    }
    if err := l.StartWithContext(ctx); err != nil {
        log.Fatalf("Could not start 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)),
    })
}

Documentation

Index

• Variables
• type Instance
  • func NewInstance(opts ...InstanceOption) (*Instance, error)
  • func NewInstanceCtx(ctx context.Context, opts ...InstanceOption) (*Instance, error)
  • func (i *Instance) Endpoint(service Service) string
  • func (i *Instance) EndpointV2(service Service) string
  • func (i *Instance) Start() error
  • func (i *Instance) StartWithContext(ctx context.Context, services ...Service) error
  • func (i *Instance) Stop() error
• type InstanceOption
  • func WithClientFromEnv() (InstanceOption, error)
  • func WithClientFromEnvCtx(ctx context.Context) (InstanceOption, error)
  • func WithLabels(labels map[string]string) InstanceOption
  • func WithLogger(logger *logrus.Logger) InstanceOption
  • func WithTimeout(timeout time.Duration) InstanceOption
  • func WithVersion(version string) InstanceOption
• type Service

Variables

var (
	FixedPort = Service{Name: "all", Port: "4566/tcp"}

	CloudFormation   = Service{Name: "cloudformation", Port: "4581/tcp"}
	CloudWatch       = Service{Name: "cloudwatch", Port: "4582/tcp"}
	CloudWatchLogs   = Service{Name: "cloudwatchlogs", Port: "4586/tcp"}
	CloudWatchEvents = Service{Name: "cloudwatchevents", Port: "4587/tcp"}
	DynamoDB         = Service{Name: "dynamoDB", Port: "4569/tcp"}
	DynamoDBStreams  = Service{Name: "dynamoDBStreams", Port: "4570/tcp"}
	EC2              = Service{Name: "ec2", Port: "4597/tcp"}
	ES               = Service{Name: "es", Port: "4578/tcp"}
	Firehose         = Service{Name: "firehose", Port: "4573/tcp"}
	IAM              = Service{Name: "iam", Port: "4593/tcp"}
	Kinesis          = Service{Name: "kinesis", Port: "4568/tcp"}
	Lambda           = Service{Name: "lambda", Port: "4574/tcp"}
	Redshift         = Service{Name: "redshift", Port: "4577/tcp"}
	Route53          = Service{Name: "route53", Port: "4580/tcp"}
	S3               = Service{Name: "s3", Port: "4572/tcp"}
	SecretsManager   = Service{Name: "secretsmanager", Port: "4584/tcp"}
	SES              = Service{Name: "ses", Port: "4579/tcp"}
	SNS              = Service{Name: "sns", Port: "4575/tcp"}
	SQS              = Service{Name: "sqs", Port: "4576/tcp"}
	SSM              = Service{Name: "ssm", Port: "4583/tcp"}
	STS              = Service{Name: "sts", Port: "4592/tcp"}
	StepFunctions    = Service{Name: "stepfunctions", Port: "4585/tcp"}
)

Supported AWS/localstack services

var AvailableServices = map[Service]struct{}{
	FixedPort:        {},
	CloudFormation:   {},
	CloudWatch:       {},
	CloudWatchLogs:   {},
	CloudWatchEvents: {},
	DynamoDB:         {},
	DynamoDBStreams:  {},
	EC2:              {},
	ES:               {},
	Firehose:         {},
	IAM:              {},
	Kinesis:          {},
	Lambda:           {},
	Redshift:         {},
	Route53:          {},
	S3:               {},
	SecretsManager:   {},
	SES:              {},
	SNS:              {},
	SQS:              {},
	SSM:              {},
	STS:              {},
	StepFunctions:    {},
}

AvailableServices provides a map of all services for faster searches

Types

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance manages the localstack

func NewInstance

func NewInstance(opts ...InstanceOption) (*Instance, error)

NewInstance creates a new Instance Fails when Docker is not reachable

func NewInstanceCtx

func NewInstanceCtx(ctx context.Context, opts ...InstanceOption) (*Instance, error)

NewInstanceCtx is NewInstance, but with Context

func (*Instance) Endpoint

func (i *Instance) Endpoint(service Service) string

Endpoint returns the endpoint for the given service Endpoints are allocated dynamically (to avoid blocked ports), but are fix after starting the instance

func (*Instance) EndpointV2

func (i *Instance) EndpointV2(service Service) string

EndpointV2 returns the endpoint for the given service when used by aws-sdk-v2 Endpoints are allocated dynamically (to avoid blocked ports), but are fix after starting the instance

func (*Instance) Start

func (i *Instance) Start() error

Start starts the localstack

func (*Instance) StartWithContext

func (i *Instance) StartWithContext(ctx context.Context, services ...Service) error

StartWithContext starts the localstack and ends it when the context is done. Use it to also start individual services, by default all are started.

func (*Instance) Stop

func (i *Instance) Stop() error

Stop stops the localstack

type InstanceOption

type InstanceOption func(i *Instance)

InstanceOption is an option that controls the behaviour of localstack.

func WithClientFromEnv

func WithClientFromEnv() (InstanceOption, error)

WithClientFromEnv configures the instance to use a client that respects environment variables.

func WithClientFromEnvCtx

func WithClientFromEnvCtx(ctx context.Context) (InstanceOption, error)

WithClientFromEnvCtx like WithClientFromEnv but with context

func WithLabels

func WithLabels(labels map[string]string) InstanceOption

WithLabels configures the labels that will be applied on the instance.

func WithLogger

func WithLogger(logger *logrus.Logger) InstanceOption

WithLogger configures the instance to use the specified logger.

func WithTimeout

func WithTimeout(timeout time.Duration) InstanceOption

WithTimeout configures the timeout for terminating the localstack instance. This was invented to prevent orphaned containers after panics. The default timeout is set to 5 minutes.

func WithVersion

func WithVersion(version string) InstanceOption

WithVersion configures the instance to use a specific version of localstack. Must be a valid version string or "latest".

type Service

type Service struct {
	Name string
	Port string
}

Service represents an AWS service