Documentation
¶
Overview ¶
Package tfrender renders Backyard's Terraform modules for tests. It runs a module's `terraform test` scenarios (providers mocked, nothing created) in a scratch copy, returns what each run left in its state, and loads a rendered backyard.yaml with internal/config the way the server does at startup (strict YAML, ${ENV} expansion, environment overrides, defaults and validation).
The configcheck tests under deploy/terraform/{aws,gcp,azure}/configcheck use it, so CI catches a rendered configuration that the server would refuse before anyone deploys it (an ECS task, Cloud Run revision or Container App that never becomes ready).
Terraform only runs when BACKYARD_TEST_TERRAFORM is set ("1" for terraform on PATH, or the path of a terraform binary); otherwise the tests skip. Provider downloads honour TF_PLUGIN_CACHE_DIR; without it the module's own .terraform directory is reused as a cache when `terraform init` ran there. Terraform's plugin cache is not safe for concurrent use, so run several configcheck packages with `go test -p 1` (make tf-configcheck does).
Index ¶
- Constants
- func Get(v any, path ...any) any
- func Load(t testing.TB, raw string, env map[string]string) (*config.Config, error)
- func Missing(raw string, env map[string]string) []string
- func Parse(r io.Reader) (map[string]*Run, []string, error)
- func Placeholder(name string) string
- func Refs(raw string) []string
- func Render(t testing.TB, tf string, o Options) map[string]*Run
- func Terraform(t testing.TB) string
- type Options
- type Run
Constants ¶
const EnvVar = "BACKYARD_TEST_TERRAFORM"
EnvVar names the variable that enables the Terraform-backed tests.
const PlaceholderSecret = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
PlaceholderSecret is a 64-character value, long enough for server.secret.
Variables ¶
This section is empty.
Functions ¶
func Get ¶
Get walks decoded JSON: string keys index objects, ints index arrays. It returns nil when the path does not exist.
func Load ¶
Load writes raw to a file and loads it with config.Load in exactly env: the variables config.Load reads and every variable raw references are cleared first, then env is applied (t.Setenv, so tests using Load cannot run in parallel).
func Missing ¶
Missing returns the variables raw references (see Refs) that env does not set: the server would expand them to empty strings.
func Parse ¶
Parse reads the machine-readable output of `terraform test -json -verbose` and returns the runs that left a state, plus one problem per failed run with its error diagnostics. (Runs with expect_failures report the expected errors as diagnostics too, but pass.)
func Placeholder ¶
Placeholder returns a value of the right shape for a secret-backed environment variable, judged by its name (a DSN for DATABASE_URL and *_DSN, a URL for *_URL, a random-looking string otherwise).
func Refs ¶
Refs returns the variables that raw references as ${VAR} without a default (escaped $${…} sequences excluded), sorted.
func Render ¶
Render copies the module (without .terraform, examples or configcheck directories) to a temporary directory, runs `terraform init` and `terraform test -json -verbose` there, and returns the runs that left a state, by run name. Failed runs and error diagnostics fail the test; a failed init (usually an unreachable provider registry) skips it.
Types ¶
type Options ¶
type Options struct {
// Module is the Terraform module directory.
Module string
// TestDir is the test directory, relative to the module, whose
// *.tftest.hcl files run ("tests" when empty).
TestDir string
// Extra copies more files into the scratch copy: destination (relative
// to the copy's root) → source path.
Extra map[string]string
// Timeout bounds init and test together (20 minutes when zero).
Timeout time.Duration
}
Options select what Render runs.
type Run ¶
type Run struct {
Name string
// File is the test file the run belongs to.
File string
// Outputs are the module's output values, decoded from JSON.
Outputs map[string]any
// Resources are the resources' attribute values by address (child
// modules included, as module.<name>.<address>).
Resources map[string]map[string]any
}
Run is what one `run` block of a test file left in its state. Only runs that apply (command = apply, the default) have one.
Source Files