statecheck

package

v1.13.0 Latest Latest Go to latest Published: May 16, 2025 License: MPL-2.0 Imports: 12 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/hashicorp/terraform-plugin-testing

Links

Open Source Insights

Documentation ¶

Overview ¶

Package statecheck contains the state check interface, request/response structs, and common state check implementations.

Index ¶

Examples ¶

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func CompareValue ¶ added in v1.10.0

func CompareValue(comparer compare.ValueComparer) *compareValue

CompareValue returns a state check that compares values retrieved from state using the supplied value comparer.

Types ¶

type CheckStateRequest ¶

type CheckStateRequest struct {
	// State represents a parsed state file, retrieved via the `terraform show -json` command.
	State *tfjson.State
}

CheckStateRequest is a request for an invoke of the CheckState function.

type CheckStateResponse ¶

type CheckStateResponse struct {
	// Error is used to report the failure of a state check assertion and is combined with other StateCheck errors
	// to be reported as a test failure.
	Error error
}

CheckStateResponse is a response to an invoke of the CheckState function.

type StateCheck ¶

type StateCheck interface {
	// CheckState should perform the state check.
	CheckState(context.Context, CheckStateRequest, *CheckStateResponse)
}

StateCheck defines an interface for implementing test logic that checks a state file and then returns an error if the state file does not match what is expected.

func CompareValueCollection ¶ added in v1.10.0

func CompareValueCollection(resourceAddressOne string, collectionPath []tfjsonpath.Path, resourceAddressTwo string, attributePath tfjsonpath.Path, comparer compare.ValueComparer) StateCheck

CompareValueCollection returns a state check that iterates over each element in a collection and compares the value of each element with the value of an attribute using the given value comparer.

func CompareValuePairs ¶ added in v1.10.0

func CompareValuePairs(resourceAddressOne string, attributePathOne tfjsonpath.Path, resourceAddressTwo string, attributePathTwo tfjsonpath.Path, comparer compare.ValueComparer) StateCheck

CompareValuePairs returns a state check that compares the value in state for the first given resource address and path with the value in state for the second given resource address and path using the supplied value comparer.

func ExpectIdentity ¶ added in v1.13.0

func ExpectIdentity(resourceAddress string, identity map[string]knownvalue.Check) StateCheck

ExpectIdentity returns a state check that asserts that the identity at the given resource matches a known object, where each map key represents an identity attribute name. The identity in state must exactly match the given object and any missing/extra attributes will raise a diagnostic.

This state check can only be used with managed resources that support resource identity. Resource identity is only supported in Terraform v1.12+

Example ¶

package main

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/tfversion"
)

func main() {
	// A typical test would accept *testing.T as a function parameter, for instance `func TestSomething(t *testing.T) { ... }`.
	t := &testing.T{}
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Resource identity support is only available in Terraform v1.12+
		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
			tfversion.SkipBelow(tfversion.Version1_12_0),
		},
		// Provider definition omitted. Assuming "test_resource" has an identity schema with "id" and "name" string attributes
		Steps: []resource.TestStep{
			{
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectIdentity(
						"test_resource.one",
						map[string]knownvalue.Check{
							"id":   knownvalue.StringExact("id-123"),
							"name": knownvalue.StringExact("John Doe"),
						},
					),
				},
			},
		},
	})
}

Output:

func ExpectIdentityValue ¶ added in v1.13.0

func ExpectIdentityValue(resourceAddress string, attributePath tfjsonpath.Path, identityValue knownvalue.Check) StateCheck

ExpectIdentityValue returns a state check that asserts that the specified identity attribute at the given resource matches a known value. This state check can only be used with managed resources that support resource identity.

Resource identity is only supported in Terraform v1.12+

Example ¶

package main

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"
	"github.com/hashicorp/terraform-plugin-testing/tfversion"
)

func main() {
	// A typical test would accept *testing.T as a function parameter, for instance `func TestSomething(t *testing.T) { ... }`.
	t := &testing.T{}
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Resource identity support is only available in Terraform v1.12+
		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
			tfversion.SkipBelow(tfversion.Version1_12_0),
		},
		// Provider definition omitted. Assuming "test_resource" has an identity schema with an "id" string attribute
		Steps: []resource.TestStep{
			{
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectIdentityValue(
						"test_resource.one",
						tfjsonpath.New("id"),
						knownvalue.StringExact("id-123"),
					),
				},
			},
		},
	})
}

Output:

func ExpectIdentityValueMatchesState ¶ added in v1.13.0

func ExpectIdentityValueMatchesState(resourceAddress string, attributePath tfjsonpath.Path) StateCheck

ExpectIdentityValueMatchesState returns a state check that asserts that the specified identity attribute at the given resource matches the same attribute in state. This is useful when an identity attribute is in sync with a state attribute of the same path.

This state check can only be used with managed resources that support resource identity. Resource identity is only supported in Terraform v1.12+

Example ¶

package main

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 main() {
	// A typical test would accept *testing.T as a function parameter, for instance `func TestSomething(t *testing.T) { ... }`.
	t := &testing.T{}
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Resource identity support is only available in Terraform v1.12+
		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
			tfversion.SkipBelow(tfversion.Version1_12_0),
		},
		// Provider definition omitted. Assuming "test_resource":
		//  - Has an identity schema with an "id" string attribute
		//  - Has a resource schema with an "id" string attribute
		Steps: []resource.TestStep{
			{
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					// The identity attribute and state attribute at "id" must match
					statecheck.ExpectIdentityValueMatchesState("test_resource.one", tfjsonpath.New("id")),
				},
			},
		},
	})
}

Output:

func ExpectIdentityValueMatchesStateAtPath ¶ added in v1.13.0

func ExpectIdentityValueMatchesStateAtPath(resourceAddress string, identityAttrPath, stateAttrPath tfjsonpath.Path) StateCheck

ExpectIdentityValueMatchesStateAtPath returns a state check that asserts that the specified identity attribute at the given resource matches the specified attribute in state. This is useful when an identity attribute is in sync with a state attribute of a different path.

This state check can only be used with managed resources that support resource identity. Resource identity is only supported in Terraform v1.12+

Example ¶

package main

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 main() {
	// A typical test would accept *testing.T as a function parameter, for instance `func TestSomething(t *testing.T) { ... }`.
	t := &testing.T{}
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Resource identity support is only available in Terraform v1.12+
		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
			tfversion.SkipBelow(tfversion.Version1_12_0),
		},
		// Provider definition omitted. Assuming "test_resource":
		//  - Has an identity schema with an "identity_id" string attribute
		//  - Has a resource schema with an "state_id" string attribute
		Steps: []resource.TestStep{
			{
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					// The identity attribute at "identity_id" and state attribute at "state_id" must match
					statecheck.ExpectIdentityValueMatchesStateAtPath(
						"test_resource.one",
						tfjsonpath.New("identity_id"),
						tfjsonpath.New("state_id"),
					),
				},
			},
		},
	})
}

Output:

func ExpectKnownOutputValue ¶

func ExpectKnownOutputValue(outputAddress string, knownValue knownvalue.Check) StateCheck

ExpectKnownOutputValue returns a state check that asserts that the specified value has a known type, and value.

Example ¶

package main

import (
	"testing"

	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
	"github.com/hashicorp/terraform-plugin-testing/knownvalue"
	"github.com/hashicorp/terraform-plugin-testing/statecheck"
)

func main() {
	// A typical test would accept *testing.T as a function parameter, for instance `func TestSomething(t *testing.T) { ... }`.
	t := &testing.T{}
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				Config: `resource "test_resource" "one" {
		          bool_attribute = true
		        }

		        output bool_output {
		          value = test_resource.one.bool_attribute
		        }
		        `,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownOutputValue(
						"bool_output",
						knownvalue.Bool(true),
					),
				},
			},
		},
	})
}

Output:

func ExpectKnownOutputValueAtPath ¶

func ExpectKnownOutputValueAtPath(outputAddress string, outputPath tfjsonpath.Path, knownValue knownvalue.Check) StateCheck

ExpectKnownOutputValueAtPath returns a state check that asserts that the specified output at the given path has a known type and value.

Example ¶

package main

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 main() {
	// A typical test would accept *testing.T as a function parameter, for instance `func TestSomething(t *testing.T) { ... }`.
	t := &testing.T{}
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				Config: `resource "test_resource" "one" {
		          bool_attribute = true
		        }

		        output test_resource_one_output {
		          value = test_resource.one
		        }
		        `,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownOutputValueAtPath(
						"test_resource_one_output",
						tfjsonpath.New("bool_attribute"),
						knownvalue.Bool(true),
					),
				},
			},
		},
	})
}

Output:

func ExpectKnownValue ¶

func ExpectKnownValue(resourceAddress string, attributePath tfjsonpath.Path, knownValue knownvalue.Check) StateCheck

ExpectKnownValue returns a state check that asserts that the specified attribute at the given resource has a known type and value.

Example ¶

package main

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 main() {
	// A typical test would accept *testing.T as a function parameter, for instance `func TestSomething(t *testing.T) { ... }`.
	t := &testing.T{}
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				Config: `resource "test_resource" "one" {
		          bool_attribute = true
		        }
		        `,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("bool_attribute"),
						knownvalue.Bool(true),
					),
				},
			},
		},
	})
}

Output:

func ExpectSensitiveValue ¶

func ExpectSensitiveValue(resourceAddress string, attributePath tfjsonpath.Path) StateCheck

ExpectSensitiveValue returns a state check that asserts that the specified attribute at the given resource has a sensitive value.

Due to implementation differences between the terraform-plugin-sdk and the terraform-plugin-framework, representation of sensitive values may differ. For example, terraform-plugin-sdk based providers may have less precise representations of sensitive values, such as marking whole maps as sensitive rather than individual element values.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL