package wait

import "github.com/testcontainers/testcontainers-go/wait"

Index

Examples

Functions

func ForSQL 

func ForSQL(port nat.Port, driver string, url func(host string, port nat.Port) string) *waitForSql

ForSQL constructs a new waitForSql strategy for the given driver

Types

type ExecStrategy 

type ExecStrategy struct {

	// additional properties
	ExitCodeMatcher func(exitCode int) bool
	ResponseMatcher func(body io.Reader) bool
	PollInterval    time.Duration
	// contains filtered or unexported fields
}
Example

Code: 

{
	ctx := context.Background()
	req := testcontainers.ContainerRequest{
		Image:      "alpine:latest",
		Entrypoint: []string{"tail", "-f", "/dev/null"}, // needed for the container to stay alive
		WaitingFor: wait.ForExec([]string{"ls", "/"}).WithStartupTimeout(1 * time.Second),
	}

	ctr, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	defer func() {
		if err := testcontainers.TerminateContainer(ctr); err != nil {
			log.Printf("failed to terminate container: %s", err)
		}
	}()
	if err != nil {
		log.Printf("failed to start container: %s", err)
		return
	}

	state, err := ctr.State(ctx)
	if err != nil {
		log.Printf("failed to get container state: %s", err)
		return
	}

	fmt.Println(state.Running)

	// Output:
	// true
}

Output:

true

func ForExec 

func ForExec(cmd []string) *ExecStrategy

ForExec is a convenience method to assign ExecStrategy

func NewExecStrategy 

func NewExecStrategy(cmd []string) *ExecStrategy

NewExecStrategy constructs an Exec strategy ...

func (*ExecStrategy) Timeout 

func (ws *ExecStrategy) Timeout() *time.Duration

func (*ExecStrategy) WaitUntilReady 

