gnomock

package module
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 19, 2020 License: MIT Imports: 17 Imported by: 27

README

Gnomock – test your code without mocks

🏗️ Spin up entire dependency stack

🎁 Setup initial dependency state – easily!

🏭 Test against actual, close to production software

⏳ Spend no time writing mocks

🕹️ Test actual program behavior and side effects

Build Go Report Card

Gnomock is an integration and end-to-end testing toolkit. It uses Docker to create temporary containers for application dependencies, setup their initial state and clean them up in the end. Gnomock allows to test the code with no mocks wherever possible.

The power of Gnomock is in a variety of Presets, each implementing a specific database, service or other tools. Each preset provides ways of setting up its initial state as easily as possible: SQL schema creation, test data upload into S3, sending test events to Splunk, etc.

The name "Gnomock" stands for "no mock", with a "G" for "Go" 😼. It also sounds like "gnome", that's why the friendly garden gnome artwork (by Michael Zolotov)

Table of contents

Getting started

Gnomock runs exposes an API over HTTP. This API is defined using OpenAPI 3.0 specification. Go programs can use an extended Gnomock package directly, without the HTTP layer, while other languages require communication with a Gnomock server.

Gnomock requires a running and working Docker daemon running locally in the same environment.

Using Gnomock in Go applications

Gnomock can be used in Go programs directly, without running a local server. See the following example to get started:

go get github.com/orlangure/gnomock

Setting up a Postgres container with schema setup example:

import (
	"database/sql"

	_ "github.com/lib/pq" // postgres driver
	"github.com/orlangure/gnomock"
	"github.com/orlangure/gnomock/preset/postgres"
)

p := postgres.Preset(
    postgres.WithUser("gnomock", "gnomick"),
    postgres.WithDatabase("mydb"),
    postgres.WithQueriesFile("/var/project/db/schema.sql"),
)
container, _ := gnomock.Start(p)
defer func() { _ = gnomock.Stop(container) }()

connStr := fmt.Sprintf(
    "host=%s port=%d user=%s password=%s  dbname=%s sslmode=disable",
    container.Host, container.DefaultPort(),
    "gnomock", "gnomick", "mydb",
)
db, _ := sql.Open("postgres", connStr)
// db has the required schema and data, and is ready to use

See package reference. For Preset documentation, refer to Presets section.

Using Gnomock server

To start a gnomock server, run the following on any Unix-based system:

docker run --rm \
    -p 23042:23042 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v `pwd`:`pwd` \
    orlangure/gnomock

-p 23042:23042 exposes a port on the host to communicate with gnomock. You can use any port you like, just make sure to configure the client properly.

-v /var/run/docker.sock:/var/run/docker.sock allows gnomock to communicate with the docker engine running on host. Without it gnomock can't access docker.

If you use any file-related gnomock options, like WithQueriesFile, you have to make the path you use available inside the container:

# this makes the current folder appear inside the container under the same
# path and name:
-v `pwd`:`pwd`

Any program in any language can communicate with gnomock server using OpenAPI 3.0 specification.

Below is an example of setting up a MySQL container using a POST request:

$ cat mysql-preset.json
{
  "preset": {
    "db": "mydb",
    "user": "gnomock",
    "password": "p@s$w0rD",
    "queries": [
      "create table foo(bar int)",
      "insert into foo(bar) values(1)"
    ],
    "queries_file": "/home/gnomock/project/testdata/mysql/queries.sql"
  },
  "options": {}
}

$ curl --data @mysql-preset.json http://127.0.0.1:23042/start/mysql
{
  "id": "f5d08dc84421",
  "host": "string",
  "ports": {
    "default": {
      "protocol": "tcp",
      "port": 35973
    }
  }
}

There are auto-generated wrappers for the available API:

Client Sample code
Python SDK Code
JavaScript SDK
PHP SDK
Ruby SDK
PHP SDK
Java SDK
Other languages

For more details and a full specification, see documentation.

Installation instruction, as well as pre-compiled binaries for MacOS and Linux, are coming soon.

Official presets

The power of Gnomock is in the Presets. Presets, both existing and planned, are listed below:

Preset Go package HTTP API Go API
Localstack Go package Docs Reference
Splunk Go package Docs Reference
Redis Go package Docs Reference
MySQL Go package Docs Reference
PostgreSQL Go package Docs Reference
Microsoft SQL Server Go package Docs Reference
MongoDB Go package Docs Reference
Elasticsearch
DynamoDB
Cassandra
MariaDB

It is possible to use Gnomock directly from Go code without any presets. HTTP API only allows to setup containers using presets that exist in this repository.

Troubleshooting

