docker

README

go-docker-testsuite

Library to run any third-party dependency in Docker on any platform Docker supports The main purpose is to allow runnings integration tests against almost any database or other dependency running right within docker and available via network.

Applications

The test suite provides some of applications, i.e. wrappers for particular docker image, here's the list:

• MinIO
• MySQL/MariaDB/Percona Server
• PostgreSQL
• Redis
• ScyllaDB

Each application could provide its own interface to interact so please refer to applications package for some examples.

Example usage

Go Docker Testsuite provides its own interface for each application aiming to make it clean and easy to use each particular application.

Here's an example for MySQL database:

package main

import (
    "context"
    "database/sql"

    _ "github.com/go-sql-driver/mysql"

    "github.com/teran/go-docker-testsuite/applications/mysql"
)

func main() {
    ctx := context.Background()

    app, err := mysql.New(ctx, "index.docker.io/library/mysql:8.0.4")
    if err != nil {
        panic(err)
    }
    defer app.Close(ctx)

    if err := app.CreateDB(ctx, "important_database"); err != nil {
        panic(err)
    }

    db, err := sql.Open("mysql", app.MustDSN("important_database"))
    if err != nil {
        panic(err)
    }

    if err := db.Ping(); err != nil {
        panic(err)
    }

    if _, err := db.ExecContext(ctx, "SELECT 1"); err != nil {
        panic(err)
    }
}

Documentation

Index

• Variables
• func DockerIP() (string, error)
• func NewHostConfig(pb *PortBindings) (*dockerContainer.HostConfig, error)
• func OneToOneRandomPort(proto Protocol, srcPort uint16) (string, uint16, []string, error)
• func RandomPort(proto Protocol, dstPort uint16) (string, uint16, []string, error)
• type Application
  • func NewApplication(c Container, hooks ...Hook) *Application
• type Binding
• type Container
  • func NewContainer(name, image string, cmd []string, environment Environment, ports *PortBindings) (Container, error)
  • func NewContainerWithClient(cli *client.Client, name, image string, cmd []string, env Environment, ...) (Container, error)
• type ContainerID
• type ContainerInfo
• type Environment
  • func NewEnvironment() Environment
  • func (e Environment) BoolVar(name string, value bool) Environment
  • func (e Environment) Eval(c ContainerInfo) (es []string)
  • func (e Environment) Int16Var(name string, value int16) Environment
  • func (e Environment) Int32Var(name string, value int32) Environment
  • func (e Environment) Int64Var(name string, value int64) Environment
  • func (e Environment) Int8Var(name string, value int8) Environment
  • func (e Environment) IntVar(name string, value int) Environment
  • func (e Environment) LogLevelVar(name string, l log.Level) Environment
  • func (e Environment) StringVar(name, value string) Environment
  • func (e Environment) Uint16Var(name string, value uint16) Environment
  • func (e Environment) Uint32Var(name string, value uint32) Environment
  • func (e Environment) Uint64Var(name string, value uint64) Environment
  • func (e Environment) Uint8Var(name string, value uint8) Environment
  • func (e Environment) UintVar(name string, value uint) Environment
  • func (e Environment) Var(name string, vfn func(c ContainerInfo) string) Environment
• type Group
  • func NewGroup(name string, apps ...*Application) (Group, error)
  • func NewGroupWithClient(cli *client.Client, name string, apps ...*Application) (Group, error)
• type Hook
• type HookType
• type HostConfigSpec
• type HostPort
  • func (hp *HostPort) String() string
• type Matcher
  • func NewExactMatcher(s string) Matcher
  • func NewRegexpMatcher(r *regexp.Regexp) Matcher
  • func NewSubstringMatcher(s string) Matcher
• type NetworkID
• type PortAllocator
• type PortBindings
  • func NewDirectPortBinding() *PortBindings
  • func NewPortBindings() *PortBindings
  • func NewPortBindingsWithPortAllocator(allocator PortAllocator) *PortBindings
  • func (pb *PortBindings) PortDNAT(proto Protocol, port uint16) *PortBindings
• type Protocol
  • func (p Protocol) String() string

Variables

var (
	ErrPortNotMapped             = errors.New("port not mapped")
	ErrDockerHostIPIsNotResolved = errors.New("docker host IP address cannot be resolved")
)

Functions

func DockerIP

func DockerIP() (string, error)

DockerIP returns docker node IP address for further connectivity usage

func NewHostConfig

func NewHostConfig(pb *PortBindings) (*dockerContainer.HostConfig, error)

NewHostConfig creates new HostConfig instance

func OneToOneRandomPort

func OneToOneRandomPort(proto Protocol, srcPort uint16) (string, uint16, []string, error)

func RandomPort

func RandomPort(proto Protocol, dstPort uint16) (string, uint16, []string, error)

RandomPortTCP makes a query to the kernel about free high range IP address NOTE: it have some probability impact so could fail in the really small amount of cases

Types

type Application

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

func NewApplication

func NewApplication(c Container, hooks ...Hook) *Application

type Binding

type Binding struct {
	HostIP   string
	HostPort string
}

Binding reflects a mapping part of the internal & external port of the container

type Container

type Container interface {
	AwaitOutput(ctx context.Context, m Matcher) error
	Close(ctx context.Context) error
	Name() string
	NetworkAttach(networkID string) error
	Ping(ctx context.Context) error
	Run(ctx context.Context) error
	URL(proto Protocol, port uint16) (*HostPort, error)
}

