Testing OpenTofu
Test OpenTofu code with tofu test and mocked providers, run with the network switched off. The tests read the real configuration and workspace files, so they need no credentials and can't create anything. A test only helps when it fails for the right reason, so change the code one line at a time in a scratch copy and confirm that a test fails each time. The limits were found on OpenTofu 1.13.2, and each one changes how you write the tests.
Mocked tests
A mocked provider returns made-up values for every attribute the plan reads. The plan still runs through the real code: variables, locals, for_each, validations, preconditions and outputs. That covers most mistakes in a configuration that builds resources from YAML files, such as a missing key, a name without its required prefix, or a default that wins over a value that was set.
Test a module directly when you want to assert on its resources, and test the root when you want to assert on its outputs. A root run can't assert on the resources of a child module, so a check on a resource belongs in a test file in the module's own tests/ directory.
Example
This file lives in modules/network/tests/network.tftest.hcl. The module reads a list of networks, and a validation requires every network name to start with name_prefix.
mock_provider "example" {}
variables {
name_prefix = "acme-"
}
run "valid_network" {
command = plan
variables {
networks = { acme-main = { cidr = "10.10.0.0/24" } }
}
assert {
condition = example_network.this["acme-main"].ip_network[0].address == "10.10.0.0/24"
error_message = "the network must take its address from the cidr key"
}
}
run "name_without_prefix" {
command = plan
variables {
networks = { main = { cidr = "10.10.0.0/24" } }
}
expect_failures = [var.networks]
}The second run passes only when the validation on var.networks fails, so it shows that the prefix rule is enforced. A run that expects a failure and gets none fails the test.
Fixtures
Keep the files a test reads under tests/fixtures/, never in the directories the real configuration reads. A fixture in the real directory ends up in the next plan of a real workspace. Pass the fixture directory through a variable, for example workspaces_dir, and leave its default pointing at the real files. Then the same code path runs in the test and in production, and a second test can read the committed files themselves.
Mutation checks
A passing test says nothing about whether it can fail. Copy the module to a scratch directory, change one thing, and run the tests there. Every change must make at least one test fail, and the failing run should be the one written for that change. Useful mutations are small:
- Put
true ||in front of a condition, orfalse &&, to turn a check or a filter off. - Swap two operands of
merge()orcoalesce(), to test the order of precedence. - Remove a
try(), a validation or a precondition. - Make an assert accept every value, to test that the fixture holds a case that fails it.
Write down each result next to the mutation, with the names of the failing runs. A mutation that no test notices is a finding, and it has one of two causes: a missing test or an equivalent mutant.
Missing tests
The first cause is a missing test. In one project the fixtures held a merge of nested maps, and the mutation that made the deepest level accept every value passed at two levels. The fixture had no value at those levels that the check would have rejected, so two fixture cases were added. Another mutation removed the read of a value in a routed network, and no test used a routed network.
Equivalent mutants
The second cause is an equivalent mutant, which behaves like the original, so no test can tell them apart. A try() around a value changed nothing, because an earlier check already failed when the value was missing. Remove the try(), because it guards a case that can't happen. No test is missing there.
Resource order
One mutation survived in a different way: a module output that returns cluster IDs without waiting for the node groups. A plan shows no order between resources, so no planned value or assert can see it. A test can't catch a missing depends_on. Note such a case in the module and review it by hand.
Limits
Each limit showed up while testing a real configuration.
Ephemeral resources
A mock provider can't replace an ephemeral resource. The source says so: internal/configs/test_file.go has the comment "TODO ephemeral testing support". The mock returns made-up strings for the ephemeral resource, and a real provider that reads them as input rejects them, for example a client certificate that is not valid PEM. Mock that provider as well. The cost is that no test plans with the provider blocks as written, so only tofu validate reads them.
Blocked destroys
expect_failures only matches a check, a precondition or a variable validation. A destroy that prevent_destroy blocks fails with "Resource instance cannot be destroyed", and no expect_failures entry matches it. The test file would also fail at its own cleanup, because tofu destroys what the file created.
Test the parts around it instead. Assert on the value that each resource gets for prevent_destroy, and read the .tf files to check that every resource uses the value of its own type (see text checks). A resource type with the value set to false can be destroyed, so a run with expect_failures on a precondition and one that completes without errors show both sides.
Workspaces
tofu test always runs in the default workspace, and a test file can't set terraform.workspace. Code that reads terraform.workspace gets one value in every test. Add an optional input variable that defaults to terraform.workspace, and set it in the test:
variable "workspace" {
type = string
default = null
}
locals {
workspace = var.workspace == null ? terraform.workspace : var.workspace
}Providers with for_each
Two limits meet when the root builds one provider instance per key with for_each.
The variables in a test file, and -var on tofu test, don't reach the static evaluation of a provider for_each. The provider reads the key from the real workspace file while the rest of the run reads the fixture. A test of that for_each can only run on the real file.
A mock_provider with an alias replaces the provider block, and its for_each with it. Without its own for_each the mock has no instances, and the plan fails with "Provider instance not present". Give the mock the same for_each as the block it replaces.
Outputs between runs
A run block can use the outputs of an earlier run only when that run used command = apply. With mocked providers an apply creates nothing, so it is safe. A module without resources has nothing to apply at all. Use it to merge the real YAML files in one run, and to plan the module that consumes the result in the next.
Init after changes
After you add or rename a run block that uses a module, run tofu init again. Without it the test run stops on the new module call before it reaches your assertions.
Workarounds
Some properties can't be asserted on a plan. Two techniques cover most of them.
Text checks
When no planned value shows the property, read the .tf files with fileset() and file() and match them with regexall(). This test checks that every resource with a lifecycle block reads prevent_destroy from the local of its own type:
assert {
condition = [
for match in regexall("(?m)^resource \"([a-z_]+)\" \"([a-z]+)\" \\{\\n(?:[^}\\n].*\\n|\\n)*? lifecycle \\{\\n(?: .*\\n|\\n)*? prevent_destroy = (.*)$", var.module_tf) :
"${match[0]}.${match[1]} ${match[2]}"
] == [
"example_network.this local.prevent_destroy.networks",
"example_cluster.this local.prevent_destroy.clusters",
]
error_message = "each resource must read prevent_destroy for its own type"
}A text check breaks when someone reformats the code, so keep the expression short and make the message say what the file must contain. Mutate it like any other test: remove one line and see that it fails.
Resource types
A test can't list the resource types in a plan, and an assert can't name a type that no module declares. To keep a secret out of the state, scan the .tf files for every resource and data type and compare the list with the types you approved. A type that is not in the list fails the test until someone has read its schema (tofu providers schema -json) and found no sensitive attribute, or accepted the risk.
This is stricter than a check on the plan on purpose, because a resource with for_each = {} creates nothing and so passes a plan check, but its first key creates it. The test also fails when the scan finds none of a type that must exist, because then it read the wrong files. Add each type that has a sensitive attribute, such as an access key, to a separate list with the reason.
Running tests
Run OpenTofu from the pinned image, as your own user, so no file in the tree is owned by root:
docker run --rm --user "$(id -u):$(id -g)" --volume "$PWD:/work" --workdir /work \
ghcr.io/opentofu/opentofu:1.13.2 init -backend=false
docker run --rm --user "$(id -u):$(id -g)" --network none --volume "$PWD:/work" --workdir /work \
ghcr.io/opentofu/opentofu:1.13.2 testinit needs the network, because it downloads the providers into .terraform/. test doesn't, and --network none proves it: a test that uses the network fails instead of passing on a machine with credentials. Pin the image to a tag and run the same tag in CI, so a test result doesn't change with the version.
Run tofu test in the root and again in each module that has a tests/ directory, since each directory has its own test files and its own init.