The guide · how-to

Test a package

5 min read · 2026-09-02 · config-weave 0.1.0

Goal

Prove that a package's resources converge and stay converged by running its tests in a disposable instance with the testlab's three-run protocol. You need a package with at least one test block and the vmlab CLI on your PATH. Tests that declare a template run as full virtual machines and also need KVM. The example tests the file_present resource of a package named core.

1. Declare a test

Add a test block to package.wcl. It carries a description, exactly one of image or template, and one or more steps. image names an OCI image and runs the test as a container, which is Linux-only and starts in seconds. template names a vmlab template and runs the test as a full VM, Linux or Windows, with a real init system and the ability to reboot.

pkgs/core/package.wclwcl
test "file_present_converges" {
  description = "file_present creates the file and is idempotent"
  image = "debian:12"
  step "create" {
    description = "Create a marker file"
    resource = "file_present"
    properties { path = "/var/tmp/weave.txt"  content = "hello" }
  }
}

Every value in a test must be static. The test runs against a synthesized playbook with no variables, so a variable reference in test properties is a validation error. An unqualified resource or from reference resolves to the declaring package, so file_present here means core.file_present. A step defaults to expect = "converge": check must report not configured, apply must succeed, and a second apply must change nothing. The other expectations, the optional verify script, group and memory fields, and the gather assertions are in The test block.

2. Run the test

Run the test command on the playbook directory with an optional filter. No filter runs every test in every package, core runs that package's tests, and core:file_present_converges runs one test.

console
$ config-weave test ./my-playbook core:file_present_converges
⟳ [core:file_present_converges] provisioning (container debian:12)
⟳ core:file_present_converges — check
⟳ core:file_present_converges — first apply
⟳ core:file_present_converges — second apply

test 'My Playbook' — 1 test(s)
  ✓ core:file_present_converges                passed  container debian:12 4.2s
summary: 1 passed, 0 failed, 0 error (4.2s)

config-weave probes vmlab once up front, then provisions an instance, copies the binary and the synthesized playbook in, and runs check, apply and apply again, each as a separate process. The second run's internal re-check proves convergence within one process. The third run catches the subtler bug: state that only looked converged to the process that created it, which shows up as the step reporting configured instead of already configured. A failure lists each failing step under its test line.

The instance runs whatever binary you point it at. When your development build is dynamically linked, pass a static Linux binary with --binary PATH and, for Windows guests, --binary-windows PATH. To run every container test against a different image, or every VM test against a different template, pass --image REF or --template REF. Neither converts a test between the two kinds.

3. Debug a failure with --keep

When a test fails, run it again with --keep. The instance stays up after the run and its handle is reported, so you can attach with the vmlab CLI and inspect what apply wrote.

console
$ config-weave test ./my-playbook core --keep
⟳ [core:file_present_converges] kept <handle> — remove it manually when done

A kept instance is not torn down for you. Remove it with vmlab when you are finished. The exit code is 0 when every test passed, 1 when any test failed or errored, and 2 for a validation problem, a filter that matches nothing, or a vmlab environment that fails the up-front probe.

Done

config-weave test reports every selected test passed and exits 0. The package's resources converge, and stay converged across processes, on the declared image.

Next steps