Container exposes interface to control the container runtime

func NewContainer

func NewContainer(name, image string, cmd []string, environment Environment, ports *PortBindings) (Container, error)

New creates new container instance from remote docker image

func NewContainerWithClient

func NewContainerWithClient(cli *client.Client, name, image string, cmd []string, env Environment, ports *PortBindings) (Container, error)

NewContainerWithClient creates new container from remote docker image and allows to pass custom docker.Client instance

type ContainerID

type ContainerID = string

type ContainerInfo

type ContainerInfo interface {
	GetExternalPortMapping(Protocol, uint16) (uint16, error)
	GetDockerHostIP() (string, error)
}

type Environment

type Environment map[string]func(c ContainerInfo) string

Environment represents the container environment passed into runtime

func NewEnvironment

func NewEnvironment() Environment

NewEnvironment creates new Environment instance

func (Environment) BoolVar

func (e Environment) BoolVar(name string, value bool) Environment

BoolVar sets bool var to the environment

func (Environment) Eval

func (e Environment) Eval(c ContainerInfo) (es []string)

func (Environment) Int16Var

func (e Environment) Int16Var(name string, value int16) Environment

Int16Var sets int16 var to the environment

func (Environment) Int32Var

func (e Environment) Int32Var(name string, value int32) Environment

Int32Var sets int32 var to the environment

func (Environment) Int64Var

func (e Environment) Int64Var(name string, value int64) Environment

Int64Var sets int64 var to the environment

func (Environment) Int8Var

func (e Environment) Int8Var(name string, value int8) Environment

Int8Var sets int8 var to the environment

func (Environment) IntVar

func (e Environment) IntVar(name string, value int) Environment

IntVar sets int var to the environment

func (Environment) LogLevelVar

func (e Environment) LogLevelVar(name string, l log.Level) Environment

LogLevelVar sets logrus.Level var to the environment

func (Environment) StringVar

func (e Environment) StringVar(name, value string) Environment

StringVar sets string var to the environment

func (Environment) Uint16Var

func (e Environment) Uint16Var(name string, value uint16) Environment

Uint16Var sets uint16 var to the environment

func (Environment) Uint32Var

func (e Environment) Uint32Var(name string, value uint32) Environment

Uint32Var sets uint32 var to the environment

func (Environment) Uint64Var

func (e Environment) Uint64Var(name string, value uint64) Environment

Uint64Var sets uint64 var to the environment

func (Environment) Uint8Var

func (e Environment) Uint8Var(name string, value uint8) Environment

Uint8Var sets uint8 var to the environment

func (Environment) UintVar

func (e Environment) UintVar(name string, value uint) Environment

UintVar sets uint var to the environment

func (Environment) Var

func (e Environment) Var(name string, vfn func(c ContainerInfo) string) Environment

Var allows to set custom function to generate environment variable

type Group

type Group interface {
	Run(ctx context.Context) error
	Close(ctx context.Context) error
}

func NewGroup

func NewGroup(name string, apps ...*Application) (Group, error)

func NewGroupWithClient

func NewGroupWithClient(cli *client.Client, name string, apps ...*Application) (Group, error)

type Hook

type Hook func(context.Context, HookType, Container) error

type HookType

type HookType string

const (
	HookTypeBeforeRun   HookType = "before_run"
	HookTypeAfterRun    HookType = "after_run"
	HookTypeBeforeClose HookType = "before_close"
	HookTypeAfterClose  HookType = "after_close"
)

type HostConfigSpec

type HostConfigSpec struct {
	PortBindings map[string][]Binding
}

HostConfigSpec is just a wrapper structure to pass host configuration to the container

type HostPort

type HostPort struct {
	Host string
	Port uint16
}

HostPort allows to return host & port from the URL method

func (*HostPort) String

func (hp *HostPort) String() string

String returns IP:Port pair

type Matcher

type Matcher func(l string) bool

Matcher allows to create any kind of matcher for container outputs

func NewExactMatcher

func NewExactMatcher(s string) Matcher

NewExactMatcher represents exact matcher i.e. the output should be exactly matched (except space chars around the word)

func NewRegexpMatcher

func NewRegexpMatcher(r *regexp.Regexp) Matcher

func NewSubstringMatcher

func NewSubstringMatcher(s string) Matcher

NewSubstringMatcher represents partial matcher

type NetworkID

type NetworkID = string

type PortAllocator

type PortAllocator func(proto Protocol, port uint16) (string, uint16, []string, error)

type PortBindings

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

PortBindings is a full mapping of internal & external docker container ports

func NewDirectPortBinding

func NewDirectPortBinding() *PortBindings

func NewPortBindings

func NewPortBindings() *PortBindings

NewPortBindings creates new PortBindings instance

func NewPortBindingsWithPortAllocator

func NewPortBindingsWithPortAllocator(allocator PortAllocator) *PortBindings

NewPortBindingsWithTCPPortAllocator creates new PortBinding instance and allows to pass custom port allocation function

func (*PortBindings) PortDNAT

func (pb *PortBindings) PortDNAT(proto Protocol, port uint16) *PortBindings

PortDNAT adds new port to be exposed from the container

type Protocol

type Protocol string

Protocol to be NAT'ed from the container

const (
	// ProtoTCP ...
	ProtoTCP Protocol = "tcp"

	// ProtoUDP ...
	ProtoUDP Protocol = "udp"
)

func (Protocol) String

func (p Protocol) String() string

String returns the string representation of the protocol