dockertest

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package dockertest provides test doubles for internal/docker.Client.

It composes whailtest.FakeAPIClient into a real *docker.Client, so docker-layer methods (ListContainers, FindContainerByAgent, etc.) execute real code through the whail jail — giving better coverage than mocking the docker.Client interface directly.

Usage: 

fake := dockertest.NewFakeClient(cfg)
fake.SetupContainerList(dockertest.RunningContainerFixture("myapp", "dev"))
containers, err := fake.Client.ListContainers(ctx, true)

fake.AssertCalled(t, "ContainerList")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildKitBuildOpts 

func BuildKitBuildOpts(tag, contextDir string) docker.BuildImageOpts

BuildKitBuildOpts returns a BuildImageOpts configured for the BuildKit path.

func ContainerFixture 

func ContainerFixture(project, agent, image string) container.Summary

ContainerFixture builds a container.Summary with proper clawker labels. The container is in "exited" state by default.

func ImageSummaryFixture 

func ImageSummaryFixture(repoTag string) whail.ImageSummary

ImageSummaryFixture returns an ImageSummary with the given repo tag.

func MinimalCreateOpts 

func MinimalCreateOpts() docker.ContainerCreateOptions

MinimalCreateOpts returns the minimum ContainerCreateOptions needed for whail's ContainerCreate to succeed (requires non-nil Config for label merging).

func MinimalStartOpts 

func MinimalStartOpts(containerID string) docker.ContainerStartOptions

MinimalStartOpts returns ContainerStartOptions for a given container ID.

func RunningContainerFixture 

func RunningContainerFixture(project, agent string) container.Summary

RunningContainerFixture builds a container.Summary in "running" state with a default image of "node:20-slim".

Types

type BuildKitCapture 

type BuildKitCapture = whailtest.BuildKitCapture

BuildKitCapture records calls to the fake BuildKit builder wired via SetupBuildKit.

type FakeClient 

type FakeClient struct {
	// Client is the real *docker.Client to inject into command Options.
	// Its embedded Engine delegates to FakeAPI through whail's jail layer.
	Client *docker.Client

	// FakeAPI is the underlying function-field fake. Set Fn fields here
	// to control what the Docker SDK "returns" for each operation.
	FakeAPI *whailtest.FakeAPIClient

	// Cfg is the config used to construct this client. Exposed so that
	// Setup helpers and callers can read label keys without hardcoding.
	Cfg config.Config
}

FakeClient wraps a real *docker.Client backed by a whailtest.FakeAPIClient. Configure behavior via FakeAPI's Fn fields; pass Client to code under test.

func NewFakeClient 

func NewFakeClient(cfg config.Config, opts ...FakeClientOption) *FakeClient

NewFakeClient constructs a FakeClient with production-equivalent label configuration. The returned Client.Engine uses clawker's label prefix, so docker-layer methods (ListContainers, FindContainerByAgent, etc.) exercise real label filtering logic.

func (*FakeClient) AssertCalled 

func (f *FakeClient) AssertCalled(t *testing.T, method string)

AssertCalled asserts that the given method was called at least once.

func (*FakeClient) AssertCalledN 

func (f *FakeClient) AssertCalledN(t *testing.T, method string, n int)

AssertCalledN asserts that the given method was called exactly n times.

func (*FakeClient) AssertNotCalled 

func (f *FakeClient) AssertNotCalled(t *testing.T, method string)

AssertNotCalled asserts that the given method was never called.

func (*FakeClient) Reset 

func (f *FakeClient) Reset()

Reset clears the call recording log.

func (*FakeClient) SetupBuildKit 

func (f *FakeClient) SetupBuildKit() *BuildKitCapture

SetupBuildKit wires a fake BuildKit builder onto the FakeClient's Engine. Returns a capture struct for asserting the builder was called with the expected options. The fake builder succeeds by default (returns nil error). 

fake := dockertest.NewFakeClient()
capture := fake.SetupBuildKit()
// exercise code that calls BuildImage with BuildKitEnabled=true
if capture.CallCount != 1 { ... }

func (*FakeClient) SetupBuildKitWithProgress 

func (f *FakeClient) SetupBuildKitWithProgress(events []whail.BuildProgressEvent) *BuildKitCapture

SetupBuildKitWithProgress wires a fake BuildKit builder that emits the given progress events via the OnProgress callback. Returns a capture struct for asserting the builder was called with expected options. 

events := whailtest.SimpleBuildEvents()
capture := fake.SetupBuildKitWithProgress(events)
// exercise code that calls BuildImage with BuildKitEnabled=true
assert.Equal(t, 1, capture.CallCount)

func (*FakeClient) SetupBuildKitWithRecordedProgress 

