1.4.1 Procedures

Procedure: assert-container-running KEY: #:container #:name ¶

Return an assertion that container is running.

Unlike assert-true, the check is performed when the assertion runs, not when it is constructed.

Procedure: container-build KEY: #:tag #:dockerfile #:context #:extra-args ¶

Build an image with tag from dockerfile in context.

Procedure: container-exec container command ¶

Run command (a list of strings) inside running container.

Returns the captured combined output and raises on failure.

Procedure: container-exec-status container command ¶

Run command inside container, returning two values: status and output.

Procedure: container-logs container ¶

Return the logs of container as a string.

Procedure: container-remove container ¶

Force-stop and remove container, returning its exit status.

Procedure: container-run KEY: #:image #:name #:env #:ports #:volumes #:command #:detach? #:extra-args ¶

Start image and return the new container id (or name when given).

env entries are passed as -e variables, ports as -p bindings and volumes as -v mounts.

Procedure: container-running? container ¶

Return #t when container exists and is running.

Procedure: container-runtime ¶

Return the container runtime executable to use.

Honours VERITAS_CONTAINER_RUNTIME, otherwise prefers podman and falls back to docker.

Procedure: container-runtime-available? ¶

Return #t when a container runtime is available.

Procedure: container-stop container ¶

Stop container, returning its exit status.

Procedure: container-wait-for-command container command KEY: #:timeout #:interval ¶

Wait until command succeeds inside container.

Procedure: container-wait-for-log container pattern KEY: #:timeout #:interval ¶

Wait until container logs match pattern (regexp or string).

Procedure: container-wait-for-port host port KEY: #:timeout #:interval ¶

Wait until a TCP connection to host:port succeeds.

Procedure: run-command command KEY: #:input ¶

Run command, a list of strings, without a shell.

Returns two values: the exit status (an integer, -1 when the process could not be started) and the captured standard output as a string.

(call-with-values (lambda () (run-command (list "echo" "hi")))
  (lambda (status output) (list status output)))
⇒ (0 "hi\n")

Procedure: run-command! command KEY: #:input ¶

Like run-command, but raise an error on a non-zero exit status.

Returns the captured standard output.

Procedure: wait-until predicate KEY: #:timeout #:interval #:message ¶

Poll predicate every interval seconds until it is true.

Returns #t, or raises an error after timeout seconds. Exceptions raised by predicate are treated as a false result.

Procedure: with-container thunk KEY: #:image #:name #:env #:ports #:volumes #:command #:detach? #:extra-args #:wait #:keep? ¶

Start a container, call thunk with its id, and always clean it up.

wait, when supplied, is a procedure called with the container id after start (for example to wait for a log line or a port). keep? leaves the container running for debugging.