Plan Checks
During the Lifecycle (config) and Refresh modes of a TestStep, the testing framework will run terraform plan before and after certain operations. For example, the Lifecycle (config) mode will run a plan before the terraform apply phase, as well as a plan before and after the terraform refresh phase.
These terraform plan operations results in a plan file and can be represented by this JSON format.
A plan check is a test assertion that inspects the plan file at a specific phase during the current testing mode. Multiple plan checks can be run at each defined phase, all assertion errors returned are aggregated, reported as a test failure, and all test cleanup logic is executed.
- Available plan phases for Lifecycle (config) mode are defined in the
TestStep.ConfigPlanChecksstruct - Available plan phases for Refresh mode are defined in the
TestStep.RefreshPlanChecksstruct - Import mode currently does not run any plan operations, and therefore does not support plan checks.
Refer to:
- General Plan Checks for built-in general purpose plan checks.
- Resource Plan Checks for built-in managed resource and data source plan checks.
- Output Plan Checks for built-in output-related plan checks.
- Custom Plan Checks for defining bespoke plan checks.
General Plan Checks
The terraform-plugin-testing module provides a package plancheck with built-in general plan checks for common use-cases:
| Check | Description |
|---|---|
ExpectEmptyPlan | Asserts the entire plan has no operations for apply. |
ExpectNonEmptyPlan | Asserts the entire plan contains at least one operation for apply. |
ExpectEmptyPlan Plan Check
One of the built-in plan checks, plancheck.ExpectEmptyPlan, is useful for determining a plan is a no-op prior to, for instance, the terraform apply phase.
Given the following example with the random provider, we have written a test that asserts that there are no planned changes:
package example_testimport ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/plancheck")func Test_Random_EmptyPlan(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ ExternalProviders: map[string]resource.ExternalProvider{ "random": { Source: "registry.terraform.io/hashicorp/random", }, }, Steps: []resource.TestStep{ { Config: `resource "random_string" "one" { length = 16 }`, }, { Config: `resource "random_string" "one" { length = 16 }`, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectEmptyPlan(), }, }, }, }, })}ExpectNonEmptyPlan Plan Check
One of the built-in plan checks, plancheck.ExpectNonEmptyPlan, is useful for determining whether a plan contains changes prior to, for instance, the terraform apply phase.
The following example, which uses the built-in terraform_data resource, asserts that there are planned changes:
package example_testimport ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/plancheck" "github.com/hashicorp/terraform-plugin-testing/tfversion")func Test_ExpectNonEmptyPlan_ResourceChanges(t *testing.T) { t.Parallel() resource.UnitTest(t, resource.TestCase{ TerraformVersionChecks: []tfversion.TerraformVersionCheck{ tfversion.SkipBelow(tfversion.Version1_4_0), }, ExternalProviders: map[string]resource.ExternalProvider{ "terraform": {Source: "terraform.io/builtin/terraform"}, }, Steps: []resource.TestStep{ { Config: `resource "terraform_data" "one" { triggers_replace = ["original"] }`, }, { Config: `resource "terraform_data" "one" { triggers_replace = ["new"] }`, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectNonEmptyPlan(), }, }, }, }, })}