itestcontainer

command module
v0.1.3 Latest Latest
Warning

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

Go to latest
Published: Jun 23, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

itestcontainer

itestcontainer is a runner shim invoked by rules_itest's itest_service as an exe to launch a container image as the system under test.

Runtime Backends

itestcontainer supports two container runtimes:

Runtime Backend Networking
docker moby/moby client Docker bridge networking
containerd containerd/v2 CNI (bridge + portmap)

By default, itestcontainer expects images to be pre-loaded into the container runtime.

By default, itestcontainer auto-detects the runtime: it probes the containerd socket first (/run/containerd/containerd.sock), then falls back to Docker (DOCKER_HOST or /var/run/docker.sock). Override with --runtime=docker or --runtime=containerd.

Image Pulling

itestcontainer assumes images are available in the local runtime cache. If an image is missing, it will fail to start.

You can enable automatic image pulling by using the PullImages flag in RunOptions (if using as a Go library) or via corresponding command-line flags. This functionality should be used sparingly or only for local development, as it introduces external dependencies during test execution.

containerd Prerequisites
  • containerd running with a socket accessible at /run/containerd/containerd.sock
  • CNI plugin binaries installed: bridge, portmap, loopback (typically under /opt/cni/bin)

Flags

Flag Description
--name Container image to start (required)
--runtime Runtime backend: docker or containerd (default: auto-detect)
--ports Port mappings, comma-separated <host>:<container> (e.g. 8080:80/tcp)
--pull-images Enable automatic image pulling if not found locally (default: false).
--env Environment variables to pass through, comma-separated
--volume Volume mounts, comma-separated <source>:<target>
--labels Container labels, comma-separated <key>=<value>

By default, itestcontainer assumes images are already loaded into the container runtime. The --pull-images flag should only be used if automatic pulling is required for local development workflows.

Example:

load("@rules_img//img:image.bzl", "image_manifest")
load("@rules_img//img:load.bzl", "image_load")
load("@rules_itest//:itest.bzl", "itest_service", "itest_task", "named_port")

platform(
    name = "host_docker_platform",
    constraint_values = ["@platforms//os:linux"],  # linux OS inside docker host
    parents = ["@platforms//host"],  # use host CPU
)

# Construct a Postgresql for the container host
image_manifest(
    name = "pg_image",
    base = "@postgresql",
    platform = ":host_docker_platform",
)

# An executable target to load the image into the container host
image_load(
    name = "load_pg_image",
    image = ":pg_image",
    tag = "pg_image:latest",
)

# A task that invokes the previous executable target
itest_task(
    name = "load_pg_image_task",
    testonly = True,
    exe = ":load_pg_image",
)

# The service under test, which depends on the load task to load the image, and then invokes `itestcontainer` to run the image with the provided options.
itest_service(
    name = "sut",
    testonly = True,
    args = [
        # Name of the image to start
        "--name=pg_image:latest",
        # Environment variables to pass through to the container
        "--env=POSTGRES_USER,POSTGRES_PASSWORD,POSTGRES_DB",
        # Ports to expose from the container, using `rules_test`'s helper macro
        "--ports=" + named_port("//:sut", "db") + ":5432",
        # --labels
        # --volume
    ],
    env = {
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "postgres",
    },
    exe = "@com_github_jaqx0r_itestcontainer//:itestcontainer",
    named_ports = [
        "db",
    ],
    deps = [":load_pg_image_task"],
)

Use the Go Tools Pattern to include itestcontainer into your dependencies.

See test/tools.go and the rest of the test directory for a full example.

Documentation

Overview

itestcontainer is a runner shim invoked by a `rules_itest`'s `itest_service` as an `exe` to launch a container image.

Pass the name of the container, any environment the container needs, volume mounts, port assignments, and labels.

Volumes are managed by the selected runtime backend (Docker named volumes or containerd host bind mounts), but are identified internally with the prefix `bazel-itest-`. If run inside the Bazel test execution environment (i.e. with the environment variable `TEST_TARGET` set) then that string is hashed and appended to the volume name. This allows each `itest_service` to run concurrently, avoiding contention and potential locking issues.

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL