testhelpers

README

Go container testhelpers

Shared helpers for standalone Go container checks.

Purpose

• Reduce repeated testcontainers-go setup across app checks.
• Keep common behavior consistent:
  • TEST_IMAGE override support.
  • container cleanup and exit-code assertions.

Helpers

• GetTestImage(defaultImage string) Returns TEST_IMAGE when set, otherwise the provided default image.

• CheckHTTPEndpoint(...) error Runs a container and waits for an HTTP endpoint on a port/path to match the expected status. HTTP checks always include a TCP listening wait on the same port first.

• CheckTCPListening(...) error Runs a container and waits for a TCP port to become reachable.

• CheckWaits(..., httpConfigs []HTTPTestConfig, tcpConfigs []TCPTestConfig, ...) error Runs one container and waits for multiple checks in the same lifecycle:

  • httpConfigs []HTTPTestConfig
  • tcpConfigs []TCPTestConfig Every HTTP item implicitly enforces TCP listening wait first on the same port.

• CheckFileExists(...) error Verifies a file exists inside the container by running test -f.

• CheckFilesExist(..., filePaths []string, ...) error Verifies multiple files exist (one check per file path).

• CheckCommandSucceeds(...) error Runs a command via container cmd args and verifies exit code 0.

• CheckCommand(..., commandConfig *CommandTestConfig, ...) error Runs a command with optional assertions:

  • ExpectedExitCode (defaults to 0 when omitted)
  • ExpectedContent + MatchContent=true for output contains match (after trimming)

• CheckCommands(..., commands []CommandTestConfig) error Runs multiple command checks. Each item uses CommandTestConfig.Command executed as sh -c <command>.

For list-based file/command checks, each item currently starts its own container run.

• TestHTTPEndpoint(...), TestTCPListening(...), TestFileExists(...), TestFilesExist(...), TestCommandSucceeds(...), TestCommands(...) Convenience wrappers for go test that fail the test immediately when the check returns an error.

• TestWaits(...) Convenience wrapper for combined HTTP/TCP wait lists.

• HTTPTestConfig.StatusCodeMatcher func(int) bool Optional custom matcher for HTTP status codes.

Standalone usage (no go test)

You can run checks directly via:

go run ./cmd/run-tests --mode file --image ghcr.io/trueforge-org/actions-runner:rolling --file /usr/local/bin/yq

go run ./cmd/run-tests --mode http --image ghcr.io/trueforge-org/adguardhome-sync:rolling --http-port 8080 --http-path / --http-status 200

go run ./cmd/run-tests --mode command --image ghcr.io/trueforge-org/cloudflareddns:rolling --entrypoint test --arg -f --arg /app/cloudflare-ddns.sh

go run ./cmd/run-tests --mode command --image ghcr.io/trueforge-org/cloudflareddns:rolling --entrypoint sh --arg -c --arg 'echo ok' --command-exit-code 0 --command-content ok

Optional env vars for the started container can be added with repeated --env KEY=VALUE.

YAML structure (struct-based)

When defining container-test.yaml based on the helper structs, use:

• http: []HTTPTestConfig
• tcp: []TCPTestConfig
• commands: []CommandTestConfig
• filePaths: []string

Example YAMLs

Minimal HTTP readiness check:

# yaml-language-server: $schema=../../testhelpers/container-test.schema.json
timeoutSeconds: 180
http:
  - port: "8123"
    path: /

TCP + file existence checks:

# yaml-language-server: $schema=../../testhelpers/container-test.schema.json
timeoutSeconds: 120
tcp:
  - port: "8000"
filePaths:
  - /usr/local/bin/yq
  - /bin/sh

Command checks with exit code and output matching:

# yaml-language-server: $schema=../../testhelpers/container-test.schema.json
commands:
  - command: test -x /usr/local/bin/imaginary
    expectedExitCode: 0
  - command: /usr/local/bin/imaginary -version
    expectedExitCode: 1
    expectedContent: dev
    matchContent: true

