Resource State Checks
The terraform-plugin-testing module provides a package statecheck with built-in managed resource, and data source state checks for common use-cases:
| Check | Description |
|---|---|
CompareValue | Compares sequential values of the specified attribute at the given managed resource, or data source, using the supplied value comparer. |
CompareValueCollection | Compares each item in the specified collection (e.g., list, set) attribute, with the second specified attribute at the given managed resources, or data sources, using the supplied value comparer. |
CompareValuePairs | Compares the specified attributes at the given managed resources, or data sources, using the supplied value comparer. |
ExpectKnownValue | Asserts the specified attribute at the given managed resource, or data source, has the specified type, and value. |
ExpectSensitiveValue | Asserts the specified attribute at the given managed resource, or data source, has a sensitive value. |
CompareValue State Check
The intended usage of statecheck.CompareValue(comparer) state check is to retrieve a specific resource attribute value from state during sequential test steps, and to compare these values using the supplied value comparer.
Refer to Value Comparers for details, and examples of the available compare.ValueComparer types that can be used with the CompareValue state check.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/compare" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/statecheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath") func TestCompareValue_CheckState_ValuesSame(t *testing.T) { t.Parallel() compareValuesSame := statecheck.CompareValue(compare.ValuesSame()) resource.Test(t, resource.TestCase{ // Provider definition omitted. Steps: []resource.TestStep{ { // Example resource containing a computed attribute named "computed_attribute" Config: `resource "test_resource" "one" {}`, ConfigStateChecks: []statecheck.StateCheck{ compareValuesSame.AddStateValue( "test_resource.one", tfjsonpath.New("computed_attribute"), ), }, }, { // Example resource containing a computed attribute named "computed_attribute" Config: `resource "test_resource" "one" {}`, ConfigStateChecks: []statecheck.StateCheck{ compareValuesSame.AddStateValue( "test_resource.one", tfjsonpath.New("computed_attribute"), ), }, }, }, })}CompareValueCollection State Check
The statecheck.CompareValueCollection(resourceAddressOne, collectionPath, resourceAddressTwo, attributePath, comparer) state check retrieves a specific collection (e.g., list, set) resource attribute, and a second resource attribute from state, and compares each of the items in the collection with the second attribute using the supplied value comparer.
Refer to Value Comparers for details, and examples of the available compare.ValueComparer types that can be used with the CompareValueCollection state check.
The following example illustrates how a CompareValue state check can be used to determine whether an attribute value appears in a collection attribute. Note that this is for illustrative purposes only, CompareValue should only be used for checking computed values.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/compare" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/statecheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath") func TestCompareValueCollection_CheckState_ValuesSame(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ // Provider definition omitted. Steps: []resource.TestStep{ { // The following is for illustrative purposes. State checking // should only be used for computed attributes Config: `resource "test_resource" "one" { string_attribute = "str" } resource "test_resource" "two" { list_attribute = [ "str2", "str", ] } `, ConfigStateChecks: []statecheck.StateCheck{ statecheck.CompareValueCollection( "test_resource.two", []tfjsonpath.Path{ tfjsonpath.New("list_attribute"), }, "test_resource.one", tfjsonpath.New("string_attribute"), compare.ValuesSame(), ), }, }, }, })}The following example illustrates how a CompareValue state check can be used to determine whether an object attribute value appears in a collection (e.g., list) attribute containing objects. Note that this is for illustrative purposes only, CompareValue should only be used for checking computed values.
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/compare" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/statecheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath") func TestCompareValueCollection_CheckState_ValuesSame(t *testing.T) { resource.Test(t, resource.TestCase{ // Provider definition omitted. Steps: []resource.TestStep{ { // The following is for illustrative purposes. State checking // should only be used for computed attributes Config: `resource "test_resource" "one" { list_nested_attribute = [ { a = false b = "two" }, { a = true b = "four" } ] single_nested_attribute = { a = true b = "four" } }`, ConfigStateChecks: []statecheck.StateCheck{ statecheck.CompareValueCollection( "test_resource.one", []tfjsonpath.Path{ tfjsonpath.New("list_nested_attribute"), tfjsonpath.New("b"), }, "test_resource.one", tfjsonpath.New("single_nested_attribute").AtMapKey("b"), compare.ValuesSame(), ), }, }, }, })}CompareValuePairs State Check
The statecheck.CompareValuePairs(resourceAddressOne, attributePathOne, resourceAddressTwo, attributePathTwo, comparer) state check provides a basis for retrieving a pair of attribute values, and comparing them using the supplied value comparer.
Refer to Value Comparers for details, and examples of the available compare.ValueComparer types that can be used with the CompareValuePairs state check.
package statecheck_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/compare" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/statecheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath") func TestCompareValuePairs_CheckState_ValuesSame(t *testing.T) { t.Parallel() resource.Test(t, resource.TestCase{ // Provider definition omitted. Steps: []resource.TestStep{ { // Example resource containing a computed attribute named "computed_attribute" Config: `resource "test_resource" "one" {} resource "test_resource" "two" {} `, ConfigStateChecks: []statecheck.StateCheck{ statecheck.CompareValuePairs( "test_resource.one", tfjsonpath.New("computed_attribute"), "test_resource.two", tfjsonpath.New("computed_attribute"), compare.ValuesSame(), ), }, }, }, })}ExpectKnownValue State Check
The statecheck.ExpectKnownValue(address, path, value) state check provides a basis for asserting that a specific resource attribute 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 ExpectKnownValue state 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/statecheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath") func TestExpectKnownValue_CheckState_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" {}`, ConfigStateChecks: []statecheck.StateCheck{ statecheck.ExpectKnownValue( "test_resource.one", tfjsonpath.New("computed_attribute"), knownvalue.Bool(true), ), }, }, }, })}ExpectSensitiveValue State Check
The statecheck.ExpectSensitiveValue(address, path) state check provides a basis for asserting that a specific resource attribute is marked as sensitive.
Note: In this example, a TerraformVersionCheck is being used to prevent execution of this test prior to Terraform version 1.4.6 (refer to the release notes for Terraform v1.4.6).
package example_test import ( "testing" "github.com/hashicorp/terraform-plugin-testing/helper/resource" "github.com/hashicorp/terraform-plugin-testing/statecheck" "github.com/hashicorp/terraform-plugin-testing/tfjsonpath" "github.com/hashicorp/terraform-plugin-testing/tfversion") func Test_ExpectSensitiveValue_SensitiveStringAttribute(t *testing.T) { t.Parallel() resource.UnitTest(t, resource.TestCase{ TerraformVersionChecks: []tfversion.TerraformVersionCheck{ tfversion.SkipBelow(tfversion.Version1_4_6), // StateResource.SensitiveValues }, // Provider definition omitted. Steps: []resource.TestStep{ { Config: ` resource "test_resource" "one" { sensitive_string_attribute = "test" } `, ConfigStateChecks: []statecheck.StateCheck{ statecheck.ExpectSensitiveValue("test_resource.one", tfjsonpath.New("sensitive_string_attribute")), }, }, }, })}