Tests with Gnomock take too long and time-out eventually

It happens a lot locally if your internet isn't fast enough to pull docker images used in tests. In CI, such as in Github Actions, the images are downloaded very quickly. To work around this issue locally, pull the image manually before running the tests. You only need to do it once, the images stay in local cache until deleted. For example, to pull Postgres 11 image, run:

docker pull postgres:11
Tests time-out even when the image exists locally

It can happen if the containers can't become ready to use before they time out. By default, Gnomock uses fairly high timeouts for new containers (for starting and for setting them up). If you choose to change default timeout using WithTimeout (timeout in HTTP), it is possible that the values you choose are too short.

Tests pass when run one-by-one, and fail when run in parallel

It happens when you try to start up a lot of containers at the same time. The system, especially in CI environments such as Github Actions, cannot handle the load, and containers fail to become healthy before they time-out. That's the reason Gnomock has a few separate build jobs, each running only a small subset of tests, one package at a time.

Containers fail to setup with a "File not found" error

If you run gnomock as a server, you need to make sure the files you use in your setup are available inside gnomock container. Use -v $(pwd):$(pwd) argument to docker run to mount the current working directory under the same path inside the gnomock container. If you prefer to keep a permanent gnomock container running, you can mount your entire $HOME directory (or any other directory where you keep the code).

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

Constants

View Source
const DefaultPort = "default"

DefaultPort should be used with simple containers that expose only one TCP port. Use DefaultTCP function when creating a container, and use DefaultPort when calling Address()

Variables

View Source
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

View Source
var ErrPortNotFound = errors.New("port not found")

ErrPortNotFound means that a port with the requested name was not found in the created container. Make sure that the name used in Find method matches the name used in in NamedPorts. For default values, use DefaultTCP and DefaultPort

Functions

func Stop

func Stop(cs ...*Container) error

Stop stops the provided container and lets docker remove them from the system. Stop returns an error if any one of the containers couldn't stop

Types

type Container

type Container struct {
	// Container ID as set by docker
	ID string `json:"id,omitempty"`

	// Host name of bound ports
	//
	// Default: localhost
	Host string `json:"host,omitempty"`

	// A collections of ports exposed by this container. Each port has an alias
	// and an actual port number as exposed on the host
	Ports NamedPorts `json:"ports,omitempty"`
	// contains filtered or unexported fields
}

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

func Start

func Start(p Preset, opts ...Option) (*Container, error)

Start creates a container using the provided Preset. The Preset provides its own Options to configure Gnomock container. Usually this is enough, but it is still possible to extend/override Preset options with new values. For example, wait timeout defined in the Preset, if at all, might be not enough for this particular usage, so it can't be changed during this call.

All provided Options are applied. First, Preset options are applied. Then, custom Options. If both Preset and custom Options change the same configuration, custom Options are used

func StartCustom added in v0.3.0

func StartCustom(image string, ports NamedPorts, opts ...Option) (c *Container, err error)

StartCustom creates a new container using provided image and binds random ports on the host to the provided ports 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 (*Container) Address

func (c *Container) Address(name string) string

Address is a convenience function that returns host:port that can be used to connect to this container. If a container was created with DefaultTCP call, use DefaultPort as the name. Otherwise, use the name of one of the ports used during setup

func (*Container) DefaultAddress added in v0.3.0

func (c *Container) DefaultAddress() string

DefaultAddress return Address() with DefaultPort

func (*Container) DefaultPort added in v0.3.0

func (c *Container) DefaultPort() int

DefaultPort returns Port() with DefaultPort

func (*Container) Port

func (c *Container) Port(name string) int

Port is a convenience function that returns port number with the provided name

type HealthcheckFunc