Documentation

Index

• func CheckCommand(ctx context.Context, image string, containerConfig *ContainerConfig, ...) (err error)
• func CheckCommandSucceeds(ctx context.Context, image string, config *ContainerConfig, entrypoint string, ...) error
• func CheckCommands(ctx context.Context, image string, containerConfig *ContainerConfig, ...) error
• func CheckFileExists(ctx context.Context, image string, filePath string, config *ContainerConfig) error
• func CheckFilesExist(ctx context.Context, image string, filePaths []string, config *ContainerConfig) error
• func CheckHTTPEndpoint(ctx context.Context, image string, httpConfig HTTPTestConfig, ...) (err error)
• func CheckTCPListening(ctx context.Context, image string, port string, config *ContainerConfig) (err error)
• func CheckWaits(ctx context.Context, image string, httpConfigs []HTTPTestConfig, ...) (err error)
• func GetTestImage(defaultImage string) string
• func RunChecksFromYAML(ctx context.Context, image string, yamlPath string, ...) error
• func TestCommand(t testFailureReporter, ctx context.Context, image string, ...)
• func TestCommandSucceeds(t testFailureReporter, ctx context.Context, image string, ...)
• func TestCommands(t testFailureReporter, ctx context.Context, image string, ...)
• func TestFileExists(t testFailureReporter, ctx context.Context, image string, filePath string, ...)
• func TestFilesExist(t testFailureReporter, ctx context.Context, image string, filePaths []string, ...)
• func TestHTTPEndpoint(t testFailureReporter, ctx context.Context, image string, ...)
• func TestTCPListening(t testFailureReporter, ctx context.Context, image string, port string, ...)
• func TestWaits(t testFailureReporter, ctx context.Context, image string, ...)
• type CommandTestConfig
• type ContainerConfig
• type ContainerTestYAML
  • func LoadContainerTestYAML(filePath string) (ContainerTestYAML, error)
• type HTTPTestConfig
• type TCPTestConfig

Functions

func CheckCommand

func CheckCommand(ctx context.Context, image string, containerConfig *ContainerConfig, commandConfig *CommandTestConfig, entrypoint string, args ...string) (err error)

CheckCommand verifies that a command runs with optional expected exit code and output content checks.

func CheckCommandSucceeds

func CheckCommandSucceeds(ctx context.Context, image string, config *ContainerConfig, entrypoint string, args ...string) error

CheckCommandSucceeds verifies that a command runs successfully in the container (exit code 0).

func CheckCommands

func CheckCommands(ctx context.Context, image string, containerConfig *ContainerConfig, commands []CommandTestConfig) error

CheckCommands verifies that all provided commands pass using the command backend checks.

func CheckFileExists

func CheckFileExists(ctx context.Context, image string, filePath string, config *ContainerConfig) error

CheckFileExists verifies a file exists in the container.

func CheckFilesExist

func CheckFilesExist(ctx context.Context, image string, filePaths []string, config *ContainerConfig) error

CheckFilesExist verifies that all provided files exist in the container.

func CheckHTTPEndpoint

func CheckHTTPEndpoint(ctx context.Context, image string, httpConfig HTTPTestConfig, containerConfig *ContainerConfig) (err error)

CheckHTTPEndpoint verifies that an HTTP endpoint is accessible and returns the expected status code.

func CheckTCPListening

func CheckTCPListening(ctx context.Context, image string, port string, config *ContainerConfig) (err error)

CheckTCPListening verifies that a TCP port is listening in the container.

func CheckWaits

func CheckWaits(ctx context.Context, image string, httpConfigs []HTTPTestConfig, tcpConfigs []TCPTestConfig, containerConfig *ContainerConfig) (err error)

CheckWaits verifies HTTP and TCP waits within one container start/stop lifecycle.

func GetTestImage

func GetTestImage(defaultImage string) string

GetTestImage returns the image to test from TEST_IMAGE env var or falls back to the default