func (f *FakeClient) SetupBuildKitWithRecordedProgress(events []whailtest.RecordedBuildEvent) *BuildKitCapture

SetupBuildKitWithRecordedProgress wires a fake BuildKit builder that emits recorded events with timing delays. Use with scenarios loaded from JSON testdata files for realistic replay. 

scenario, _ := whailtest.LoadRecordedScenario("testdata/multi-stage.json")
capture := fake.SetupBuildKitWithRecordedProgress(scenario.Events)

func (*FakeClient) SetupContainerAttach 

func (f *FakeClient) SetupContainerAttach()

SetupContainerAttach configures the fake to succeed on ContainerAttach, returning a HijackedResponse backed by a net.Pipe. The server side of the pipe is closed immediately, simulating a container that exits right away.

func (*FakeClient) SetupContainerAttachWithOutput added in v0.1.4 

func (f *FakeClient) SetupContainerAttachWithOutput(data string)

SetupContainerAttachWithOutput configures the fake to return a hijacked connection for ContainerAttach that writes the given data as stdcopy-framed stdout. This allows StartContainer (which uses stdcopy.StdCopy) to demux the output correctly. The server side is closed after writing.

func (*FakeClient) SetupContainerCreate 

func (f *FakeClient) SetupContainerCreate()

SetupContainerCreate configures the fake to succeed on ContainerCreate, returning a container with the given fake ID.

func (*FakeClient) SetupContainerInspect 

func (f *FakeClient) SetupContainerInspect(containerID string, c container.Summary)

SetupContainerInspect configures the fake to return inspect data for the given container ID. Unlike SetupFindContainer (which also wires ContainerList for find-by-name), this only wires ContainerInspect — suitable for commands that already have a container ID and just need inspect data.

func (*FakeClient) SetupContainerKill 

func (f *FakeClient) SetupContainerKill()

SetupContainerKill configures the fake to succeed on ContainerKill.

func (*FakeClient) SetupContainerList 

func (f *FakeClient) SetupContainerList(containers ...container.Summary)

SetupContainerList configures the fake to return the given containers from ContainerList calls. The whail jail will inject the managed label filter automatically, so callers only need to provide containers with proper clawker labels.

func (*FakeClient) SetupContainerListError added in v0.1.4 

func (f *FakeClient) SetupContainerListError(err error)

SetupContainerListError configures the fake to return an error from ContainerList calls.

func (*FakeClient) SetupContainerLogs 

func (f *FakeClient) SetupContainerLogs(logs string)

SetupContainerLogs configures the fake to return the given string as log output. The logs are returned as a plain io.ReadCloser (suitable for non-multiplexed TTY output).

func (*FakeClient) SetupContainerPause 

func (f *FakeClient) SetupContainerPause()

SetupContainerPause configures the fake to succeed on ContainerPause.

func (*FakeClient) SetupContainerRemove 

func (f *FakeClient) SetupContainerRemove()

SetupContainerRemove configures the fake to succeed on ContainerRemove.

func (*FakeClient) SetupContainerRename 

func (f *FakeClient) SetupContainerRename()

SetupContainerRename configures the fake to succeed on ContainerRename.

func (*FakeClient) SetupContainerResize 

func (f *FakeClient) SetupContainerResize()

SetupContainerResize configures the fake to succeed on ContainerResize.

func (*FakeClient) SetupContainerRestart 

func (f *FakeClient) SetupContainerRestart()

SetupContainerRestart configures the fake to succeed on ContainerRestart.

func (*FakeClient) SetupContainerStart 

func (f *FakeClient) SetupContainerStart()

SetupContainerStart configures the fake to succeed on ContainerStart.

func (*FakeClient) SetupContainerStats 

func (f *FakeClient) SetupContainerStats(statsJSON string)

SetupContainerStats configures the fake to return a single JSON stats response. The body is a one-shot io.ReadCloser containing the given JSON. Pass an empty string for a minimal default stats response.

func (*FakeClient) SetupContainerStop 

func (f *FakeClient) SetupContainerStop()

SetupContainerStop configures the fake to succeed on ContainerStop.

func (*FakeClient) SetupContainerTop 

func (f *FakeClient) SetupContainerTop(titles []string, processes [][]string)

SetupContainerTop configures the fake to return the given process table.

func (*FakeClient) SetupContainerUnpause 

func (f *FakeClient) SetupContainerUnpause()

SetupContainerUnpause configures the fake to succeed on ContainerUnpause.

func (*FakeClient) SetupContainerUpdate 

func (f *FakeClient) SetupContainerUpdate()

SetupContainerUpdate configures the fake to succeed on ContainerUpdate.

func (*FakeClient) SetupContainerWait 

func (f *FakeClient) SetupContainerWait(exitCode int64)

