gnomock

README

Gnomock

Gnomock is a framework to set up temporary docker containers for integration and end-to-end testing of other applications. It handles pulling images, starting containers, waiting for them to become available, setting up their initial state and cleaning up in the end.

It can be used either directly, or via already existing implementations of various connectors built by the community.

This project is WIP

Documentation

Overview

Package gnomock contains a framework to set up temporary docker containers for integration and end-to-end testing of other applications. It handles pulling images, starting containers, waiting for them to become available, setting up their initial state and cleaning up in the end.

It can be used either directly, or via already existing implementations of various connectors built by the community.

Index

• Variables
• func Stop(c *Container) error
• type Container
  • func Start(image string, port int, opts ...Option) (c *Container, err error)
  • func StartPreset(p Preset) (c *Container, err error)
  • func (c *Container) Address() string
• type HealthcheckFunc
• type InitFunc
• type Option
  • func WithContext(ctx context.Context) Option
  • func WithHealthCheck(f HealthcheckFunc) Option
  • func WithHealthCheckInterval(t time.Duration) Option
  • func WithInit(f InitFunc) Option
  • func WithStartTimeout(t time.Duration) Option
  • func WithWaitTimeout(t time.Duration) Option
• type Preset

Variables

var ErrEnvClient = fmt.Errorf("can't connect to docker host")

ErrEnvClient means that Gnomock can't connect to docker daemon in the testing environment. See https://docs.docker.com/compose/reference/overview/ for information on required configuration

Functions

func Stop

func Stop(c *Container) error

Stop stops this container and lets docker to remove it from the system

Types

type Container

type Container struct {
	ID   string
	Host string
	Port string
}

Container represents a docker container created for testing. Host and Port fields should be used to configure the connection to this container. ID matches the original docker container ID

func Start

func Start(image string, port int, opts ...Option) (c *Container, err error)

Start creates a new container using provided image and binds a random port on the host to the provided port inside the container. Image may include tag, which is set to "latest" by default. Optional configuration is available through Option functions. The returned container must be stopped when no longer needed using its Stop() method

func StartPreset

func StartPreset(p Preset) (c *Container, err error)

StartPreset creates a container using the provided Preset. For more information, see Start

func (*Container) Address

func (c *Container) Address() string

Address is a convenience function that returns host:port that can be used to connect to this container

type HealthcheckFunc

type HealthcheckFunc func(string, string) error

HealthcheckFunc defines a function to be used to determine container health. It receives a host and a port, and returns an error if the container is not ready, or nil when the container can be used. One example of HealthcheckFunc would be an attempt to establish the same connection to the container that the application under test uses

type InitFunc

type InitFunc func(*Container) error

InitFunc defines a function to be called on a ready to use container to set up its initial state before running the tests. For example, InitFunc can take care of creating a SQL table and inserting test data into it

type Option

type Option func(*options)

Option is an optional Gnomock configuration. Functions implementing this signature may be combined to configure Gnomock containers for different use cases

func WithContext

func WithContext(ctx context.Context) Option

WithContext sets the provided context to be used for setting up a Gnomock container. Canceling this context will cause Start() to abort

func WithHealthCheck

func WithHealthCheck(f HealthcheckFunc) Option

WithHealthCheck allows to define a rule to consider a Gnomock container ready to use. For example, it can attempt to connect to this container, and return an error on any failure, or nil on success. This function is called repeatedly until the timeout is reached, or until a nil error is returned

func WithHealthCheckInterval

func WithHealthCheckInterval(t time.Duration) Option

WithHealthCheckInterval defines an interval between two consecutive health check calls. This is a constant interval

func WithInit

func WithInit(f InitFunc) Option

WithInit lets the provided InitFunc to be called when a Gnomock container is created, but before Start() returns. Use this function to run arbitrary code on the new container before using it. It can be useful to bring the container to a certain state (e.g create SQL schema)

func WithStartTimeout

func WithStartTimeout(t time.Duration) Option

WithStartTimeout sets the amount of time to wait for a new Gnomock container to start. This includes pulling an image and creating a new container from it. To set the amount of time to wait before a created container healthy and ready to use, use WithWaitTimeout

func WithWaitTimeout

func WithWaitTimeout(t time.Duration) Option

WithWaitTimeout sets the amount of time to wait for a created container to become ready to use. If health check function does not return nil error until this timeout is reached, Start() fails

type Preset

type Preset interface {
	// Image returns a canonical docker image used to setup this Preset
	Image() string

	// Port returns a port number used by the container created with this
	// Preset
	Port() int

	// Options returns a list of Option functions that allow to setup this
	// Preset implementation
	Options() []Option
}

Preset is a type that includes ready to use Gnomock configuration. Such configuration includes image and port as well as options specific to this implementation. For example, well known services like Redis or Postgres may have Gnomock implementations, providing healthcheck functions and basic initialization options