func RunChecksFromYAML

func RunChecksFromYAML(ctx context.Context, image string, yamlPath string, containerConfig *ContainerConfig) error

RunChecksFromYAML runs container checks defined in a struct-based container-test YAML file.

func TestCommand

func TestCommand(t testFailureReporter, ctx context.Context, image string, containerConfig *ContainerConfig, commandConfig *CommandTestConfig, entrypoint string, args ...string)

TestCommand runs a command check with optional expected exit code and output content checks.

func TestCommandSucceeds

func TestCommandSucceeds(t testFailureReporter, ctx context.Context, image string, containerConfig *ContainerConfig, entrypoint string, args ...string)

TestCommandSucceeds runs a command check and fails the test on error.

func TestCommands

func TestCommands(t testFailureReporter, ctx context.Context, image string, containerConfig *ContainerConfig, commands []CommandTestConfig)

TestCommands runs list-based command checks and fails the test on error.

func TestFileExists

func TestFileExists(t testFailureReporter, ctx context.Context, image string, filePath string, containerConfig *ContainerConfig)

TestFileExists runs a file existence check and fails the test on error.

func TestFilesExist

func TestFilesExist(t testFailureReporter, ctx context.Context, image string, filePaths []string, containerConfig *ContainerConfig)

TestFilesExist runs list-based file existence checks and fails the test on error.

func TestHTTPEndpoint

func TestHTTPEndpoint(t testFailureReporter, ctx context.Context, image string, httpConfig HTTPTestConfig, containerConfig *ContainerConfig)

TestHTTPEndpoint runs an HTTP endpoint check and fails the test on error.

func TestTCPListening

func TestTCPListening(t testFailureReporter, ctx context.Context, image string, port string, containerConfig *ContainerConfig)

TestTCPListening runs a TCP listening check and fails the test on error.

func TestWaits

func TestWaits(t testFailureReporter, ctx context.Context, image string, httpConfigs []HTTPTestConfig, tcpConfigs []TCPTestConfig, containerConfig *ContainerConfig)

TestWaits runs combined HTTP/TCP waits and fails the test on error.

Types

type CommandTestConfig

type CommandTestConfig struct {
	Command          string `yaml:"command"`
	ExpectedExitCode int    `yaml:"expectedExitCode"`
	ExpectedContent  string `yaml:"expectedContent"`
	MatchContent     bool   `yaml:"matchContent"`
}

CommandTestConfig holds optional configuration for command checks.

type ContainerConfig

type ContainerConfig struct {
	Env map[string]string // Environment variables to set in the container
}

ContainerConfig holds optional container configuration

type ContainerTestYAML

type ContainerTestYAML struct {
	TimeoutSeconds int                 `yaml:"timeoutSeconds"`
	HTTP           []HTTPTestConfig    `yaml:"http"`
	TCP            []TCPTestConfig     `yaml:"tcp"`
	Commands       []CommandTestConfig `yaml:"commands"`
	FilePaths      []string            `yaml:"filePaths"`
}

ContainerTestYAML defines the struct-based container-test.yaml schema.

Supported keys: - timeoutSeconds - http: []HTTPTestConfig - tcp: []TCPTestConfig - commands: []CommandTestConfig - filePaths: []string

Note: this intentionally mirrors the exported helper structs used by runtime checks.

func LoadContainerTestYAML

func LoadContainerTestYAML(filePath string) (ContainerTestYAML, error)

LoadContainerTestYAML reads and parses a container-test YAML file.

type HTTPTestConfig

type HTTPTestConfig struct {
	Port              string `yaml:"port"`
	Path              string `yaml:"path"`
	StatusCode        int    `yaml:"statusCode"`
	StatusCodeMatcher func(int) bool
}

HTTPTestConfig holds the configuration for HTTP endpoint tests

type TCPTestConfig

type TCPTestConfig struct {
	Port string `yaml:"port"`
}

TCPTestConfig holds the configuration for TCP wait checks.