func (ws *ExecStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

func (*ExecStrategy) WithExitCode 

func (ws *ExecStrategy) WithExitCode(exitCode int) *ExecStrategy

func (*ExecStrategy) WithExitCodeMatcher 

func (ws *ExecStrategy) WithExitCodeMatcher(exitCodeMatcher func(exitCode int) bool) *ExecStrategy

func (*ExecStrategy) WithPollInterval 

func (ws *ExecStrategy) WithPollInterval(pollInterval time.Duration) *ExecStrategy

WithPollInterval can be used to override the default polling interval of 100 milliseconds

func (*ExecStrategy) WithResponseMatcher 

func (ws *ExecStrategy) WithResponseMatcher(matcher func(body io.Reader) bool) *ExecStrategy

func (*ExecStrategy) WithStartupTimeout 

func (ws *ExecStrategy) WithStartupTimeout(startupTimeout time.Duration) *ExecStrategy

WithStartupTimeout can be used to change the default startup timeout

type ExitStrategy 

type ExitStrategy struct {

	// additional properties
	PollInterval time.Duration
	// contains filtered or unexported fields
}

ExitStrategy will wait until container exit

func ForExit 

func ForExit() *ExitStrategy

ForExit is the default construction for the fluid interface.

For Example: 

wait.
	ForExit().
	WithPollInterval(1 * time.Second)

func NewExitStrategy 

func NewExitStrategy() *ExitStrategy

NewExitStrategy constructs with polling interval of 100 milliseconds without timeout by default

func (*ExitStrategy) Timeout 

func (ws *ExitStrategy) Timeout() *time.Duration

func (*ExitStrategy) WaitUntilReady 

func (ws *ExitStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

WaitUntilReady implements Strategy.WaitUntilReady

func (*ExitStrategy) WithExitTimeout 

func (ws *ExitStrategy) WithExitTimeout(exitTimeout time.Duration) *ExitStrategy

WithExitTimeout can be used to change the default exit timeout

func (*ExitStrategy) WithPollInterval 

func (ws *ExitStrategy) WithPollInterval(pollInterval time.Duration) *ExitStrategy

WithPollInterval can be used to override the default polling interval of 100 milliseconds

type FileStrategy 

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

FileStrategy waits for a file to exist in the container.

func ForFile 

func ForFile(file string) *FileStrategy

ForFile is a convenience method to assign FileStrategy

func NewFileStrategy 

func NewFileStrategy(file string) *FileStrategy

NewFileStrategy constructs an FileStrategy strategy.

func (*FileStrategy) Timeout 

func (ws *FileStrategy) Timeout() *time.Duration

Timeout returns the timeout for the strategy

func (*FileStrategy) WaitUntilReady 

func (ws *FileStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

WaitUntilReady waits until the file exists in the container and copies it to the target.

func (*FileStrategy) WithMatcher 

func (ws *FileStrategy) WithMatcher(matcher func(io.Reader) error) *FileStrategy

WithMatcher can be used to consume the file content. The matcher can return an errdefs.ErrNotFound to indicate that the file is not ready. Any other error will be considered a failure. Default: nil, will only wait for the file to exist.

func (*FileStrategy) WithPollInterval 

func (ws *FileStrategy) WithPollInterval(pollInterval time.Duration) *FileStrategy

WithPollInterval can be used to override the default polling interval of 100 milliseconds

func (*FileStrategy) WithStartupTimeout 

func (ws *FileStrategy) WithStartupTimeout(startupTimeout time.Duration) *FileStrategy

WithStartupTimeout can be used to change the default startup timeout

type HTTPStrategy 

type HTTPStrategy struct {

	// additional properties
	Port                   nat.Port
	Path                   string
	StatusCodeMatcher      func(status int) bool
	ResponseMatcher        func(body io.Reader) bool
	UseTLS                 bool
	AllowInsecure          bool
	TLSConfig              *tls.Config // TLS config for HTTPS
	Method                 string      // http method
	Body                   io.Reader   // http request body
	Headers                map[string]string
	ResponseHeadersMatcher func(headers http.Header) bool
	PollInterval           time.Duration
	UserInfo               *url.Userinfo
	ForceIPv4LocalHost     bool
	// contains filtered or unexported fields
}
Example

https://github.com/testcontainers/testcontainers-go/issues/183

Code: 

{
	// waitForHTTPWithDefaultPort {
	ctx := context.Background()
	req := testcontainers.ContainerRequest{
		Image:        "nginx:latest",
		ExposedPorts: []string{"80/tcp"},
		WaitingFor:   wait.ForHTTP("/").WithStartupTimeout(10 * time.Second),
	}

	c, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	defer func() {
		if err := testcontainers.TerminateContainer(c); err != nil {
			log.Printf("failed to terminate container: %s", err)
		}
	}()
	if err != nil {
		log.Printf("failed to start container: %s", err)
		return
	}
	// }

	state, err := c.State(ctx)
	if err != nil {
		log.Printf("failed to get container state: %s", err)
		return
	}

	fmt.Println(state.Running)

	// Output:
	// true
}

Output:

true

func ForHTTP 

func ForHTTP(path string) *HTTPStrategy

ForHTTP is a convenience method similar to Wait.java https://github.com/testcontainers/testcontainers-java/blob/1d85a3834bd937f80aad3a4cec249c027f31aeb4/core/src/main/java/org/testcontainers/containers/wait/strategy/Wait.java

func NewHTTPStrategy 

func NewHTTPStrategy(path string) *HTTPStrategy

NewHTTPStrategy constructs a HTTP strategy waiting on port 80 and status code 200

func (*HTTPStrategy) Timeout 

func (ws *HTTPStrategy) Timeout() *time.Duration

func (*HTTPStrategy) WaitUntilReady 

func (ws *HTTPStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

WaitUntilReady implements Strategy.WaitUntilReady

func (*HTTPStrategy) WithAllowInsecure 

func (ws *HTTPStrategy) WithAllowInsecure(allowInsecure bool) *HTTPStrategy

func (*HTTPStrategy) WithBasicAuth 

func (ws *HTTPStrategy) WithBasicAuth(username, password string) *HTTPStrategy
Example

Code: 

{
	// waitForBasicAuth {
	ctx := context.Background()
	req := testcontainers.ContainerRequest{
		Image:        "gogs/gogs:0.11.91",
		ExposedPorts: []string{"3000/tcp"},
		WaitingFor:   wait.ForHTTP("/").WithBasicAuth("username", "password"),
	}

	gogs, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	defer func() {
		if err := testcontainers.TerminateContainer(gogs); err != nil {
			log.Printf("failed to terminate container: %s", err)
		}
	}()
	if err != nil {
		log.Printf("failed to start container: %s", err)
		return
	}
	// }

	state, err := gogs.State(ctx)
	if err != nil {
		log.Printf("failed to get container state: %s", err)
		return
	}

	fmt.Println(state.Running)

	// Output:
	// true
}

Output:

true

func (*HTTPStrategy) WithBody 

func (ws *HTTPStrategy) WithBody(reqdata io.Reader) *HTTPStrategy

func (*HTTPStrategy) WithForcedIPv4LocalHost 

func (ws *HTTPStrategy) WithForcedIPv4LocalHost() *HTTPStrategy

WithForcedIPv4LocalHost forces usage of localhost to be ipv4 127.0.0.1 to avoid ipv6 docker bugs https://github.com/moby/moby/issues/42442 https://github.com/moby/moby/issues/42375

Example

Code: 

{
	ctx := context.Background()
	req := testcontainers.ContainerRequest{
		Image:        "nginx:latest",
		ExposedPorts: []string{"8080/tcp", "80/tcp"},
		WaitingFor:   wait.ForHTTP("/").WithForcedIPv4LocalHost(),
	}

	c, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	defer func() {
		if err := testcontainers.TerminateContainer(c); err != nil {
			log.Printf("failed to terminate container: %s", err)
		}
	}()
	if err != nil {
		log.Printf("failed to start container: %s", err)
		return
	}

	state, err := c.State(ctx)
	if err != nil {
		log.Printf("failed to get container state: %s", err)
		return
	}

	fmt.Println(state.Running)

	// Output:
	// true
}

Output:

true

func (*HTTPStrategy) WithHeaders 

func (ws *HTTPStrategy) WithHeaders(headers map[string]string) *HTTPStrategy
Example

Code: 

{
	capath := filepath.Join("testdata", "root.pem")
	cafile, err := os.ReadFile(capath)
	if err != nil {
		log.Printf("can't load ca file: %v", err)
		return
	}

	certpool := x509.NewCertPool()
	if !certpool.AppendCertsFromPEM(cafile) {
		log.Printf("the ca file isn't valid")
		return
	}

	ctx := context.Background()

	// waitForHTTPHeaders {
	tlsconfig := &tls.Config{RootCAs: certpool, ServerName: "testcontainer.go.test"}
	req := testcontainers.ContainerRequest{
		FromDockerfile: testcontainers.FromDockerfile{
			Context: "testdata",
		},
		ExposedPorts: []string{"6443/tcp"},
		WaitingFor: wait.ForHTTP("/headers").
			WithTLS(true, tlsconfig).
			WithPort("6443/tcp").
			WithHeaders(map[string]string{"X-request-header": "value"}).
			WithResponseHeadersMatcher(func(headers http.Header) bool {
				return headers.Get("X-response-header") == "value"
			},
			),
	}
	// }

	c, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	defer func() {
		if err := testcontainers.TerminateContainer(c); err != nil {
			log.Printf("failed to terminate container: %s", err)
		}
	}()
	if err != nil {
		log.Printf("failed to start container: %s", err)
		return
	}

	state, err := c.State(ctx)
	if err != nil {
		log.Printf("failed to get container state: %s", err)
		return
	}

	fmt.Println(state.Running)

	// Output:
	// true
}

Output:

true

func (*HTTPStrategy) WithMethod 

func (ws *HTTPStrategy) WithMethod(method string) *HTTPStrategy

func (*HTTPStrategy) WithPollInterval 

func (ws *HTTPStrategy) WithPollInterval(pollInterval time.Duration) *HTTPStrategy

WithPollInterval can be used to override the default polling interval of 100 milliseconds

func (*HTTPStrategy) WithPort 

func (ws *HTTPStrategy) WithPort(port nat.Port) *HTTPStrategy

WithPort set the port to wait for. Default is the lowest numbered port.

Example

Code: 

{
	// waitForHTTPWithPort {
	ctx := context.Background()
	req := testcontainers.ContainerRequest{
		Image:        "nginx:latest",
		ExposedPorts: []string{"8080/tcp", "80/tcp"},
		WaitingFor:   wait.ForHTTP("/").WithPort("80/tcp"),
	}

	c, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
		ContainerRequest: req,
		Started:          true,
	})
	defer func() {
		if err := testcontainers.TerminateContainer(c); err != nil {
			log.Printf("failed to terminate container: %s", err)
		}
	}()
	if err != nil {
		log.Printf("failed to start container: %s", err)
		return
	}
	// }

	state, err := c.State(ctx)
	if err != nil {
		log.Printf("failed to get container state: %s", err)
		return
	}

	fmt.Println(state.Running)

	// Output:
	// true
}

Output:

true

func (*HTTPStrategy) WithResponseHeadersMatcher 

func (ws *HTTPStrategy) WithResponseHeadersMatcher(matcher func(http.Header) bool) *HTTPStrategy

func (*HTTPStrategy) WithResponseMatcher 

func (ws *HTTPStrategy) WithResponseMatcher(matcher func(body io.Reader) bool) *HTTPStrategy

func (*HTTPStrategy) WithStartupTimeout 

func (ws *HTTPStrategy) WithStartupTimeout(timeout time.Duration) *HTTPStrategy

WithStartupTimeout can be used to change the default startup timeout

func (*HTTPStrategy) WithStatusCodeMatcher 

func (ws *HTTPStrategy) WithStatusCodeMatcher(statusCodeMatcher func(status int) bool) *HTTPStrategy

func (*HTTPStrategy) WithTLS 

func (ws *HTTPStrategy) WithTLS(useTLS bool, tlsconf ...*tls.Config) *HTTPStrategy

type HealthStrategy 

type HealthStrategy struct {

	// additional properties
	PollInterval time.Duration
	// contains filtered or unexported fields
}

HealthStrategy will wait until the container becomes healthy

func ForHealthCheck 

func ForHealthCheck() *HealthStrategy

ForHealthCheck is the default construction for the fluid interface.

For Example: 

wait.
	ForHealthCheck().
	WithPollInterval(1 * time.Second)

func NewHealthStrategy 

func NewHealthStrategy() *HealthStrategy

NewHealthStrategy constructs with polling interval of 100 milliseconds and startup timeout of 60 seconds by default

func (*HealthStrategy) Timeout 

func (ws *HealthStrategy) Timeout() *time.Duration

func (*HealthStrategy) WaitUntilReady 

func (ws *HealthStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

WaitUntilReady implements Strategy.WaitUntilReady

func (*HealthStrategy) WithPollInterval 

func (ws *HealthStrategy) WithPollInterval(pollInterval time.Duration) *HealthStrategy

WithPollInterval can be used to override the default polling interval of 100 milliseconds

func (*HealthStrategy) WithStartupTimeout 

func (ws *HealthStrategy) WithStartupTimeout(startupTimeout time.Duration) *HealthStrategy

WithStartupTimeout can be used to change the default startup timeout

type HostPortStrategy 

type HostPortStrategy struct {
	// Port is a string containing port number and protocol in the format "80/tcp"
	// which
	Port nat.Port

	PollInterval time.Duration
	// contains filtered or unexported fields
}

func ForExposedPort 

func ForExposedPort() *HostPortStrategy

ForExposedPort returns a host port strategy that waits for the first port to be exposed and bound internally the container.

func ForListeningPort 

func ForListeningPort(port nat.Port) *HostPortStrategy

ForListeningPort returns a host port strategy that waits for the given port to be exposed and bound internally the container. Alias for `NewHostPortStrategy(port)`.

func NewHostPortStrategy 

func NewHostPortStrategy(port nat.Port) *HostPortStrategy

NewHostPortStrategy constructs a default host port strategy that waits for the given port to be exposed. The default startup timeout is 60 seconds.

func (*HostPortStrategy) SkipInternalCheck 

func (hp *HostPortStrategy) SkipInternalCheck() *HostPortStrategy

SkipInternalCheck changes the host port strategy to skip the internal check, which is useful when a shell is not available in the container or when the container doesn't bind the port internally until additional conditions are met.

func (*HostPortStrategy) Timeout 

func (hp *HostPortStrategy) Timeout() *time.Duration

func (*HostPortStrategy) WaitUntilReady 

func (hp *HostPortStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

WaitUntilReady implements Strategy.WaitUntilReady

func (*HostPortStrategy) WithPollInterval 

func (hp *HostPortStrategy) WithPollInterval(pollInterval time.Duration) *HostPortStrategy

WithPollInterval can be used to override the default polling interval of 100 milliseconds

func (*HostPortStrategy) WithStartupTimeout 

func (hp *HostPortStrategy) WithStartupTimeout(startupTimeout time.Duration) *HostPortStrategy

WithStartupTimeout can be used to change the default startup timeout

type LogStrategy 

type LogStrategy struct {

	// additional properties
	Log          string
	IsRegexp     bool
	Occurrence   int
	PollInterval time.Duration
	// contains filtered or unexported fields
}

LogStrategy will wait until a given log entry shows up in the docker logs

func ForLog 

func ForLog(log string) *LogStrategy

ForLog is the default construction for the fluid interface.

For Example: 

wait.
	ForLog("some text").
	WithPollInterval(1 * time.Second)

func NewLogStrategy 

func NewLogStrategy(log string) *LogStrategy

NewLogStrategy constructs with polling interval of 100 milliseconds and startup timeout of 60 seconds by default

func (*LogStrategy) AsRegexp 

func (ws *LogStrategy) AsRegexp() *LogStrategy

AsRegexp can be used to change the default behavior of the log strategy to use regexp instead of plain text

func (*LogStrategy) Timeout 

func (ws *LogStrategy) Timeout() *time.Duration

func (*LogStrategy) WaitUntilReady 

func (ws *LogStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

WaitUntilReady implements Strategy.WaitUntilReady

func (*LogStrategy) WithOccurrence 

func (ws *LogStrategy) WithOccurrence(o int) *LogStrategy

func (*LogStrategy) WithPollInterval 

func (ws *LogStrategy) WithPollInterval(pollInterval time.Duration) *LogStrategy

WithPollInterval can be used to override the default polling interval of 100 milliseconds

func (*LogStrategy) WithStartupTimeout 

func (ws *LogStrategy) WithStartupTimeout(timeout time.Duration) *LogStrategy

WithStartupTimeout can be used to change the default startup timeout

type MultiStrategy 

type MultiStrategy struct {

	// additional properties
	Strategies []Strategy
	// contains filtered or unexported fields
}

func ForAll 

func ForAll(strategies ...Strategy) *MultiStrategy

func (*MultiStrategy) Timeout 

func (ms *MultiStrategy) Timeout() *time.Duration

func (*MultiStrategy) WaitUntilReady 

func (ms *MultiStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

func (*MultiStrategy) WithDeadline 

func (ms *MultiStrategy) WithDeadline(deadline time.Duration) *MultiStrategy

WithDeadline sets a time.Duration which limits all wait strategies

func (*MultiStrategy) WithStartupTimeout 

func (ms *MultiStrategy) WithStartupTimeout(timeout time.Duration) Strategy

WithStartupTimeout sets a time.Duration which limits all wait strategies

Deprecated: use WithDeadline

func (*MultiStrategy) WithStartupTimeoutDefault 

func (ms *MultiStrategy) WithStartupTimeoutDefault(timeout time.Duration) *MultiStrategy

WithStartupTimeoutDefault sets the default timeout for all inner wait strategies

type NopStrategy 

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

func ForNop 

func ForNop(
	waitUntilReady func(context.Context, StrategyTarget) error,
) *NopStrategy

func (*NopStrategy) Timeout 

func (ws *NopStrategy) Timeout() *time.Duration

func (*NopStrategy) WaitUntilReady 

func (ws *NopStrategy) WaitUntilReady(ctx context.Context, target StrategyTarget) error

func (*NopStrategy) WithStartupTimeout 

func (ws *NopStrategy) WithStartupTimeout(timeout time.Duration) *NopStrategy

type NopStrategyTarget 

type NopStrategyTarget struct {
	ReaderCloser   io.ReadCloser
	ContainerState types.ContainerState
}

func (NopStrategyTarget) CopyFileFromContainer 

func (st NopStrategyTarget) CopyFileFromContainer(context.Context, string) (io.ReadCloser, error)

func (NopStrategyTarget) Exec 

func (st NopStrategyTarget) Exec(_ context.Context, _ []string, _ ...exec.ProcessOption) (int, io.Reader, error)

func (NopStrategyTarget) Host 

func (st NopStrategyTarget) Host(_ context.Context) (string, error)

func (NopStrategyTarget) Inspect 

func (st NopStrategyTarget) Inspect(_ context.Context) (*types.ContainerJSON, error)

func (NopStrategyTarget) Logs 

func (st NopStrategyTarget) Logs(_ context.Context) (io.ReadCloser, error)

func (NopStrategyTarget) MappedPort 

func (st NopStrategyTarget) MappedPort(_ context.Context, n nat.Port) (nat.Port, error)

func (NopStrategyTarget) Ports 

func (st NopStrategyTarget) Ports(_ context.Context) (nat.PortMap, error)

Deprecated: use Inspect instead

func (NopStrategyTarget) State 

func (st NopStrategyTarget) State(_ context.Context) (*types.ContainerState, error)

type Strategy 

type Strategy interface {
	WaitUntilReady(context.Context, StrategyTarget) error
}

Strategy defines the basic interface for a Wait Strategy

type StrategyTarget 

type StrategyTarget interface {
	Host(context.Context) (string, error)
	Inspect(context.Context) (*types.ContainerJSON, error)
	Ports(ctx context.Context) (nat.PortMap, error) // Deprecated: use Inspect instead
	MappedPort(context.Context, nat.Port) (nat.Port, error)
	Logs(context.Context) (io.ReadCloser, error)
	Exec(context.Context, []string, ...exec.ProcessOption) (int, io.Reader, error)
	State(context.Context) (*types.ContainerState, error)
	CopyFileFromContainer(ctx context.Context, filePath string) (io.ReadCloser, error)
}

type StrategyTimeout 

type StrategyTimeout interface {
	Timeout() *time.Duration
}

StrategyTimeout allows MultiStrategy to configure a Strategy's Timeout

Source Files

all.go errors.go exec.go exit.go file.go health.go host_port.go http.go log.go nop.go sql.go wait.go

Version
v0.34.0
Published
Oct 21, 2024
Platform
js/wasm
Imports
21 packages
Last checked
5 hours ago –

Tools for package owners.