with

Documentation

Overview

Package with - provides various options/setups that can be used by marrow.Suite

Index

• type Image
• type ImageApi
  • func ApiImage(imageName string, tag string, port int, env map[string]any, leaveRunning bool) ImageApi
• type ImagePull
  • func PullImage(stage Stage, image string, pullOptions PullOptions, runOptions *RunOptions) ImagePull
• type ImageResolveEnv
• type PullOptions
• type RunOptions
• type Stage
• type SuiteInit
• type With
  • func ApiHost(host string, port int) With
  • func Cookie(cookie *http.Cookie) With
  • func CoverageCollector(collector coverage.Collector) With
  • func Database(name string, db *sql.DB, dbArgs common.DatabaseArgs) With
  • func DisableReaperShutdowns(disable bool) With
  • func HttpDo(httpDo common.HttpDo) With
  • func Logging(stdout io.Writer, stderr io.Writer) With
  • func Make(stage Stage, file string, timeout time.Duration, showLogs bool, args ...string) With
  • func MockService(name string) With
  • func OAS(r io.Reader) With
  • func Repeats(n int, stopOnFailure bool, resets ...func()) With
  • func ReportCoverage(fn func(coverage *coverage.Coverage)) With
  • func SetEnv(key, value string) With
  • func Testing(t *testing.T) With
  • func TraceTimings() With
  • func Var(name string, value any) With

Types

type Image

type Image interface {
	Name() string
	Host() string
	Port() string
	MappedPort() string
	IsDocker() bool
	Username() string
	Password() string
}

Image is the interface that describes a running docker image

type ImageApi

type ImageApi interface {
	With
	Image
	Container() testcontainers.Container
	IsApi() bool
}

func ApiImage

func ApiImage(imageName string, tag string, port int, env map[string]any, leaveRunning bool) ImageApi

ApiImage initialises a marrow.Suite with a docker image to run and test against

the image should be built either by the user (externally) or by using the Make

the env arg is used to build the environment vars for the docker container - each key being the name of the environment variable and the value is reduced to a string. If the value is already a string, it can contain special markers which are resolved...

Special env marker examples:

• "{$mysql:host}" - where a supporting image of "mysql" has been provided, and you want the host
• "{$mysql:port}" - where a supporting image of "mysql" has been provided, and you want the port
• "{$mysql:mport}" - where a supporting image of "mysql" has been provided, and you want the docker mapped port
• "{$mysql:username}" - where a supporting image of "mysql" has been provided, and you want the username
• "{$mysql:password}" - where a supporting image of "mysql" has been provided, and you want the password
• "{$mock:mymock:host}" - where a mock service named "mymock" has been provided, and you want the host
• "{$mock:mymock:port}" - where a mock service named "mymock" has been provided, and you want the port

multiple markers can be used in the string value - so that, you can for example, build a DSN - e.g.

"DSN": "{$mysql:username}:{$mysql:password}@tcp(host.docker.internal:{$mysql:mport})/petstore"

type ImagePull

type ImagePull interface {
	With
	Image
	Container() testcontainers.Container
}

func PullImage

func PullImage(stage Stage, image string, pullOptions PullOptions, runOptions *RunOptions) ImagePull

PullImage pulls a docker image and optional runs it

the image is only run as a container is runOptions is non-nil

The stage can be either Initial or Supporting (any other causes panic)

It is recommended that the Supporting stage is used, as these are run as goroutines prior to Final stage initializers

type ImageResolveEnv

type ImageResolveEnv interface {
	ResolveEnv(tokens ...string) (string, bool)
}

ImageResolveEnv is an additional interface that images can implement to resolve additional env settings

type PullOptions

type PullOptions struct {
	Username string
	Password string
	// ServerAddress is used to denote the private docker hub address
	//
	// if Username and Password are specified but this is left empty, it defaults to "https://index.docker.io/v1/"
	ServerAddress string
}

PullOptions is used by PullImage to supply credentials for a private docker hub

credentials are only used if the Username and Password are non-empty strings

type RunOptions

type RunOptions struct {
	Name         string
	Port         int
	Env          map[string]any
	LeaveRunning bool
}

RunOptions is used by PullImage to denote the image should be run once pulled

type Stage

type Stage int

Stage is the stage at which the With is executed during Suite initialisation

const (
	Initial    Stage = iota // for setting up e.g. vars (anything that just updates a setting in Suite)
	Supporting              // for spinning up supporting docker images (or running a Make on API image)
	Final                   // for final stage of Suite init, e.g. running the API container
)

type SuiteInit

