Test harnesses in cuelang using golden files

[mogsie]

We want to be able to validate our cue files, so that when we make changes, then we know that previously implemented cue functionality hasn't been broken.

To do this, we have started to employ golden files:

• Create a test package in test.cue
• In this test package, import the package under test (in the same directory)
• run "cue export :test" and capture this to a golden file
• run "cue vet :test golden.yaml" to verify that this golden file matches the test.
• normalize and diff the output of cue export :test with the existing golden file to see if anything changed.

The test package can then exercise the package under test in different ways, and ensure that its behaviour is unchanged. This can be captured in a simple Makefile. make test to verify and make golden to update any golden files when changes are desired.

package test

import "example.com/path/network:network"

_test1: network.#Call
_test1: Input: {
	param1: "10.11"
	param2: "north-pole-2"
	param3: 33
}
test1: _test1.Output

We sometimes skip adding constraints for other imported types (like k8s or other go commands) to speed up normal execution, and then you can add additional constraints to the test output, e.g.

test1: somethingelse.#Constraint

Here is an excerpt of the Makefile:

test: ## Test that the :test package output matches the golden.yaml file
	cue vet :test golden.yaml
	cue export :test --out yaml | diff golden.yaml -

golden: ## Update the golden.yaml file with the :test package output
	cue export :test --out yaml --force --outfile golden.yaml