docker_compose_test

Rules

docker_compose_test

docker_compose_test

load("@rules_docker_compose//docker_compose:docker_compose_test.bzl", "docker_compose_test")

docker_compose_test(name, data, delay, env, env_inherit, images, test, test_args, yamls)

Runs a test with docker-compose services.

This rule starts docker-compose services, waits for them to be ready, runs a test binary, and then tears down the services. The test lifecycle is:

Loading container images into Docker (under a per-original-tag daemon-level lock) and retagging each loaded image to a content-derived unique tag
Starting services with docker-compose up against the unique-tag-rewritten YAML
Waiting for containers to be running (with health checks)
Running the test binary with optional arguments
Cleaning up with docker-compose down

The test requires network access and Docker to be available on the host.

Supported image loader types:

Loader	Source
oci_load	rules_oci
image_load	rules_img

Example:

load("@rules_docker_compose//docker_compose:docker_compose_test.bzl", "docker_compose_test")
load("@rules_oci//oci:defs.bzl", "oci_load")

oci_load(
    name = "my_service.load",
    image = ":my_service",
    repo_tags = ["my-service:latest"],
)

docker_compose_test(
    name = "integration_test",
    yamls = ["docker-compose.yaml"],
    images = [":my_service.load"],
    test = ":my_test_binary",
    test_args = ["-host", "localhost:8080"],
    delay = 2,  # Wait 2 seconds after containers start
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional runtime dependencies for the test.	List of labels	optional	`[]`
delay	Seconds to wait after containers are running before executing the test. Useful for services that need initialization time beyond their health checks.	Integer	optional	`1`
env	Dictionary of strings; values are subject to `$(location)` and "Make variable" substitution	Dictionary: String -> String	optional	`{}`
env_inherit	Specifies additional environment variables to inherit from the external environment when the test is executed by `bazel test`.	List of strings	optional	`[]`
images	Image loader targets that provide the container images for the docker-compose services. Each image will be loaded into Docker before `docker-compose up` is called. See the rule documentation for supported loader types.	List of labels	optional	`[]`
test	The test binary to execute after containers are running. The binary will receive arguments from `test_args`.	Label	optional	`None`
test_args	Arguments to pass to the test binary.	List of strings	optional	`[]`
yamls	One or more docker-compose YAML files defining the services to run. Files are merged using `docker-compose config`.	List of labels	optional	`[]`