contessa

README

Go Contessa

Library for easier testing with containers. Originally developed for testing nvim-dbee.

Only basic functionality for now - adding fetures if needed.

Quick Start

package example_test

import (
	"database/sql"
	"fmt"
	"testing"
	"time"

	"github.com/stretchr/testify/require"

	"github.com/kndndrj/go-contessa"
)

func TestExample(t *testing.T) {
	r := require.New(t)
	cm, err := contessa.New(contessa.WithTestingLogger(t))
	r.NoError(err)

	// get a free port from os
	port := contessa.GetFreePortOr(5177)

	// create a new postgres container
	ready, err := cm.StartContainer("postgres:15",
		// port binding
		contessa.WithPortBinding(port, 5432),

		// env vars
		contessa.WithEnvVariable("POSTGRES_USER", "postgres"),
		contessa.WithEnvVariable("POSTGRES_PASSWORD", "postgres"),
		contessa.WithEnvVariable("POSTGRES_DB", "postgres"),

		// startup probe and delay
		contessa.WithStartupProbe("pg_isready"),
		contessa.WithStartupProbeSkew(2*time.Second),
		contessa.WithStartupDelay(10*time.Second),
	)
	r.NoError(err)

	// Wait for the container to be set-up
	<-ready

	// connect to postgres container
	dsn := fmt.Sprintf("postgres://postgres:postgres@localhost:%d/postgres?sslmode=disable", port)
	db, err := sql.Open("pgx", dsn)
	r.NoError(err)
	defer db.Close()

	// do whatever you need with "db"...
}

Documentation

Index

• func GetFreePort() (int, error)
• func GetFreePortOr(fallback int) int
• type ContainerStartOption
  • func WithCmd(cmd ...string) ContainerStartOption
  • func WithEnvVariable(key, value string) ContainerStartOption
  • func WithPortBinding(host, container int) ContainerStartOption
  • func WithStartupDelay(delay time.Duration) ContainerStartOption
  • func WithStartupProbe(cmd ...string) ContainerStartOption
  • func WithStartupProbeSkew(t time.Duration) ContainerStartOption
• type Logger
  • func WithTestingLogger(t *testing.T) Logger
• type Manager
  • func New(logger Logger) (*Manager, error)
  • func (m *Manager) Close() error
  • func (m *Manager) StartContainer(image string, opts ...ContainerStartOption) (chan struct{}, error)

Functions

func GetFreePort

func GetFreePort() (int, error)

GetFreePort asks the kernel for a free open port that is ready to use.

taken from: github.com/phayes/freeport

func GetFreePortOr

func GetFreePortOr(fallback int) int

GetFreePortOr tries to get a free port from system kernel and returns the fallback value otherwise

Types

type ContainerStartOption

type ContainerStartOption func(*containerStartConfig)

func WithCmd

func WithCmd(cmd ...string) ContainerStartOption

WithCmd specifies the command to be used at container start

func WithEnvVariable

func WithEnvVariable(key, value string) ContainerStartOption

WithEnvVariable sets an environment variable (can be used multiple times)

func WithPortBinding

func WithPortBinding(host, container int) ContainerStartOption

WithPortBinding binds container port to host's port (can be used multiple times)

func WithStartupDelay

func WithStartupDelay(delay time.Duration) ContainerStartOption

WithStartupDelay delays the closing of the ready channel.

If used alongside startup probe command, the ready channel is closed whenever one of the conditions finishes first.

func WithStartupProbe

func WithStartupProbe(cmd ...string) ContainerStartOption

WithStartupProbe runs the provided command inside container periodically until it returns zero exit code and then closes the ready channel.

If used alongside startup delay, the ready channel is closed whenever one of the conditions finishes first.

func WithStartupProbeSkew

func WithStartupProbeSkew(t time.Duration) ContainerStartOption

WithStartupProbeSkew adds an aditional delay at the end of the startup probe operation; total delay is therefore: startup probe + skew

This has no effect on startup delay

type Logger

type Logger interface {
	Print(v ...any)
	Printf(format string, v ...any)
}

func WithTestingLogger

func WithTestingLogger(t *testing.T) Logger

WithTestingLogger adapts testing.T as a logger for Logger interface.

type Manager

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

func New

func New(logger Logger) (*Manager, error)

func (*Manager) Close

func (m *Manager) Close() error

func (*Manager) StartContainer

func (m *Manager) StartContainer(image string, opts ...ContainerStartOption) (chan struct{}, error)

StartContainer starts the specified container with provided image and options. It returns a "ready" channel, that is closed whenever the container is considered to be up. The behaviour of the readiness channel can be configured using several options.