Output Plan Checks
The terraform-plugin-testing module provides a package plancheck with built-in output value plan checks for common use-cases:
| Check | Description |
|---|---|
ExpectKnownOutputValue | Asserts the output at the specified address has the specified type, and value. |
ExpectKnownOutputValueAtPath | Asserts the output at the specified address, and path has the specified type, and value. |
ExpectNullOutputValue | Asserts the output at the specified address has a null value. |
ExpectNullOutputValueAtPath | Asserts the output at the specified address, and path has a null value. |
ExpectUnknownOutputValue | Asserts the output at the specified address has an unknown value. |
ExpectUnknownOutputValueAtPath | Asserts the output at the specified address, and path has an unknown value. |
ExpectKnownOutputValue Plan Check
The plancheck.ExpectKnownOutputValue(address, value) plan check verifies that a specific output value has a known type, and value.
Refer to Known Value Checks for details, and examples of the available knownvalue.Check types that can be used with the ExpectKnownOutputValue plan check.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/knownvalue" "github.com/hashicorp/terraform-plugin-testing/plancheck" "github.com/hashicorp/terraform-plugin-testing/tfversion") func TestExpectKnownOutputValue_CheckPlan_Bool(t *testing.T) { t.Parallel() resource.UnitTest(t, resource.TestCase{ TerraformVersionChecks: []tfversion.TerraformVersionCheck{ tfversion.SkipBelow(tfversion.Version1_8_0), }, // Provider definition omitted. Steps: []resource.TestStep{ { Config: ` output "test" { value = provider::example::bool(true) }`, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectKnownOutputValue( "test", knownvalue.Bool(true), ), }, }, }, }, })}ExpectKnownOutputValueAtPath Plan Check
The plancheck.ExpectKnownOutputValueAtPath(address, path, value) plan check verifies that a specific output value at a defined path has a known type, and value.
Note: Prior to Terraform v1.3.0 a planned output is marked as fully unknown if any attribute is unknown.
Refer to Known Value Checks for details, and examples of the available knownvalue.Check types that can be used with the ExpectKnownOutputValueAtPath plan check.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/knownvalue" "github.com/hashicorp/terraform-plugin-testing/plancheck") func TestExpectKnownOutputValue_CheckPlan_Bool(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ // Provider definition omitted. Steps: []resource.TestStep{ { // Example resource containing a computed boolean attribute named "computed_attribute" Config: `resource "test_resource" "one" {} // Generally, it is not necessary to use an output to test a resource attribute, // the resource attribute should be tested directly instead. This is only shown as // an example. // // ConfigPlanChecks: resource.ConfigPlanChecks{ // PreApply: []plancheck.PlanCheck{ // plancheck.ExpectKnownValue( // "test_resource.one", // tfjsonpath.New("computed_attribute"), // knownvalue.Bool(true), // ), // }, // }, // // This is only shown as an example. output test { value = test_resource.one }`, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectKnownOutputValueAtPath( "test", tfjsonpath.New("computed_attribute"), knownvalue.Bool(true), ), }, }, }, }, })}ExpectNullOutputValue Plan Check
Note: ExpectNullOutputValue is deprecated. Use ExpectKnownOutputValue with knownvalue.Null() instead.
The built-in plancheck.ExpectNullOutputValue(address) plan check determines whether an output at the specified address has a null value.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/plancheck") func Test_ExpectNullOutputValue_StringAttribute_NullConfig(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ // Provider definition omitted. Steps: []resource.TestStep{ { Config: `resource "test_resource" "test" { string_attribute = null } output "string_attribute" { value = test_resource.test.string_attribute } `, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectNullOutputValue("string_attribute"), }, }, }, }, })}ExpectNullOutputValueAtPath Plan Check
Note: ExpectNullOutputValueAtPath is deprecated. Use ExpectKnownOutputValueAtPath with knownvalue.Null() instead.
The built-in plancheck.ExpectNullOutputValueAtPath(address, path) plan check determines whether an output at the specified address, and path has a null value. |
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/plancheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath" "github.com/hashicorp/terraform-plugin-testing/tfversion") func Test_ExpectNullOutputValueAtPath_StringAttribute_NullConfig(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ // Prior to Terraform v1.3.0 a planned output is marked as fully unknown // if any attribute is unknown. The id attribute within the test provider // is unknown. // Reference: https://github.com/hashicorp/terraform/blob/v1.3/CHANGELOG.md#130-september-21-2022 TerraformVersionChecks: []tfversion.TerraformVersionCheck{ tfversion.SkipBelow(tfversion.Version1_3_0), }, // Provider definition omitted. Steps: []resource.TestStep{ { Config: `resource "test_resource" "test" { string_attribute = null } output "resource" { value = test_resource.test } `, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectNullOutputValueAtPath("resource", tfjsonpath.New("string_attribute")), }, }, }, }, })}ExpectUnknownOutputValue Plan Check
One of the built-in plan checks, plancheck.ExpectUnknownOutputValue, determines whether an output value is unknown, for example, prior to the terraform apply phase.
The following uses the time_offset resource from the time provider, to illustrate usage of the plancheck.ExpectUnknownOutputValue, and verifies that day is unknown.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/plancheck") func Test_Time_Unknown(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ ExternalProviders: map[string]resource.ExternalProvider{ "time": { Source: "registry.terraform.io/hashicorp/time", }, }, Steps: []resource.TestStep{ { Config: `resource "time_offset" "one" { offset_days = 1 } output day { value = time_offset.one.day }`, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectUnknownOutputValue("day"), }, }, }, }, })}ExpectUnknownOutputValueAtPath Plan Check
Output values can contain objects or collections as well as primitive (e.g., string) values. Output value plan checks provide two forms for the plan checks, for example ExpectUnknownOutputValue(), and ExpectUnknownOutputValueAtPath(). The Expect<...>OutputValueAtPath() form is used to access a value contained within an object or collection, as illustrated in the following example.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/plancheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath") func Test_Time_Unknown(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ ExternalProviders: map[string]resource.ExternalProvider{ "time": { Source: "registry.terraform.io/hashicorp/time", }, }, Steps: []resource.TestStep{ { Config: `resource "time_offset" "one" { offset_days = 1 } output time_offset_one { value = time_offset.one }`, ConfigPlanChecks: resource.ConfigPlanChecks{ PreApply: []plancheck.PlanCheck{ plancheck.ExpectUnknownOutputValueAtPath("time_offset_one", tfjsonpath.New("day")), }, }, }, }, })}