SetupContainerWait configures the fake to succeed on ContainerWait, returning the given exit code immediately.

func (*FakeClient) SetupCopyFromContainer 

func (f *FakeClient) SetupCopyFromContainer()

SetupCopyFromContainer configures the fake to succeed on CopyFromContainer, returning an empty tar stream.

func (*FakeClient) SetupCopyToContainer 

func (f *FakeClient) SetupCopyToContainer()

SetupCopyToContainer configures the fake to succeed on CopyToContainer.

func (*FakeClient) SetupExecAttach 

func (f *FakeClient) SetupExecAttach()

SetupExecAttach configures the fake to return a hijacked connection for ExecAttach. The server side is closed immediately (suitable for non-TTY tests).

func (*FakeClient) SetupExecAttachWithOutput added in v0.1.4 

func (f *FakeClient) SetupExecAttachWithOutput(data string)

SetupExecAttachWithOutput configures the fake to return a hijacked connection for ExecAttach that writes the given data as stdcopy-framed stdout. This allows ExecCapture (which uses stdcopy.StdCopy) to demultiplex the output correctly. The server side is closed after writing, so the client side reads the data then gets EOF.

func (*FakeClient) SetupExecCreate 

func (f *FakeClient) SetupExecCreate(execID string)

SetupExecCreate configures the fake to succeed on ExecCreate, returning the given exec ID.

func (*FakeClient) SetupExecInspect 

func (f *FakeClient) SetupExecInspect(exitCode int)

SetupExecInspect configures the fake to return an ExecInspect result with the given exit code. Running is set to false (exec completed).

func (*FakeClient) SetupExecStart 

func (f *FakeClient) SetupExecStart()

SetupExecStart configures the fake to succeed on ExecStart (detach mode).

func (*FakeClient) SetupFindContainer 

func (f *FakeClient) SetupFindContainer(name string, c container.Summary)

SetupFindContainer configures the fake so that FindContainerByAgent returns the given container when the matching name is inspected. It sets up ContainerInspect to return managed inspect data plus a ContainerList that includes the container (FindContainerByName uses list + name filter internally).

func (*FakeClient) SetupImageExists 

func (f *FakeClient) SetupImageExists(ref string, exists bool)

SetupImageExists configures the fake to report whether a managed image exists. When exists is true, ImageInspect returns a managed result with clawker labels. When exists is false, ImageInspect returns a not-found error.

func (*FakeClient) SetupImageList 

func (f *FakeClient) SetupImageList(summaries ...whail.ImageSummary)

SetupImageList configures the fake to return the given image summaries from ImageList calls.

func (*FakeClient) SetupImageTag 

func (f *FakeClient) SetupImageTag()

SetupImageTag configures the fake to succeed on ImageTag. It wires both ImageTag and ImageInspect (for managed label check).

func (*FakeClient) SetupLegacyBuild 

func (f *FakeClient) SetupLegacyBuild()

SetupLegacyBuild wires a fake legacy (non-BuildKit) image build that succeeds. Returns an empty build response body. Use this for code paths that call client.BuildImage without BuildKitEnabled (e.g., init command).

func (*FakeClient) SetupLegacyBuildError 

func (f *FakeClient) SetupLegacyBuildError(err error)

SetupLegacyBuildError wires a fake legacy image build that returns the given error.

func (*FakeClient) SetupNetworkCreate 

func (f *FakeClient) SetupNetworkCreate()

SetupNetworkCreate configures the fake to succeed on NetworkCreate.

func (*FakeClient) SetupNetworkExists 

func (f *FakeClient) SetupNetworkExists(name string, exists bool)

SetupNetworkExists configures the fake to report whether a network exists. When exists is true, NetworkInspect returns a managed network. When exists is false, NetworkInspect returns a not-found error. If name is empty, the behavior applies to all network names.

func (*FakeClient) SetupPingBuildKit 

func (f *FakeClient) SetupPingBuildKit()

SetupPingBuildKit wires PingFn to report BuildKit as the preferred builder. Use this when exercising code paths that call BuildKitEnabled() for detection.

func (*FakeClient) SetupVolumeCreate 

func (f *FakeClient) SetupVolumeCreate()

SetupVolumeCreate configures the fake to succeed on VolumeCreate, returning a volume with the requested name and managed labels.

func (*FakeClient) SetupVolumeExists 

func (f *FakeClient) SetupVolumeExists(name string, exists bool)

SetupVolumeExists configures the fake to report whether a volume exists. When exists is true, VolumeInspect returns a managed volume. When exists is false, VolumeInspect returns a not-found error. If name is empty, the behavior applies to all volume names.

type FakeClientOption 

type FakeClientOption func(*FakeClient)

FakeClientOption configures a FakeClient.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.