type HealthcheckFunc func(context.Context, *Container) 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(context.Context, *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 NamedPorts added in v0.1.0

type NamedPorts map[string]Port

NamedPorts is a collection of ports exposed by a container, where every exposed port is given a name. Some examples of names are "web" or "api" for a container that exposes two separate ports: one for web access and another for API calls

func DefaultTCP added in v0.1.0

func DefaultTCP(port int) NamedPorts

DefaultTCP is a utility function to use with simple containers exposing a single TCP port. Use it to create default named port for the provided port number. Pass DefaultPort to Address() method to get the address of the default port

func (NamedPorts) Find added in v0.1.0

func (p NamedPorts) Find(proto string, portNum int) (string, error)

Find returns the name of a port with the provided protocol and number. Use this method to find out the name of an exposed ports, when port number and protocol are known

func (NamedPorts) Get added in v0.1.0

func (p NamedPorts) Get(name string) Port

Get returns a port with the provided name. An empty value is returned if there are no ports with the given name

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 WithDebugMode added in v0.9.0

func WithDebugMode() Option

WithDebugMode allows Gnomock to output internal messages for debug purposes. Containers created in debug mode will not be automatically removed on failure to setup their initial state. Containers still might be removed if they are shut down from the inside. Use WithLogWriter to see what happens inside.

func WithEnv added in v0.1.1

func WithEnv(env string) Option

WithEnv adds environment variable to the container. For example, AWS_ACCESS_KEY_ID=FOOBARBAZ

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 WithLogWriter added in v0.2.1

func WithLogWriter(w io.Writer) Option

WithLogWriter sets the target where to write container logs. This can be useful for debugging

func WithOptions added in v0.4.0

func WithOptions(options *Options) Option

WithOptions allows to provide an existing set of Options instead of using optional configuration.

This way has its own limitations. For example, context or initialization functions cannot be set in this way

func WithTimeout added in v0.9.0

func WithTimeout(t time.Duration) Option

WithTimeout sets the amount of time to wait for a created container to become ready to use. All startup steps must complete before they time out: start, wait until healthy, init.

type Options added in v0.4.0

type Options struct {
	// Timeout is an amount of time to wait before considering Start operation
	// as failed.
	Timeout time.Duration `json:"timeout"`

	// Env is a list of environment variable to inject into the container. Each
	// entry is in format ENV_VAR_NAME=value
	Env []string `json:"env"`

	// Debug flag allows Gnomock to be verbose about steps it takes
	Debug bool `json:"debug"`
	// contains filtered or unexported fields
}

Options includes Gnomock startup configuration. Functional options (WithSomething) should be used instead of directly initializing objects of this type whenever possible

type Parallel added in v0.3.0

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

Parallel is a builder object that configures parallel preset execution

func InParallel added in v0.3.0

func InParallel() *Parallel

InParallel begins parallel preset execution setup. Use Start to add more presets with their configuration to parallel execution, and Go() in the end to kick-off everything

func (*Parallel) Go added in v0.3.0

func (b *Parallel) Go() ([]*Container, error)

Go kicks-off parallel preset execution. Returned containers are in the same order as they were added with Start. An error is returned if any of the containers failed to start and become available. Even if Go() returns an errors, there still might be containers created in the process, and it is callers responsibility to Stop them

func (*Parallel) Start added in v0.3.0

func (b *Parallel) Start(p Preset, opts ...Option) *Parallel

Start adds the provided preset with its configuration to the parallel execution kicked-off by Go(), together with other added presets

type Port added in v0.1.0

type Port struct {
	// Protocol of the exposed port (TCP/UDP)
	Protocol string `json:"protocol"`

	// Port number of the exposed port
	Port int `json:"port"`
}

Port is a combination of port number and protocol that are exposed in a container

func TCP added in v0.1.0

func TCP(port int) Port

TCP returns a Port with the provided number and "tcp" protocol. This is a utility function, it is equivalent to creating a Port explicitly

type Preset

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

	// Ports returns a group of ports exposed by this Preset, where every port
	// is given a unique name. For example, if a container exposes API endpoint
	// on port 8080, and web interface on port 80, there should be two named
	// ports: "web" and "api"
	Ports() NamedPorts

	// 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 ports 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

Directories

Path Synopsis
cmd
cleaner Module
Package errors exposes errors types used by gnomockd endpoints
Package errors exposes errors types used by gnomockd endpoints
Package gnomockd is an HTTP wrapper around Gnomock
Package gnomockd is an HTTP wrapper around Gnomock
Package preset provides access to existing presets
Package preset provides access to existing presets
localstack
Package localstack provides a Gnomock Preset for localstack project (https://github.com/localstack/localstack).
Package localstack provides a Gnomock Preset for localstack project (https://github.com/localstack/localstack).
mongo
Package mongo includes mongo implementation of Gnomock Preset interface.
Package mongo includes mongo implementation of Gnomock Preset interface.
mssql
Package mssql provides a Gnomock Preset for Microsoft SQL Server database
Package mssql provides a Gnomock Preset for Microsoft SQL Server database
mysql
Package mysql provides a Gnomock Preset for MySQL database
Package mysql provides a Gnomock Preset for MySQL database
postgres
Package postgres provides a Gnomock Preset for PostgreSQL database
Package postgres provides a Gnomock Preset for PostgreSQL database
redis
Package redis includes Redis implementation of Gnomock Preset interface.
Package redis includes Redis implementation of Gnomock Preset interface.
splunk
Package splunk includes Splunk Enterprise implementation of Gnomock Preset interface.
Package splunk includes Splunk Enterprise implementation of Gnomock Preset interface.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL