Documentation
¶
Overview ¶
Package dockermanage provides lightweight Docker container lifecycle helpers for integration testing.
A Manager wraps the native Docker client and exposes methods to start, stop, remove, and list containers. Containers are configured through functional Option values such as WithImage, WithContainerPortTCP, and WithEnv.
After starting a container, use Manager.WaitReady with a custom ReadinessFunc to block until the service inside the container is accepting connections.
Every container created through this package is tagged with the ManagedLabelKey label, which allows bulk operations like Manager.StopManaged and Manager.RemoveManaged to clean up all managed containers.
Database-specific sub-packages (e.g., postgres) provide opinionated defaults for common databases.
Index ¶
- Constants
- type Container
- type ExecOptions
- type ExecResult
- type Manager
- func (m *Manager) Close() error
- func (m *Manager) Exec(ctx context.Context, containerID string, opts ExecOptions) (*ExecResult, error)
- func (m *Manager) ListManaged(ctx context.Context) ([]string, error)
- func (m *Manager) Remove(ctx context.Context, containerID string) error
- func (m *Manager) RemoveManaged(ctx context.Context) error
- func (m *Manager) Start(ctx context.Context, options ...Option) (_ *Container, retErr error)
- func (m *Manager) Stop(ctx context.Context, containerID string) error
- func (m *Manager) StopManaged(ctx context.Context) error
- func (m *Manager) WaitReady(ctx context.Context, container *Container, readiness ReadinessFunc, ...) error
- type Option
- func WithAutoRemove(autoRemove bool) Option
- func WithContainerPort(port string) Option
- func WithContainerPortTCP(port int) Option
- func WithEnv(key, value string) Option
- func WithEnvVars(envVars []string) Option
- func WithHostIP(hostIP string) Option
- func WithHostPort(port int) Option
- func WithImage(image string) Option
- func WithLabel(key, value string) Option
- func WithLabels(labels map[string]string) Option
- func WithName(name string) Option
- func WithPullProgress(w io.Writer) Option
- type ReadinessFunc
- type WaitOption
Constants ¶
const ( // DefaultHostIP is the default host IP used for port bindings. DefaultHostIP = "127.0.0.1" // ManagedLabelKey marks containers created by this package. The value indicates the container // type (e.g., "postgres"). Presence of the key means the container is managed. ManagedLabelKey = "pressly.goose" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExecOptions ¶
type ExecOptions struct {
Cmd []string // Command and arguments
Env []string // Optional environment variables
Stdout io.Writer // Where to write stdout (nil → discard)
Stderr io.Writer // Where to write stderr (nil → discard)
}
ExecOptions configures a command to run inside a container.
type ExecResult ¶
type ExecResult struct {
ExitCode int
}
ExecResult holds the outcome of an exec invocation.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager manages Docker containers using the native Docker client.
func NewManager ¶
NewManager creates a new manager backed by the Docker client configured from environment.
func (*Manager) Exec ¶
func (m *Manager) Exec(ctx context.Context, containerID string, opts ExecOptions) (*ExecResult, error)
Exec runs a command inside a running container and streams its output.
func (*Manager) ListManaged ¶
ListManaged returns all container IDs started by this package.
func (*Manager) RemoveManaged ¶
RemoveManaged removes all containers started by this package.
func (*Manager) StopManaged ¶
StopManaged stops all containers started by this package.
func (*Manager) WaitReady ¶
func (m *Manager) WaitReady(ctx context.Context, container *Container, readiness ReadinessFunc, opts ...WaitOption) error
WaitReady waits until a custom readiness checker succeeds.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option configures container start behavior.
func WithAutoRemove ¶
WithAutoRemove configures Docker AutoRemove behavior.
func WithContainerPort ¶
WithContainerPort sets the container port to expose, for example: "5432/tcp".
func WithContainerPortTCP ¶
WithContainerPortTCP is a convenience helper for TCP ports.
func WithEnvVars ¶
WithEnvVars appends environment variables in KEY=VALUE format.
func WithHostIP ¶
WithHostIP sets the host IP to bind the container port to.
func WithHostPort ¶
WithHostPort sets a fixed host port. Leave unset to auto-assign.
func WithLabels ¶
WithLabels merges labels into container labels.
func WithPullProgress ¶
WithPullProgress sets where image pull output is streamed.
type ReadinessFunc ¶
ReadinessFunc reports whether a container is ready.
type WaitOption ¶
type WaitOption func(*waitConfig)
WaitOption configures WaitReady behavior.
func WithDelay ¶
func WithDelay(d time.Duration) WaitOption
WithDelay sets the interval between readiness checks. Defaults to 500ms.
func WithTimeout ¶
func WithTimeout(d time.Duration) WaitOption
WithTimeout sets the maximum time to wait for readiness. Defaults to 30s.
Source Files
Directories