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")),
                },
            },
        },
    })
}

Resource State Checks

CompareValue State Check

CompareValueCollection State Check

CompareValuePairs State Check

ExpectKnownValue State Check

ExpectSensitiveValue State Check

`CompareValue` State Check

`CompareValueCollection` State Check

`CompareValuePairs` State Check

`ExpectKnownValue` State Check

`ExpectSensitiveValue` State Check