Documentation ¶
Index ¶
- type Acquirer
- func (a *Acquirer) Do(ctx context.Context) (map[*Container]Ports, ReleaseFunc, error)
- func (a *Acquirer) Use(c *Container, exclusive bool, opts ...UseOption) *Acquirer
- func (a *Acquirer) UseExclusive(c *Container, opts ...UseOption) *Acquirer
- func (a *Acquirer) UseShared(c *Container, opts ...UseOption) *Acquirer
- type Backend
- type BuildOption
- type BuildParams
- type Confort
- func (cft *Confort) APIClient() *client.Client
- func (cft *Confort) Build(ctx context.Context, b *BuildParams, opts ...BuildOption) error
- func (cft *Confort) Close() error
- func (cft *Confort) Namespace() string
- func (cft *Confort) Network() *types.NetworkResource
- func (cft *Confort) Run(ctx context.Context, c *ContainerParams, opts ...RunOption) (*Container, error)
- type Container
- func (c *Container) Alias() string
- func (c *Container) CreateExec(ctx context.Context, cmd []string, opts ...ExecOption) (*ContainerExec, error)
- func (c *Container) ID() string
- func (c *Container) Name() string
- func (c *Container) Use(ctx context.Context, exclusive bool, opts ...UseOption) (Ports, ReleaseFunc, error)
- func (c *Container) UseExclusive(ctx context.Context, opts ...UseOption) (Ports, ReleaseFunc, error)
- func (c *Container) UseShared(ctx context.Context, opts ...UseOption) (Ports, ReleaseFunc, error)
- type ContainerExec
- func (e *ContainerExec) CombinedOutput(ctx context.Context) ([]byte, error)
- func (e *ContainerExec) Output(ctx context.Context) ([]byte, error)
- func (e *ContainerExec) Run(ctx context.Context) error
- func (e *ContainerExec) Start(ctx context.Context) error
- func (e *ContainerExec) Wait(ctx context.Context) error
- type ContainerParams
- type ExecOption
- type ExitError
- type InitFunc
- type Namespace
- type NewOption
- type Ports
- type ReleaseFunc
- type ResourcePolicy
- type RunOption
- func WithConfigConsistency(check bool) RunOption
- func WithContainerConfig(f func(config *container.Config)) RunOption
- func WithHostConfig(f func(config *container.HostConfig)) RunOption
- func WithNetworkingConfig(f func(config *network.NetworkingConfig)) RunOption
- func WithPullOptions(opts *types.ImagePullOptions, out io.Writer) RunOption
- type UseOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Acquirer ¶ added in v1.2.0
type Acquirer struct {
// contains filtered or unexported fields
}
func Acquire ¶ added in v1.2.0
func Acquire() *Acquirer
Acquire initiates the acquisition of locks of the multi-containers. To avoid the deadlock in your test cases, use Acquire as below:
ports, release, err := Acquire(). Use(container1, true). Use(container2, false, WithInitFunc(initContainer2)). Do(ctx) if err != nil { t.Fatal(err) } t.Cleanup(release) ports1 := ports[container1] ports2 := ports[container2] * Acquire locks of container1 and container2 at the same time * If either lock acquisition or initContainer2 fails, lock acquisition for all containers fails * If initContainer2 succeeded but acquisition failed, the successful result of init is preserved * Returned func releases all acquired locks
func (*Acquirer) UseExclusive ¶ added in v1.2.0
UseExclusive registers a container as the target of acquiring exclusive lock.
type BuildOption ¶
func WithBuildOutput ¶
func WithBuildOutput(dst io.Writer) BuildOption
WithBuildOutput sets dst that the output during build will be written.
func WithForceBuild ¶
func WithForceBuild() BuildOption
WithForceBuild forces to build an image even if it already exists.
func WithImageBuildOptions ¶
func WithImageBuildOptions(f func(option *types.ImageBuildOptions)) BuildOption
WithImageBuildOptions modifies the configuration of build. The argument `option` already contains required values, according to Build.
type BuildParams ¶ added in v0.3.0
type BuildParams struct { Image string Dockerfile string ContextDir string BuildArgs map[string]*string // RegistryAuth sets authentication config per registry host. // // BuildParam{ // RegistryAuth: map[string] types.AuthConfig { // "https://your.docker.registry.com": { // Username: "your_user", // Password: "your_password", // }, // } // } RegistryAuth map[string]types.AuthConfig Platform string }
type Confort ¶
type Confort struct {
// contains filtered or unexported fields
}
func New ¶
New creates Confort instance which is an interface of controlling containers. Confort creates docker resources like a network and containers. Also, it provides an exclusion control of container usage.
If you want to control the same containers across parallelized tests, enable integration with the beacon server by using `confort` command and WithBeacon option.
func (*Confort) Build ¶
func (cft *Confort) Build(ctx context.Context, b *BuildParams, opts ...BuildOption) error
Build creates new image from given Dockerfile and context directory.
When same name image already exists, it doesn't perform building. WithForceBuild enables us to build image on every call of Build.
func (*Confort) Network ¶ added in v0.2.0
func (cft *Confort) Network() *types.NetworkResource
Network returns docker network representation associated with Confort.
func (*Confort) Run ¶
func (cft *Confort) Run(ctx context.Context, c *ContainerParams, opts ...RunOption) (*Container, error)
Run starts container with given parameters. If container already exists and not started, it starts. It reuses already started container and its endpoint information.
When container is already existing and connected to another network, Run and other methods let the container connect to this network and create alias. For now, without specifying host port, container loses the port binding occasionally. If you want to use port binding and use a container with several network, and encounter such trouble, give it a try.
type Container ¶
type Container struct {
// contains filtered or unexported fields
}
Container represents a created container and its controller.
func (*Container) Alias ¶ added in v0.3.0
Alias returns a host name of the container. The alias is valid only in a docker network created in New or attached by Confort.Run.
func (*Container) CreateExec ¶ added in v1.3.0
func (c *Container) CreateExec(ctx context.Context, cmd []string, opts ...ExecOption) (*ContainerExec, error)
CreateExec creates new ContainerExec that executes the specified command on the container.
func (*Container) Use ¶ added in v0.3.0
func (c *Container) Use(ctx context.Context, exclusive bool, opts ...UseOption) (Ports, ReleaseFunc, error)
Use acquires a lock for using the container and returns its endpoint. If exclusive is true, it requires to use the container exclusively. When other tests have already acquired an exclusive or shared lock for the container, it blocks until all previous locks are released.
func (*Container) UseExclusive ¶ added in v0.3.0
func (c *Container) UseExclusive(ctx context.Context, opts ...UseOption) (Ports, ReleaseFunc, error)
UseExclusive acquires an exclusive lock for using the container explicitly and returns its endpoint.
type ContainerExec ¶ added in v1.3.0
type ContainerExec struct { Stdout io.Writer Stderr io.Writer // contains filtered or unexported fields }
func (*ContainerExec) CombinedOutput ¶ added in v1.3.0
func (e *ContainerExec) CombinedOutput(ctx context.Context) ([]byte, error)
CombinedOutput runs the command and returns its combined standard output and standard error. Because the difference of stdout and stderr, an order of the lines of the combined output is not preserved.
func (*ContainerExec) Output ¶ added in v1.3.0
func (e *ContainerExec) Output(ctx context.Context) ([]byte, error)
Output runs the command and returns its standard output.
func (*ContainerExec) Run ¶ added in v1.3.0
func (e *ContainerExec) Run(ctx context.Context) error
Run starts the specified command and waits for it to complete.
func (*ContainerExec) Start ¶ added in v1.3.0
func (e *ContainerExec) Start(ctx context.Context) error
Start executes the command but does not wait for it to complete.
func (*ContainerExec) Wait ¶ added in v1.3.0
func (e *ContainerExec) Wait(ctx context.Context) error
Wait waits for the specified command to exit and waits for copying from stdout or stderr to complete. The command must have been started by Start. The returned error is nil if the command runs, has no problems copying stdin, stdout, and stderr, and exits with a zero exit status. If the command fails to run or doesn't complete successfully, the error is of type *ExitError.
type ContainerParams ¶ added in v0.3.0
type ExecOption ¶ added in v1.3.0
func WithExecEnv ¶ added in v1.3.0
func WithExecEnv(kv map[string]string) ExecOption
WithExecEnv specifies environment variables using in the container.
func WithExecWorkingDir ¶ added in v1.3.0
func WithExecWorkingDir(s string) ExecOption
WithExecWorkingDir specifies working directory inside the container.
type Namespace ¶
type Namespace interface { Namespace() string Network() *types.NetworkResource CreateContainer(ctx context.Context, name string, container *container.Config, host *container.HostConfig, network *network.NetworkingConfig, configConsistency bool, wait *wait.Waiter, pullOptions *types.ImagePullOptions, pullOut io.Writer) (string, error) StartContainer(ctx context.Context, name string) (Ports, error) Release(ctx context.Context) error }
type NewOption ¶
func WithBeacon ¶
func WithBeacon() NewOption
WithBeacon configures Confort to integrate with a starting beacon server. The beacon server is started by the "confort" command. The address of server will be read from CFT_BEACON_ADDR or lock file specified as CFT_LOCKFILE.
With `confort test` command ¶
This command starts beacon server and sets the address as CFT_BEACON_ADDR automatically.
With `confort start` command ¶
This command starts beacon server and creates a lock file that contains the address. The default filename is ".confort.lock" and you don't need to set the file name as CFT_LOCKFILE. If you set a custom filename with "-lock-file" option, also you have to set the file name as CFT_LOCKFILE, or you can set address that read from lock file as CFT_BEACON_ADDR.
func WithClientOptions ¶
WithClientOptions sets options for Docker API client. Default option is client.FromEnv. For detail, see client.NewClientWithOpts.
func WithDefaultTimeout ¶
WithDefaultTimeout sets the default timeout for each request to the Docker API and beacon server. The default value of the "default timeout" is 1 min. If default timeout is 0, Confort doesn't apply any timeout for ctx.
If a timeout has already been set to ctx, the default timeout is not applied.
func WithNamespace ¶
WithNamespace specifies namespace of Confort. Default namespace is the value of the CFT_NAMESPACE environment variable. The "confort test" command has "-namespace" option that overrides the variable. If force is true, the value of the argument namespace takes precedence.
If neither CFT_NAMESPACE nor WithNamespace is set, New fails.
func WithResourcePolicy ¶
func WithResourcePolicy(s ResourcePolicy) NewOption
WithResourcePolicy overrides the policy for handling Docker resources that already exist, such as containers and networks. By default, ResourcePolicyReuse or the value of the CFT_RESOURCE_POLICY environment variable, if set, is used. The "confort test" command has "-policy" option that overrides the variable.
type Ports ¶
func (Ports) Binding ¶
func (p Ports) Binding(port nat.Port) (b nat.PortBinding)
Binding returns the first value associated with the given container port. If there are no values associated with the port, Binding returns zero value. To access multiple values, use the nat.PortMap directly.
func (Ports) HostPort ¶ added in v0.2.0
HostPort returns "host:port" style string of the first value associated with the given container port. If there are no values associated with the port, HostPort returns empty string.
type ReleaseFunc ¶ added in v1.1.0
type ReleaseFunc func()
type ResourcePolicy ¶
type ResourcePolicy string
const ( ResourcePolicyError ResourcePolicy = beacon.ResourcePolicyError ResourcePolicyReuse ResourcePolicy = beacon.ResourcePolicyReuse ResourcePolicyReusable ResourcePolicy = beacon.ResourcePolicyReusable ResourcePolicyTakeOver ResourcePolicy = beacon.ResourcePolicyTakeOver )
type RunOption ¶
func WithConfigConsistency ¶
WithConfigConsistency enables/disables the test checking consistency of configurations. By default, this test is disabled. NOTICE: This is quite experimental feature.
func WithContainerConfig ¶
WithContainerConfig modifies the configuration of container. The argument `config` already contains required values to create container, apply your values with care.
func WithHostConfig ¶
func WithHostConfig(f func(config *container.HostConfig)) RunOption
WithHostConfig modifies the configuration of container from host side. The argument `config` already contains required values to create container, apply your values with care.
func WithNetworkingConfig ¶
func WithNetworkingConfig(f func(config *network.NetworkingConfig)) RunOption
WithNetworkingConfig modifies the configuration of network. The argument `config` already contains required values to connecting to bridge network, and a container cannot join multi-networks on container creation.
func WithPullOptions ¶
func WithPullOptions(opts *types.ImagePullOptions, out io.Writer) RunOption
WithPullOptions enables to pull image that not exists. For example, if you want to use an image hosted in private repository, you have to fill RegistryAuth field.
The output will be written to `out`. If nil, io.Discard will be used.
type UseOption ¶
func WithInitFunc ¶
WithInitFunc sets initializer to set up container using the given port. The init will be performed only once per container, executed with an exclusive lock. If you use a container with Confort.UseShared, the lock state is downgraded to the shared lock after init.
The returned error makes the acquired lock released and testing.TB fail. After that, you can attempt to use the container and init again.