podrick

README

Podrick

Dynamically create and destroy containers for tests, within your Go application. Support for both Podman and Docker runtimes is built-in.

Inspired by dockertest.

Usage

package some_test

import (
	"net/http"
	"testing"

	"github.com/uw-labs/podrick"
	_ "github.com/uw-labs/podrick/runtimes/docker" // Register the docker runtime.
	_ "github.com/uw-labs/podrick/runtimes/podman" // Register the podman runtime.
)

func TestDatabase(t *testing.T) {
	ctr, err := podrick.StartContainer("kennethreitz/httpbin", "latest", "80")
	if err != nil {
		t.Fatalf("Failed to start container: %v", err)
	}
	defer func() {
		err := ctr.Close() // Stops and removes the container.
		if err != nil {
			t.Error(err.Error())
		}
	}()

	// Use ctr.Address().
	resp, err = http.Get("http://" + ctr.Address() + "/get")
}

Podrick automatically selects a runtime if one isn't explicitly specified. This allows the user to use both podman and docker, depending on the support of the environment. It's also possible to explicitly specify which runtime to use, or use a custom runtime implementation.

Advanced usage

package some_test

import (
	"database/sql"
	"testing"

	"github.com/sirupsen/logrus"
	"github.com/uw-labs/podrick"
	"github.com/uw-labs/podrick/runtimes/podman"
	logrusadapter "logur.dev/adapters/logrus"
)

func TestDatabase(t *testing.T) {
	log := logrusadapter.New(logrus.New())
	ctr, err := podrick.StartContainer("cockroachdb/cockroach", "v19.1.3", "26257",
		podrick.WithUlimit([]podrick.Ulimit{{
			Name: "nofile",
			Soft: 1956,
			Hard: 1956,
		}}),
		podrick.WithCmd([]string{
			"start",
			"--insecure",
		}),
        podrick.WithLogger(log),
        // Use of the podman runtime only.
        // The environment variable PODMAN_VARLINK_ADDRESS
        // can be used to configure where podrick should
        // look for the varlink API.
		podrick.WithRuntime(&podman.Runtime{
			Logger: log,
		}),
		podrick.WithLivenessCheck(func(address string) error {
			_, err := http.Get("http://"+address+"/get")
			return err
		}),
	)
	if err != nil {
		t.Fatal(err.Error())
	}
	defer func() {
		err := ctr.Close()
		if err != nil {
			t.Error(err.Error())
		}
	}()

	db, err := sql.Open("postgres://root@" + ctr.Address() + "/defaultdb")
	// ... make database calls, etc
}

Using podrick in CI

While podrick makes it really easy to run tests locally on users machines, it can be challenging to run the tests in CI, since it requires the permission to run containers that are accessible to the local environment. Circle CI is the only environment confirmed to work well with podrick, both using podman and docker.

Circle CI

The podrick CI tests themselves illustrate how to use podrick with Circle CI. It requires the use of the machine executor type, and there is some setup required to get a recent Go version. Please see the CI files for concrete examples of this.

If you are using Circle CI with the docker runtime, it is obviously not necessary to install podman.

Documentation

Index

• func RegisterAutoRuntime(r Runtime)
• func WithCmd(in []string) func(*config)
• func WithEntrypoint(in string) func(*config)
• func WithEnv(in []string) func(*config)
• func WithLivenessCheck(lc LivenessCheck) func(*config)
• func WithLogger(in Logger) func(*config)
• func WithRuntime(in Runtime) func(*config)
• func WithUlimit(in []Ulimit) func(*config)
• type Container
  • func StartContainer(ctx context.Context, repo, tag, port string, opts ...func(*config)) (_ Container, err error)
• type ContainerConfig
• type LivenessCheck
• type Logger
• type Runtime
• type Ulimit

Functions

func RegisterAutoRuntime

func RegisterAutoRuntime(r Runtime)

RegisterAutoRuntime allows a runtime to register itself for auto-selection of a runtime, when one isn't explicitly specified.

func WithCmd

func WithCmd(in []string) func(*config)

WithCmd configures the command of the container.

func WithEntrypoint

func WithEntrypoint(in string) func(*config)

WithEntrypoint configures the entrypoint of the container.

func WithEnv

func WithEnv(in []string) func(*config)

WithEnv configures the environment of the container.

func WithLivenessCheck

func WithLivenessCheck(lc LivenessCheck) func(*config)

WithLivenessCheck defines a function to call repeatedly until it does not error, to ascertain the successful startup of the container. The function will be retried for 10 seconds, and if it does not return a non-nil error before that time, the last error will be returned.

func WithLogger

func WithLogger(in Logger) func(*config)

WithLogger configures the logger of the container. The containers logs will be logged at Info level to this logger. Some errors during closing may also be logged at Error level.

func WithRuntime

func WithRuntime(in Runtime) func(*config)

WithRuntime configures the Runtime to use to launch the container. By default, the auto runtime is used.

func WithUlimit

func WithUlimit(in []Ulimit) func(*config)

WithUlimit configures the ulimits of the container.

Types

type Container

type Container interface {
	// Context releases resources associated with the container.
	Close(context.Context) error
	// Address contains the IP and port of the running container.
	Address() string
	// StreamLogs asynchronously streams logs from the
	// running container to the writer. The writer must
	// be safe for concurrent use.
	// If the context is cancelled after logging has been set up,
	// it has no effect. Use Close to stop logging.
	// This function is called automatically on the runtimes
	// configured logger, so there is no need to explicitly call this.
	StreamLogs(context.Context, io.Writer) error
}

Container represents a running container.

func StartContainer

func StartContainer(ctx context.Context, repo, tag, port string, opts ...func(*config)) (_ Container, err error)

StartContainer starts a container using the configured runtime. By default, a runtime is chosen automatically from those registered.

type ContainerConfig

type ContainerConfig struct {
	Repo string
	Tag  string
	Port string

	// Optional
	Env        []string
	Entrypoint *string
	Cmd        []string
	Ulimits    []Ulimit
}

ContainerConfig is used by runtimes to start containers.

type LivenessCheck

type LivenessCheck func(address string) error

LivenessCheck is a type used to check the successful startup of a container.

type Logger

type Logger interface {
	Trace(msg string, fields ...map[string]interface{})
	Debug(msg string, fields ...map[string]interface{})
	Info(msg string, fields ...map[string]interface{})
	Warn(msg string, fields ...map[string]interface{})
	Error(msg string, fields ...map[string]interface{})
}

Logger must be implemented to log events. See https://logur.dev/logur for some adapters for popular logging libraries.

type Runtime

type Runtime interface {
	Close(context.Context) error
	Connect(context.Context) error
	StartContainer(context.Context, *ContainerConfig) (Container, error)
}

Runtime supports starting containers.

type Ulimit

type Ulimit struct {
	Name string
	Soft int64
	Hard int64
}

Ulimit describes a container ulimit.