type SuiteInit interface {
	// AddDb adds a supporting database to the marrow.Suite
	//
	// The dbName is normally the flavour of db (e.g. "mysql")
	//
	// If the tests only use one supporting database, dbName can just be ""
	//
	// see also Database
	AddDb(dbName string, db *sql.DB, dbArgs common.DatabaseArgs)
	// SetApiHost sets the host and port for the API being tested
	//
	// This can be called multiple times but only one API is used - therefore, last one wins
	//
	// see also ApiHost
	SetApiHost(host string, port int)
	// SetTesting tells the marrow.Suite to run tests in the provided go test
	//
	// If this is not set, the marrow.Suite uses its own internal test runner
	//
	// see also Testing
	SetTesting(t *testing.T)
	// SetVar sets an initial variable in the marrow.Suite which is initialised in the marrow.Context on tests run
	//
	// see also Var
	SetVar(name string, value any)
	// SetCookie sets an initial cookie in the marrow.Suite which is initialised in the marrow.Context on tests run
	//
	// see also Cookie
	SetCookie(cookie *http.Cookie)
	// SetReportCoverage provides a callback function to receive test coverage.Coverage
	//
	// if this callback is not provided, the marrow.Suite will not collect coverage information
	//
	// see also ReportCoverage
	SetReportCoverage(fn func(coverage *coverage.Coverage))
	// SetCoverageCollector sets a custom coverage collector in the marrow.Suite
	//
	// see also CoverageCollector
	SetCoverageCollector(collector coverage.Collector)
	// SetOAS sets an Open API Spec reader (json or yaml)
	//
	// When an OAS is provided, coverage can report test coverage against the spec
	//
	// see also OAS
	SetOAS(r io.Reader)
	// SetRepeats initialises a marrow.Suite with a number of repeats to run
	//
	// repeats are run after the main endpoint+method tests - and is useful for gauging response timing stats
	// in coverage for a larger number of calls
	//
	// see also Repeats
	SetRepeats(n int, stopOnFailure bool, resets ...func())
	// SetLogging initialises a marrow.Suite with log writers to use
	//
	// by default, the marrow.Suite will use os.Stdout and os.Stderr
	//
	// These log writers are not used if Testing is used
	SetLogging(stdout io.Writer, stderr io.Writer)
	// AddMockService adds a mock service for use in tests
	AddMockService(mock service.MockedService)
	// AddSupportingImage adds a supporting docker container image used by the tests
	AddSupportingImage(info Image)
	// ResolveEnv is used to resolve environment variables
	//
	// if the value passed is a string, it can contain special markers - see ApiImage
	ResolveEnv(v any) (string, error)
	// SetHttpDo sets the marrow.Suite with an override for making http calls
	//
	// by default, the marrow.Suite will ue http.DefaultClient
	//
	// see also HttpDo
	SetHttpDo(do common.HttpDo)
	// SetTraceTimings sets whether the marrow.Suite should collect trace timings within coverage
	//
	// see also TraceTimings
	SetTraceTimings(collect bool)
}

SuiteInit is the interface passed to With.Init and allows the With to set things in the marrow.Suite prior to tests run

Within one With.Init, it can make one or more calls to this interface. For example, a With that spins up a supporting database docker container might call both SuiteInit.AddSupportingImage and SuiteInit.AddDb

type With

type With interface {
	Init(init SuiteInit) error
	Stage() Stage
	Shutdown() func()
}

With is the interface that must be implemented by anything passed to Suite.Init()

func ApiHost

func ApiHost(host string, port int) With

ApiHost initialises a marrow.Suite with a currently running API

see also ApiImage for initialising a marrow.Suite with a docker image

func Cookie

func Cookie(cookie *http.Cookie) With

Cookie initialises a marrow.Suite with a pre-defined http.Cookie

Any defined cookies can be used by requests made by a method

func CoverageCollector

func CoverageCollector(collector coverage.Collector) With

CoverageCollector initialises a marrow.Suite with a custom coverage collector

func Database

func Database(name string, db *sql.DB, dbArgs common.DatabaseArgs) With

Database initialises a marrow.Suite with an existing database (*sql.DB)

The name arg is only needed when tests might use multiple different databases, otherwise an empty string is sufficient

func DisableReaperShutdowns

func DisableReaperShutdowns(disable bool) With

DisableReaperShutdowns initialises a marrow.Suite to disable/enable container auto-shutdowns (RYUK)

it sets the os env var "TESTCONTAINERS_RYUK_DISABLED"

func HttpDo

func HttpDo(httpDo common.HttpDo) With

HttpDo initialises a marrow.Suite with an override for making http calls

func Logging

func Logging(stdout io.Writer, stderr io.Writer) With

Logging initialises a marrow.Suite with log writers to use

by default, the marrow.Suite will use os.Stdout and os.Stderr

These log writers are not used if Testing is used

func Make

func Make(stage Stage, file string, timeout time.Duration, showLogs bool, args ...string) With

Make executes a make with the supplied args and targets during the Suite.Init

The stage can be either Initial or Supporting (any other causes panic)

It is recommended that the Supporting stage is used, as these are run as goroutines prior to Final stage initializers

IMPORTANT NOTE: The file arg must be an absolute path (panics if otherwise)

func MockService

func MockService(name string) With

MockService initialises a marrow.Suite with a mock http service

Many apis may call other services - MockService can be used to mock the responses as well as assert/require calls were made

func OAS

func OAS(r io.Reader) With

OAS initialises a marrow.Suite with a reader for the OAS (Open API Specification) .yaml or .json

When an OAS is provided, coverage can report test coverage against the spec

func Repeats

func Repeats(n int, stopOnFailure bool, resets ...func()) With

Repeats initialises a marrow.Suite with a number of repeats to run

repeats are run after the main endpoint+method tests - and is useful for gauging response timing stats in coverage for a larger number of calls

func ReportCoverage

func ReportCoverage(fn func(coverage *coverage.Coverage)) With

ReportCoverage initialises a marrow.Suite with a function that is called to report coverage after tests have been run

func SetEnv

func SetEnv(key, value string) With

SetEnv initialises a marrow.Suite with an environment variable set

func Testing

func Testing(t *testing.T) With

Testing initialises a marrow.Suite with a golang test

When a marrow.Suite uses a testing.T, all tests are run with t.Run and api test pass/fail is indicated by the test runner

func TraceTimings

func TraceTimings() With

TraceTimings initialises a marrow.Suite to collect full trace timings on http calls for method tests

if this is used, additional information about timings is available in coverage.Timings

func Var

func Var(name string, value any) With

Var initialises a marrow.Suite with a variable set

Variables can be used in Endpoints and Methods to assert/require against