resource

Documentation

Index

• Constants
• func AddTestSweepers(name string, s *Sweeper)
• func ParallelTest(t testing.T, c TestCase)
• func PrefixedUniqueId(prefix string) string
• func Retry(timeout time.Duration, f RetryFunc) error
• func RetryContext(ctx context.Context, timeout time.Duration, f RetryFunc) error
• func Test(t testing.T, c TestCase)
• func TestMain(m interface{ ... })
• func UniqueId() string
• func UnitTest(t testing.T, c TestCase)
• type AdditionalCLIOptions
• type ApplyOptions
• type CheckResourceAttrWithFunc
• type ConfigPlanChecks
• type ErrorCheckFunc
• type ExternalProvider
• type ImportStateCheckFunc
• type ImportStateIdFunc
• type NotFoundError
  • func (e *NotFoundError) Error() string
  • func (e *NotFoundError) Unwrap() error
• type PlanOptions
• type RefreshPlanChecks
• type RetryError
  • func NonRetryableError(err error) *RetryError
  • func RetryableError(err error) *RetryError
  • func (e *RetryError) Unwrap() error
• type RetryFunc
• type StateChangeConf
  • func (conf *StateChangeConf) WaitForState() (interface{}, error)
  • func (conf *StateChangeConf) WaitForStateContext(ctx context.Context) (interface{}, error)
• type StateRefreshFunc
• type Sweeper
• type SweeperFunc
• type TestCase
• type TestCheckFunc
  • func ComposeAggregateTestCheckFunc(fs ...TestCheckFunc) TestCheckFunc
  • func ComposeTestCheckFunc(fs ...TestCheckFunc) TestCheckFunc
  • func TestCheckModuleNoResourceAttr(mp []string, name string, key string) TestCheckFunc
  • func TestCheckModuleResourceAttr(mp []string, name string, key string, value string) TestCheckFunc
  • func TestCheckModuleResourceAttrPair(mpFirst []string, nameFirst string, keyFirst string, mpSecond []string, ...) TestCheckFunc
  • func TestCheckModuleResourceAttrPtr(mp []string, name string, key string, value *string) TestCheckFunc
  • func TestCheckModuleResourceAttrSet(mp []string, name string, key string) TestCheckFunc
  • func TestCheckNoResourceAttr(name, key string) TestCheckFunc
  • func TestCheckOutput(name, value string) TestCheckFunc
  • func TestCheckResourceAttr(name, key, value string) TestCheckFunc
  • func TestCheckResourceAttrPair(nameFirst, keyFirst, nameSecond, keySecond string) TestCheckFunc
  • func TestCheckResourceAttrPtr(name string, key string, value *string) TestCheckFunc
  • func TestCheckResourceAttrSet(name, key string) TestCheckFunc
  • func TestCheckResourceAttrWith(name, key string, checkValueFunc CheckResourceAttrWithFunc) TestCheckFunc
  • func TestCheckTypeSetElemAttr(name, attr, value string) TestCheckFunc
  • func TestCheckTypeSetElemAttrPair(nameFirst, keyFirst, nameSecond, keySecond string) TestCheckFunc
  • func TestCheckTypeSetElemNestedAttrs(name, attr string, values map[string]string) TestCheckFunc
  • func TestMatchOutput(name string, r *regexp.Regexp) TestCheckFunc
  • func TestMatchResourceAttr(name, key string, r *regexp.Regexp) TestCheckFunc
  • func TestMatchTypeSetElemNestedAttrs(name, attr string, values map[string]*regexp.Regexp) TestCheckFunc
  • func TestModuleMatchResourceAttr(mp []string, name string, key string, r *regexp.Regexp) TestCheckFunc
• type TestStep
• type TimeoutError
  • func (e *TimeoutError) Error() string
  • func (e *TimeoutError) Unwrap() error
• type UnexpectedStateError
  • func (e *UnexpectedStateError) Error() string
  • func (e *UnexpectedStateError) Unwrap() error

Examples

• ComposeAggregateTestCheckFunc
• TestCheckNoResourceAttr
• TestCheckResourceAttr (TypeBool)
• TestCheckResourceAttr (TypeFloat)
• TestCheckResourceAttr (TypeInt)
• TestCheckResourceAttr (TypeListAttribute)
• TestCheckResourceAttr (TypeListBlock)
• TestCheckResourceAttr (TypeMap)
• TestCheckResourceAttr (TypeString)
• TestCheckResourceAttrPair
• TestCheckResourceAttrSet
• TestCheckResourceAttrWith (TypeInt)
• TestCheckResourceAttrWith (TypeString)
• TestCheckTypeSetElemAttr
• TestCheckTypeSetElemAttrPair
• TestCheckTypeSetElemNestedAttrs
• TestMatchResourceAttr
• TestMatchTypeSetElemNestedAttrs

Constants

const (
	// Environment variable to enable acceptance tests using this package's
	// ParallelTest and Test functions whose TestCase does not enable the
	// IsUnitTest field. Defaults to disabled, in which each test will call
	// (*testing.T).Skip(). Can be set to any value to enable acceptance tests,
	// however "1" is conventional.
	EnvTfAcc = "TF_ACC"

	// Environment variable with hostname for the provider under acceptance
	// test. The hostname is the first portion of the full provider source
	// address, such as "example.com" in example.com/myorg/myprovider. Defaults
	// to "registry.terraform.io".
	//
	// Only required if any Terraform configuration set via the TestStep
	// type Config field includes a provider source, such as the terraform
	// configuration block required_providers attribute.
	EnvTfAccProviderHost = "TF_ACC_PROVIDER_HOST"

	// Environment variable with namespace for the provider under acceptance
	// test. The namespace is the second portion of the full provider source
	// address, such as "myorg" in registry.terraform.io/myorg/myprovider.
	// Defaults to "-" for Terraform 0.12-0.13 compatibility and "hashicorp".
	//
	// Only required if any Terraform configuration set via the TestStep
	// type Config field includes a provider source, such as the terraform
	// configuration block required_providers attribute.
	EnvTfAccProviderNamespace = "TF_ACC_PROVIDER_NAMESPACE"
)

Environment variables for acceptance testing. Additional environment variable constants can be found in the internal/plugintest package.

const TestEnvVar = EnvTfAcc

Deprecated: Use EnvTfAcc instead.

const UniqueIDSuffixLength = 26

UniqueIDSuffixLength is the string length of the suffix generated by PrefixedUniqueId. This can be used by length validation functions to ensure prefixes are the correct length for the target field.

Deprecated: Copy this value to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/id.UniqueSuffixLength.

const UniqueIdPrefix = `terraform-`

UniqueIdPrefix is a string prefix automatically added to return values of the UniqueId function.

Deprecated: Copy this value to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/id.UniquePrefix.

Functions

func AddTestSweepers

func AddTestSweepers(name string, s *Sweeper)

AddTestSweepers function adds a given name and Sweeper configuration pair to the internal sweeperFuncs map. Invoke this function to register a resource sweeper to be available for running when the -sweep flag is used with `go test`. Sweeper names must be unique to help ensure a given sweeper is only ran once per run.

func ParallelTest

func ParallelTest(t testing.T, c TestCase)

ParallelTest performs an acceptance test on a resource, allowing concurrency with other ParallelTest. The number of concurrent tests is controlled by the "go test" command -parallel flag.

Tests will fail if they do not properly handle conditions to allow multiple tests to occur against the same resource or service (e.g. random naming).

Test() function requirements and documentation also apply to this function.

func PrefixedUniqueId

func PrefixedUniqueId(prefix string) string

Helper for a resource to generate a unique identifier w/ given prefix

After the prefix, the ID consists of an incrementing 26 digit value (to match previous timestamp output). After the prefix, the ID consists of a timestamp and an incrementing 8 hex digit value The timestamp means that multiple IDs created with the same prefix will sort in the order of their creation, even across multiple terraform executions, as long as the clock is not turned back between calls, and as long as any given terraform execution generates fewer than 4 billion IDs.

Deprecated: Copy this function to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/id.PrefixedUnique.

func Retry

func Retry(timeout time.Duration, f RetryFunc) error

Retry is a basic wrapper around StateChangeConf that will just retry a function until it no longer returns an error.

Deprecated: Please use RetryContext to ensure proper plugin shutdown

func RetryContext

func RetryContext(ctx context.Context, timeout time.Duration, f RetryFunc) error

RetryContext is a basic wrapper around StateChangeConf that will just retry a function until it no longer returns an error.

Cancellation from the passed in context will propagate through to the underlying StateChangeConf

Deprecated: Copy this function to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.RetryContext.

func Test

func Test(t testing.T, c TestCase)

Test performs an acceptance test on a resource.

Tests are not run unless an environmental variable "TF_ACC" is set to some non-empty value. This is to avoid test cases surprising a user by creating real resources.

Tests will fail unless the verbose flag (`go test -v`, or explicitly the "-test.v" flag) is set. Because some acceptance tests take quite long, we require the verbose flag so users are able to see progress output.

Use the ParallelTest() function to automatically set (*testing.T).Parallel() to enable testing concurrency. Use the UnitTest() function to automatically set the TestCase type IsUnitTest field.

This function will automatically find or install Terraform CLI into a temporary directory, based on the following behavior:

• If the TF_ACC_TERRAFORM_PATH environment variable is set, that Terraform CLI binary is used if found and executable. If not found or executable, an error will be returned unless the TF_ACC_TERRAFORM_VERSION environment variable is also set.
• If the TF_ACC_TERRAFORM_VERSION environment variable is set, install and use that Terraform CLI version.
• If both the TF_ACC_TERRAFORM_PATH and TF_ACC_TERRAFORM_VERSION environment variables are unset, perform a lookup for the Terraform CLI binary based on the operating system PATH. If not found, the latest available Terraform CLI binary is installed.

Refer to the Env prefixed constants for additional details about these environment variables, and others, that control testing functionality.

func TestMain

func TestMain(m interface {
	Run() int
})

TestMain adds sweeper functionality to the "go test" command, otherwise tests are executed as normal. Most provider acceptance tests are written using the Test() function of this package, which imposes its own requirements and Terraform CLI behavior. Refer to that function's documentation for additional details.

Sweepers enable infrastructure cleanup functions to be included with resource definitions, typically so developers can remove all resources of that resource type from testing infrastructure in case of failures that prevented the normal resource destruction behavior of acceptance tests. Use the AddTestSweepers() function to configure available sweepers.

Sweeper flags added to the "go test" command:

-sweep: Comma-separated list of locations/regions to run available sweepers.
-sweep-allow-failures: Enable to allow other sweepers to run after failures.
-sweep-run: Comma-separated list of resource type sweepers to run. Defaults
        to all sweepers.

Refer to the Env prefixed constants for environment variables that further control testing functionality.

func UniqueId

func UniqueId() string

Helper for a resource to generate a unique identifier w/ default prefix

Deprecated: Copy this function to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/id.Unique.

func UnitTest

func UnitTest(t testing.T, c TestCase)

UnitTest is a helper to force the acceptance testing harness to run in the normal unit test suite. This should only be used for resource that don't have any external dependencies.

Test() function requirements and documentation also apply to this function.

Types

type AdditionalCLIOptions

type AdditionalCLIOptions struct {
	// Apply represents options to be passed to the `terraform apply` command.
	Apply ApplyOptions

	// Plan represents options to be passed to the `terraform plan` command.
	Plan PlanOptions
}

AdditionalCLIOptions allows an intentionally limited set of options to be passed to the Terraform CLI when executing test steps.

type ApplyOptions

type ApplyOptions struct {
	// AllowDeferral will pass the experimental `-allow-deferral` flag to the apply command.
	AllowDeferral bool
}

ApplyOptions represents options to be passed to the `terraform apply` command.

type CheckResourceAttrWithFunc

type CheckResourceAttrWithFunc func(value string) error

CheckResourceAttrWithFunc is the callback type used to apply a custom checking logic when using TestCheckResourceAttrWith and a value is found for the given name and key.

When this function returns an error, TestCheckResourceAttrWith will fail the check.

An experimental interface exists to potentially replace the CheckResourceAttrWithFunc functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckResourceAttrWith with that experimental interface, by using statecheck.ExpectKnownValue in combination with [knownvalue.StringRegexp]:

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

func TestExpectKnownValue_CheckState_String_Custom(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example resource containing a computed string attribute named "computed_attribute"
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("computed_attribute"),
						knownvalue.StringRegexp(regexp.MustCompile("str")),
				},
			},
		},
	})
}

type ConfigPlanChecks

type ConfigPlanChecks struct {
	// PreApply runs all plan checks in the slice. This occurs before the apply of a Config test is run. This slice cannot be populated
	// with TestStep.PlanOnly, as there is no PreApply plan run with that flag set. All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
	PreApply []plancheck.PlanCheck

	// PostApplyPreRefresh runs all plan checks in the slice. This occurs after the apply and before the refresh of a Config test is run.
	// All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
	PostApplyPreRefresh []plancheck.PlanCheck

	// PostApplyPostRefresh runs all plan checks in the slice. This occurs after the apply and refresh of a Config test are run.
	// All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
	PostApplyPostRefresh []plancheck.PlanCheck
}

ConfigPlanChecks defines the different points in a Config TestStep when plan checks can be run.

type ErrorCheckFunc

type ErrorCheckFunc func(error) error

ErrorCheckFunc is a function providers can use to handle errors.

type ExternalProvider

type ExternalProvider struct {
	VersionConstraint string // the version constraint for the provider
	Source            string // the provider source
}

ExternalProvider holds information about third-party providers that should be downloaded by Terraform as part of running the test step.

type ImportStateCheckFunc

type ImportStateCheckFunc func([]*terraform.InstanceState) error

ImportStateCheckFunc is the check function for ImportState tests

type ImportStateIdFunc

type ImportStateIdFunc func(*terraform.State) (string, error)

ImportStateIdFunc is an ID generation function to help with complex ID generation for ImportState tests.

type NotFoundError

type NotFoundError struct {
	LastError    error
	LastRequest  interface{}
	LastResponse interface{}
	Message      string
	Retries      int
}

NotFoundError represents when a StateRefreshFunc returns a nil result during a StateChangeConf waiter method and that StateChangeConf is configured for specific targets.

Deprecated: Copy this type to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.NotFoundError.

func (*NotFoundError) Error

func (e *NotFoundError) Error() string

Error returns the Message string, if non-empty, or a string indicating the resource could not be found.

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.NotFoundError.

func (*NotFoundError) Unwrap

func (e *NotFoundError) Unwrap() error

Unwrap returns the LastError, compatible with errors.Unwrap.

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.NotFoundError.

type PlanOptions

type PlanOptions struct {
	// AllowDeferral will pass the experimental `-allow-deferral` flag to the plan command.
	AllowDeferral bool
}

PlanOptions represents options to be passed to the `terraform plan` command.

type RefreshPlanChecks

type RefreshPlanChecks struct {
	// PostRefresh runs all plan checks in the slice. This occurs after the refresh of the Refresh test is run.
	// All errors by plan checks in this slice are aggregated, reported, and will result in a test failure.
	PostRefresh []plancheck.PlanCheck
}

RefreshPlanChecks defines the different points in a Refresh TestStep when plan checks can be run.

type RetryError

type RetryError struct {
	Err       error
	Retryable bool
}

RetryError is the required return type of RetryFunc. It forces client code to choose whether or not a given error is retryable.

Deprecated: Copy this type to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.RetryError.

func NonRetryableError

func NonRetryableError(err error) *RetryError

NonRetryableError is a helper to create a RetryError that's _not_ retryable from a given error. To prevent logic errors, will return an error when passed a nil error.

Deprecated: Copy this function to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.NonRetryableError.

func RetryableError

func RetryableError(err error) *RetryError

RetryableError is a helper to create a RetryError that's retryable from a given error. To prevent logic errors, will return an error when passed a nil error.

Deprecated: Copy this function to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.RetryableError.

func (*RetryError) Unwrap

func (e *RetryError) Unwrap() error

Unwrap returns the Err, compatible with errors.Unwrap.

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.RetryError.

type RetryFunc

type RetryFunc func() *RetryError

RetryFunc is the function retried until it succeeds.

Deprecated: Copy this type to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.RetryFunc.

type StateChangeConf

type StateChangeConf struct {
	Delay          time.Duration    // Wait this time before starting checks
	Pending        []string         // States that are "allowed" and will continue trying
	Refresh        StateRefreshFunc // Refreshes the current state
	Target         []string         // Target state
	Timeout        time.Duration    // The amount of time to wait before timeout
	MinTimeout     time.Duration    // Smallest time to wait before refreshes
	PollInterval   time.Duration    // Override MinTimeout/backoff and only poll this often
	NotFoundChecks int              // Number of times to allow not found (nil result from Refresh)

	// This is to work around inconsistent APIs
	ContinuousTargetOccurence int // Number of times the Target state has to occur continuously
}

StateChangeConf is the configuration struct used for `WaitForState`.

Deprecated: Copy this type to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.StateChangeConf.

func (*StateChangeConf) WaitForState

func (conf *StateChangeConf) WaitForState() (interface{}, error)

WaitForState watches an object and waits for it to achieve the state specified in the configuration using the specified Refresh() func, waiting the number of seconds specified in the timeout configuration.

Deprecated: Please use WaitForStateContext to ensure proper plugin shutdown

func (*StateChangeConf) WaitForStateContext

func (conf *StateChangeConf) WaitForStateContext(ctx context.Context) (interface{}, error)

WaitForStateContext watches an object and waits for it to achieve the state specified in the configuration using the specified Refresh() func, waiting the number of seconds specified in the timeout configuration.

If the Refresh function returns an error, exit immediately with that error.

If the Refresh function returns a state other than the Target state or one listed in Pending, return immediately with an error.

If the Timeout is exceeded before reaching the Target state, return an error.

Otherwise, the result is the result of the first call to the Refresh function to reach the target state.

Cancellation from the passed in context will cancel the refresh loop

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.StateChangeConf.

type StateRefreshFunc

type StateRefreshFunc func() (result interface{}, state string, err error)

StateRefreshFunc is a function type used for StateChangeConf that is responsible for refreshing the item being watched for a state change.

It returns three results. `result` is any object that will be returned as the final object after waiting for state change. This allows you to return the final updated object, for example an EC2 instance after refreshing it. A nil result represents not found.

`state` is the latest state of that object. And `err` is any error that may have happened while refreshing the state.

Deprecated: Copy this type to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.StateRefreshFunc.

type Sweeper

type Sweeper struct {
	// Name for sweeper. Must be unique to be ran by the Sweeper Runner
	Name string

	// Dependencies list the const names of other Sweeper functions that must be ran
	// prior to running this Sweeper. This is an ordered list that will be invoked
	// recursively at the helper/resource level
	Dependencies []string

	// Sweeper function that when invoked sweeps the Provider of specific
	// resources
	F SweeperFunc
}

type SweeperFunc

type SweeperFunc func(r string) error

SweeperFunc is a signature for a function that acts as a sweeper. It accepts a string for the region that the sweeper is to be ran in. This function must be able to construct a valid client for that region.

type TestCase

type TestCase struct {
	// IsUnitTest allows a test to run regardless of the TF_ACC
	// environment variable. This should be used with care - only for
	// fast tests on local resources (e.g. remote state with a local
	// backend) but can be used to increase confidence in correct
	// operation of Terraform without waiting for a full acctest run.
	IsUnitTest bool

	// PreCheck, if non-nil, will be called before any test steps are
	// executed. It will only be executed in the case that the steps
	// would run, so it can be used for some validation before running
	// acceptance tests, such as verifying that keys are setup.
	PreCheck func()

	// TerraformVersionChecks is a list of checks to run against
	// the Terraform CLI version which is running the testing.
	// Each check is executed in order, respecting the first skip
	// or fail response, unless the Any() meta check is also used.
	TerraformVersionChecks []tfversion.TerraformVersionCheck

	// ProviderFactories can be specified for the providers that are valid.
	//
	// This can also be specified at the TestStep level to enable per-step
	// differences in providers, however all provider specifications must
	// be done either at the TestCase level or TestStep level, otherwise the
	// testing framework will raise an error and fail the test.
	//
	// These are the providers that can be referenced within the test. Each key
	// is an individually addressable provider. Typically you will only pass a
	// single value here for the provider you are testing. Aliases are not
	// supported by the test framework, so to use multiple provider instances,
	// you should add additional copies to this map with unique names. To set
	// their configuration, you would reference them similar to the following:
	//
	//  provider "my_factory_key" {
	//    # ...
	//  }
	//
	//  resource "my_resource" "mr" {
	//    provider = my_factory_key
	//
	//    # ...
	//  }
	ProviderFactories map[string]func() (*schema.Provider, error)

	// ProtoV5ProviderFactories serves the same purpose as ProviderFactories,
	// but for protocol v5 providers defined using the terraform-plugin-go
	// ProviderServer interface.
	//
	// This can also be specified at the TestStep level to enable per-step
	// differences in providers, however all provider specifications must
	// be done either at the TestCase level or TestStep level, otherwise the
	// testing framework will raise an error and fail the test.
	ProtoV5ProviderFactories map[string]func() (tfprotov5.ProviderServer, error)

	// ProtoV6ProviderFactories serves the same purpose as ProviderFactories,
	// but for protocol v6 providers defined using the terraform-plugin-go
	// ProviderServer interface.
	// The version of Terraform used in acceptance testing must be greater
	// than or equal to v0.15.4 to use ProtoV6ProviderFactories.
	//
	// This can also be specified at the TestStep level to enable per-step
	// differences in providers, however all provider specifications must
	// be done either at the TestCase level or TestStep level, otherwise the
	// testing framework will raise an error and fail the test.
	ProtoV6ProviderFactories map[string]func() (tfprotov6.ProviderServer, error)

	// Providers is the ResourceProvider that will be under test.
	//
	// Deprecated: Providers is deprecated, please use ProviderFactories
	Providers map[string]*schema.Provider

	// ExternalProviders are providers the TestCase relies on that should
	// be downloaded from the registry during init.
	//
	// This can also be specified at the TestStep level to enable per-step
	// differences in providers, however all provider specifications must
	// be done either at the TestCase level or TestStep level, otherwise the
	// testing framework will raise an error and fail the test.
	//
	// This is generally unnecessary to set at the TestCase level, however
	// it has existing in the testing framework prior to the introduction of
	// TestStep level specification and was only necessary for performing
	// import testing where the configuration contained a provider outside the
	// one under test.
	ExternalProviders map[string]ExternalProvider

	// PreventPostDestroyRefresh can be set to true for cases where data sources
	// are tested alongside real resources
	PreventPostDestroyRefresh bool

	// CheckDestroy is called after the resource is finally destroyed
	// to allow the tester to test that the resource is truly gone.
	CheckDestroy TestCheckFunc

	// ErrorCheck allows providers the option to handle errors such as skipping
	// tests based on certain errors.
	//
	// This functionality is only intended for provider-controlled error
	// messaging. While in certain scenarios this can also catch testing logic
	// error messages, those messages are not protected by compatibility
	// promises.
	ErrorCheck ErrorCheckFunc

	// Steps are the apply sequences done within the context of the
	// same state. Each step can have its own check to verify correctness.
	Steps []TestStep

	// IDRefreshName is the name of the resource to check during ID-only
	// refresh testing, which ensures that a resource can be refreshed solely
	// by its identifier. This will default to the first non-nil primary
	// resource in the state. It runs every TestStep.
	//
	// While not deprecated, most resource tests should instead prefer using
	// TestStep.ImportState based testing as it works with multiple attribute
	// identifiers and also verifies resource import functionality.
	IDRefreshName string

	// IDRefreshIgnore is a list of configuration keys that will be ignored
	// during ID-only refresh testing.
	IDRefreshIgnore []string

	// WorkingDir sets the base directory where testing files used by the testing
	// module are generated. If WorkingDir is unset, a randomized, temporary
	// directory is used.
	//
	// Use the TF_ACC_PERSIST_WORKING_DIR environment variable, conventionally
	// set to "1", to persist any working directory files. Otherwise, this directory is
	// automatically cleaned up at the end of the TestCase.
	WorkingDir string

	// AdditionalCLIOptions allows an intentionally limited set of options to be passed
	// to the Terraform CLI when executing test steps.
	AdditionalCLIOptions *AdditionalCLIOptions
}

TestCase is a single acceptance test case used to test the apply/destroy lifecycle of a resource in a specific configuration.

When the destroy plan is executed, the config from the last TestStep is used to plan it.

Refer to the Env prefixed constants for environment variables that further control testing functionality.

type TestCheckFunc

type TestCheckFunc func(*terraform.State) error

TestCheckFunc is the callback type used with acceptance tests to check the state of a resource. The state passed in is the latest state known, or in the case of being after a destroy, it is the last known state when it was created.

func ComposeAggregateTestCheckFunc

func ComposeAggregateTestCheckFunc(fs ...TestCheckFunc) TestCheckFunc

ComposeAggregateTestCheckFunc lets you compose multiple TestCheckFuncs into a single TestCheckFunc.

As a user testing their provider, this lets you decompose your checks into smaller pieces more easily.

Unlike ComposeTestCheckFunc, ComposeAggergateTestCheckFunc runs _all_ of the TestCheckFuncs and aggregates failures.

Example

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field.
	// Any TestCheckFunc and number of TestCheckFunc may be used within the
	// function parameters. Any errors are combined and displayed together.
	resource.ComposeAggregateTestCheckFunc(
		resource.TestCheckResourceAttr("example_thing.test", "example_attribute1", "one"),
		resource.TestCheckResourceAttr("example_thing.test", "example_attribute2", "two"),
	)
}

func ComposeTestCheckFunc

func ComposeTestCheckFunc(fs ...TestCheckFunc) TestCheckFunc

ComposeTestCheckFunc lets you compose multiple TestCheckFuncs into a single TestCheckFunc.

As a user testing their provider, this lets you decompose your checks into smaller pieces more easily.

ComposeTestCheckFunc returns immediately on the first TestCheckFunc error. To aggregrate all errors, use ComposeAggregateTestCheckFunc instead.

func TestCheckModuleNoResourceAttr

func TestCheckModuleNoResourceAttr(mp []string, name string, key string) TestCheckFunc

TestCheckModuleNoResourceAttr - as per TestCheckNoResourceAttr but with support for non-root modules

Deprecated: This functionality is deprecated without replacement. The terraform-plugin-testing Go module is intended for provider testing, which should always be possible within the root module of a configuration. This functionality is a carryover of when this code was used within Terraform core to test both providers and modules. Modern testing implementations to verify interactions between modules should be tested in Terraform core or using tooling outside this Go module.

func TestCheckModuleResourceAttr

func TestCheckModuleResourceAttr(mp []string, name string, key string, value string) TestCheckFunc

TestCheckModuleResourceAttr - as per TestCheckResourceAttr but with support for non-root modules

Deprecated: This functionality is deprecated without replacement. The terraform-plugin-testing Go module is intended for provider testing, which should always be possible within the root module of a configuration. This functionality is a carryover of when this code was used within Terraform core to test both providers and modules. Modern testing implementations to verify interactions between modules should be tested in Terraform core or using tooling outside this Go module.

func TestCheckModuleResourceAttrPair

func TestCheckModuleResourceAttrPair(mpFirst []string, nameFirst string, keyFirst string, mpSecond []string, nameSecond string, keySecond string) TestCheckFunc

TestCheckModuleResourceAttrPair - as per TestCheckResourceAttrPair but with support for non-root modules

Deprecated: This functionality is deprecated without replacement. The terraform-plugin-testing Go module is intended for provider testing, which should always be possible within the root module of a configuration. This functionality is a carryover of when this code was used within Terraform core to test both providers and modules. Modern testing implementations to verify interactions between modules should be tested in Terraform core or using tooling outside this Go module.

func TestCheckModuleResourceAttrPtr

func TestCheckModuleResourceAttrPtr(mp []string, name string, key string, value *string) TestCheckFunc

TestCheckModuleResourceAttrPtr - as per TestCheckResourceAttrPtr but with support for non-root modules

Deprecated: This functionality is deprecated without replacement. The terraform-plugin-testing Go module is intended for provider testing, which should always be possible within the root module of a configuration. This functionality is a carryover of when this code was used within Terraform core to test both providers and modules. Modern testing implementations to verify interactions between modules should be tested in Terraform core or using tooling outside this Go module.

func TestCheckModuleResourceAttrSet

func TestCheckModuleResourceAttrSet(mp []string, name string, key string) TestCheckFunc

TestCheckModuleResourceAttrSet - as per TestCheckResourceAttrSet but with support for non-root modules

Deprecated: This functionality is deprecated without replacement. The terraform-plugin-testing Go module is intended for provider testing, which should always be possible within the root module of a configuration. This functionality is a carryover of when this code was used within Terraform core to test both providers and modules. Modern testing implementations to verify interactions between modules should be tested in Terraform core or using tooling outside this Go module.

func TestCheckNoResourceAttr

func TestCheckNoResourceAttr(name, key string) TestCheckFunc

TestCheckNoResourceAttr ensures no value exists in the state for the given name and key combination. The opposite of this TestCheckFunc is TestCheckResourceAttrSet. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the following special key syntax to inspect underlying values of a list or map attribute:

• .{NUMBER}: List value at index, e.g. .0 to inspect the first element.
• .{KEY}: Map value at key, e.g. .example to inspect the example key value.

While it is possible to check nested attributes under list and map attributes using the special key syntax, checking a list, map, or set attribute directly is not supported. Use TestCheckResourceAttr with the special .# or .% key syntax for those situations instead.

An experimental interface exists to potentially replace the TestCheckNoResourceAttr functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckNoResourceAttr with that experimental interface, by using statecheck.ExpectKnownValue with [knownvalue.Null]:

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

func TestExpectKnownValue_CheckState_AttributeNull(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" that has a null value
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("computed_attribute"),
						knownvalue.Null(),
					),
				},
			},
		},
	})
}

Example

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_string_attribute = "test-value"
	//     }
	//
	// The following TestCheckNoResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckNoResourceAttr("example_thing.test", "non_existent_attribute")
}

func TestCheckOutput

func TestCheckOutput(name, value string) TestCheckFunc

TestCheckOutput checks an output in the Terraform configuration

An experimental interface exists to potentially replace the TestCheckOutput functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckOutput with that experimental interface, by using statecheck.ExpectKnownOutputValue:

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

func TestExpectKnownOutputValue_CheckState_Bool(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
			tfversion.SkipBelow(tfversion.Version1_8_0),
		},
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example provider containing a provider-defined function named "bool"
				Config: `output "test" {
					value = provider::example::bool(true)
				}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownOutputValue("test", knownvalue.Bool(true)),
				},
			},
		},
	})
}

An experimental interface exists to potentially replace the TestCheckOutput functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckOutput with that experimental interface, by using statecheck.ExpectKnownOutputValueAtPath:

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 TestExpectKnownOutputValueAtPath_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" {}

				// Generally, it is not necessary to use an output to test a resource attribute,
				// the resource attribute should be tested directly instead, by inspecting the
				// value of the resource attribute. For instance:
				//
				// 		ConfigStateChecks: []statecheck.StateCheck{
				//			statecheck.ExpectKnownValue(
				//				"test_resource.one",
				//				tfjsonpath.New("computed_attribute"),
				//				knownvalue.Bool(true),
				//			),
				//		},
				//
				// This is only shown as an example.
				output test_resource_one_output {
					value = test_resource.one
				}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownOutputValueAtPath(
						"test_resource_one_output",
						tfjsonpath.New("computed_attribute"),
						knownvalue.Bool(true),
					),
				},
			},
		},
	})
}

func TestCheckResourceAttr

func TestCheckResourceAttr(name, key, value string) TestCheckFunc

TestCheckResourceAttr ensures a specific value is stored in state for the given name and key combination. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the following special key syntax to inspect list, map, and set attributes:

• .{NUMBER}: List value at index, e.g. .0 to inspect the first element. Use the TestCheckTypeSet* and TestMatchTypeSet* functions instead for sets.
• .{KEY}: Map value at key, e.g. .example to inspect the example key value.
• .#: Number of elements in list or set.
• .%: Number of elements in map.

The value parameter is the stringified data to check at the given key. Use the following attribute type rules to set the value:

• Boolean: "false" or "true".
• Float/Integer: Stringified number, such as "1.2" or "123".
• String: No conversion necessary.

An experimental interface exists to potentially replace the TestCheckResourceAttr functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckResourceAttr with that experimental interface, by using statecheck.ExpectKnownValue:

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

Example (TypeBool)

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_bool_attribute = true
	//     }
	//
	// The following TestCheckResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckResourceAttr("example_thing.test", "example_bool_attribute", "true")
}

Example (TypeFloat)

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_float_attribute = 1.2
	//     }
	//
	// The following TestCheckResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckResourceAttr("example_thing.test", "example_float_attribute", "1.2")
}

Example (TypeInt)

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_int_attribute = 123
	//     }
	//
	// The following TestCheckResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckResourceAttr("example_thing.test", "example_int_attribute", "123")
}

Example (TypeListAttribute)

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_list_attribute = ["value1", "value2", "value3"]
	//     }
	//
	// The following TestCheckResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.

	// Verify the list attribute contains 3 and only 3 elements
	resource.TestCheckResourceAttr("example_thing.test", "example_list_attribute.#", "3")

	// Verify each list attribute element value
	resource.TestCheckResourceAttr("example_thing.test", "example_list_attribute.0", "value1")
	resource.TestCheckResourceAttr("example_thing.test", "example_list_attribute.1", "value2")
	resource.TestCheckResourceAttr("example_thing.test", "example_list_attribute.2", "value3")
}

Example (TypeListBlock)

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_list_block {
	//         example_string_attribute = "test-nested-value"
	//       }
	//     }
	//
	// The following TestCheckResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.

	// Verify the list block contains 1 and only 1 definition
	resource.TestCheckResourceAttr("example_thing.test", "example_list_block.#", "1")

	// Verify a first list block attribute value
	resource.TestCheckResourceAttr("example_thing.test", "example_list_block.0.example_string_attribute", "test-nested-value")
}

Example (TypeMap)

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_map_attribute = {
	//         key1 = "value1"
	//         key2 = "value2"
	//         key3 = "value3"
	//       }
	//     }
	//
	// The following TestCheckResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.

	// Verify the map attribute contains 3 and only 3 elements
	resource.TestCheckResourceAttr("example_thing.test", "example_map_attribute.%", "3")

	// Verify each map attribute element value
	resource.TestCheckResourceAttr("example_thing.test", "example_map_attribute.key1", "value1")
	resource.TestCheckResourceAttr("example_thing.test", "example_map_attribute.key2", "value2")
	resource.TestCheckResourceAttr("example_thing.test", "example_map_attribute.key3", "value3")
}

Example (TypeString)

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_string_attribute = "test-value"
	//     }
	//
	// The following TestCheckResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckResourceAttr("example_thing.test", "example_string_attribute", "test-value")
}

func TestCheckResourceAttrPair

func TestCheckResourceAttrPair(nameFirst, keyFirst, nameSecond, keySecond string) TestCheckFunc

TestCheckResourceAttrPair ensures value equality in state between the first given name and key combination and the second name and key combination. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The first and second names may use any combination of managed resources and/or data sources.

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the following special key syntax to inspect list, map, and set attributes:

• .{NUMBER}: List value at index, e.g. .0 to inspect the first element. Use the TestCheckTypeSet* and TestMatchTypeSet* functions instead for sets.
• .{KEY}: Map value at key, e.g. .example to inspect the example key value.
• .#: Number of elements in list or set.
• .%: Number of elements in map.

Example

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test1" {
	//       example_string_attribute = "test-value"
	//     }
	//
	//     resource "example_thing" "test2" {
	//       example_string_attribute = example_thing.test1.example_string_attribute
	//     }
	//
	// The following TestCheckResourceAttrPair can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckResourceAttrPair(
		"example_thing.test1",
		"example_string_attribute",
		"example_thing.test2",
		"example_string_attribute",
	)
}

func TestCheckResourceAttrPtr

func TestCheckResourceAttrPtr(name string, key string, value *string) TestCheckFunc

TestCheckResourceAttrPtr is like TestCheckResourceAttr except the value is a pointer so that it can be updated while the test is running. It will only be dereferenced at the point this step is run.

Refer to the TestCheckResourceAttr documentation for more information about setting the name, key, and value parameters.

func TestCheckResourceAttrSet

func TestCheckResourceAttrSet(name, key string) TestCheckFunc

TestCheckResourceAttrSet ensures any value exists in the state for the given name and key combination. The opposite of this TestCheckFunc is TestCheckNoResourceAttr. State value checking is only recommended for testing Computed attributes and attribute defaults.

Use this as a last resort when a more specific TestCheckFunc cannot be implemented, such as:

• TestCheckResourceAttr: Equality checking of non-TypeSet state value.
• TestCheckResourceAttrPair: Equality checking of non-TypeSet state value, based on another state value.
• TestCheckTypeSet*: Equality checking of TypeSet state values.
• TestMatchResourceAttr: Regular expression checking of non-TypeSet state value.
• TestMatchTypeSet*: Regular expression checking on TypeSet state values.

For managed resources, the name parameter is combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the following special key syntax to inspect underlying values of a list or map attribute:

• .{NUMBER}: List value at index, e.g. .0 to inspect the first element
• .{KEY}: Map value at key, e.g. .example to inspect the example key value

While it is possible to check nested attributes under list and map attributes using the special key syntax, checking a list, map, or set attribute directly is not supported. Use TestCheckResourceAttr with the special .# or .% key syntax for those situations instead.

An experimental interface exists to potentially replace the TestCheckResourceAttrSet functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckResourceAttrSet with that experimental interface, by using [ExpectKnownValue] with [knownvalue.NotNull]:

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_AttributeFound(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" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("computed_attribute"),
						knownvalue.NotNull(),
					),
				},
			},
		},
	})
}

Example

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_string_attribute = "test-value"
	//     }
	//
	// The following TestCheckResourceAttrSet can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckResourceAttrSet("example_thing.test", "example_string_attribute")
}

func TestCheckResourceAttrWith

func TestCheckResourceAttrWith(name, key string, checkValueFunc CheckResourceAttrWithFunc) TestCheckFunc

TestCheckResourceAttrWith ensures a value stored in state for the given name and key combination, is checked against a custom logic. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the following special key syntax to inspect list, map, and set attributes:

• .{NUMBER}: List value at index, e.g. .0 to inspect the first element. Use the TestCheckTypeSet* and TestMatchTypeSet* functions instead for sets.
• .{KEY}: Map value at key, e.g. .example to inspect the example key value.
• .#: Number of elements in list or set.
• .%: Number of elements in map.

The checkValueFunc parameter is a CheckResourceAttrWithFunc, and it's provided with the attribute value to apply a custom checking logic, if it was found in the state. The function must return an error for the check to fail, or `nil` to succeed.

An experimental interface exists to potentially replace the TestCheckResourceAttrWith functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckResourceAttrWith with that experimental interface, by using statecheck.ExpectKnownValue in combination with [knownvalue.StringRegexp]:

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

func TestExpectKnownValue_CheckState_String_Custom(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example resource containing a computed string attribute named "computed_attribute"
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("computed_attribute"),
						knownvalue.StringRegexp(regexp.MustCompile("str")),
				},
			},
		},
	})
}

Example (TypeInt)

package main

import (
	"fmt"
	"strconv"

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

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_int_attribute = 10
	//     }
	//
	// The following TestCheckResourceAttrWith can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.

	// Verify the attribute value is an integer, and it's between 5 (included) and 20 (excluded)
	resource.TestCheckResourceAttrWith("example_thing.test", "example_string_attribute", func(value string) error {
		valueInt, err := strconv.Atoi(value)
		if err != nil {
			return err
		}

		if valueInt < 5 && valueInt >= 20 {
			return fmt.Errorf("should be between 5 and 20")
		}
		return nil
	})
}

Example (TypeString)

package main

import (
	"fmt"

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

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_string_attribute = "Very long string..."
	//     }
	//
	// The following TestCheckResourceAttrWith can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.

	// Verify the attribute value string length is above 1000
	resource.TestCheckResourceAttrWith("example_thing.test", "example_string_attribute", func(value string) error {
		if len(value) <= 1000 {
			return fmt.Errorf("should be longer than 1000 characters")
		}
		return nil
	})
}

func TestCheckTypeSetElemAttr

func TestCheckTypeSetElemAttr(name, attr, value string) TestCheckFunc

TestCheckTypeSetElemAttr ensures a specific value is stored in state for the given name and key combination under a list or set. Use this TestCheckFunc in preference over non-set variants to simplify testing code and ensure compatibility with indicies, which can easily change with schema changes. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is a combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the sentinel value '*' to replace the element indexing into a list or set. The sentinel value can be used for each list or set index, if there are multiple lists or sets in the attribute path.

The value parameter is the stringified data to check at the given key. Use the following attribute type rules to set the value:

• Boolean: "false" or "true".
• Float/Integer: Stringified number, such as "1.2" or "123".
• String: No conversion necessary.

An experimental interface exists to potentially replace the TestCheckTypeSetElemAttr functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckTypeSetElemAttr with that experimental interface, by using statecheck.ExpectKnownValue in combination with [knownvalue.SetExact]:

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_Set(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example resource containing a computed set attribute named "computed_attribute"
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("computed_attribute"),
						knownvalue.SetExact([]knownvalue.Check{
							knownvalue.StringExact("value2"),
							knownvalue.StringExact("value1"),
						}),
					),
				},
			},
		},
	})
}

Example

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_set_attribute = ["value1", "value2", "value3"]
	//     }
	//
	// The following TestCheckTypeSetElemAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckTypeSetElemAttr("example_thing.test", "example_set_attribute.*", "value1")
	resource.TestCheckTypeSetElemAttr("example_thing.test", "example_set_attribute.*", "value2")
	resource.TestCheckTypeSetElemAttr("example_thing.test", "example_set_attribute.*", "value3")
}

func TestCheckTypeSetElemAttrPair

func TestCheckTypeSetElemAttrPair(nameFirst, keyFirst, nameSecond, keySecond string) TestCheckFunc

TestCheckTypeSetElemAttrPair ensures value equality in state between the first given name and key combination and the second name and key combination. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is a combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The first and second names may use any combination of managed resources and/or data sources.

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the sentinel value '*' to replace the element indexing into a list or set. The sentinel value can be used for each list or set index, if there are multiple lists or sets in the attribute path.

Example

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     data "example_lookup" "test" {
	//       example_string_attribute = "test-value"
	//     }
	//
	//     resource "example_thing" "test" {
	//       example_set_attribute = [
	//         data.example_lookup.test.example_string_attribute,
	//         "another-test-value",
	//       ]
	//     }
	//
	// The following TestCheckTypeSetElemAttrPair can be written to assert
	// against the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckTypeSetElemAttrPair(
		"example_thing.test",
		"example_set_attribute.*",
		"data.example_lookup.test",
		"example_string_attribute",
	)
}

func TestCheckTypeSetElemNestedAttrs

func TestCheckTypeSetElemNestedAttrs(name, attr string, values map[string]string) TestCheckFunc

TestCheckTypeSetElemNestedAttrs ensures a subset map of values is stored in state for the given name and key combination of attributes nested under a list or set block. Use this TestCheckFunc in preference over non-set variants to simplify testing code and ensure compatibility with indicies, which can easily change with schema changes. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is a combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the sentinel value '*' to replace the element indexing into a list or set. The sentinel value can be used for each list or set index, if there are multiple lists or sets in the attribute path.

The values parameter is the map of attribute names to attribute values expected to be nested under the list or set.

You may check for unset nested attributes, however this will also match keys set to an empty string. Use a map with at least 1 non-empty value.

map[string]string{
  "key1": "value",
  "key2": "",
}

If the values map is not granular enough, it is possible to match an element you were not intending to in the set. Provide the most complete mapping of attributes possible to be sure the unique element exists.

An experimental interface exists to potentially replace the TestCheckTypeSetElemNestedAttrs functionality in the future and feedback would be appreciated. This example performs the same check as TestCheckTypeSetElemNestedAttrs with that experimental interface, by using statecheck.ExpectKnownValue in combination with [knownvalue.SetPartial]:

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_SetPartial(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example resource containing a computed set attribute named "computed_attribute"
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("computed_attribute"),
						knownvalue.SetPartial([]knownvalue.Check{
							knownvalue.StringExact("value2"),
						}),
					),
				},
			},
		},
	})
}

Example

package main

import (
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_set_block {
	//         key1 = "value1a"
	//         key2 = "value2a"
	//         key3 = "value3a"
	//       }
	//
	//       example_set_block {
	//         key1 = "value1b"
	//         key2 = "value2b"
	//         key3 = "value3b"
	//       }
	//     }
	//
	// The following TestCheckTypeSetElemNestedAttrs can be written to assert
	// against the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestCheckTypeSetElemNestedAttrs(
		"example_thing.test",
		"example_set_block.*",
		map[string]string{
			"key1": "value1a",
			"key2": "value2a",
			"key3": "value3a",
		},
	)
	resource.TestCheckTypeSetElemNestedAttrs(
		"example_thing.test",
		"example_set_block.*",
		map[string]string{
			"key1": "value1b",
			"key2": "value2b",
			"key3": "value3b",
		},
	)
}

func TestMatchOutput

func TestMatchOutput(name string, r *regexp.Regexp) TestCheckFunc

TestMatchOutput ensures a value matching a regular expression is stored in state for the given name. State value checking is only recommended for testing Computed attributes and attribute defaults.

An experimental interface exists to potentially replace the TestMatchOutput functionality in the future and feedback would be appreciated. This example performs the same check as TestMatchOutput with that experimental interface, by using statecheck.ExpectKnownOutputValueAtPath in combination with [knownvalue.StringRegexp]:

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

func TestExpectKnownOutputValueAtPath_CheckState_String_Custom(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example resource containing a computed string 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, by inspecting the
				// value of the resource attribute. For instance:
				//
				// 		ConfigStateChecks: []statecheck.StateCheck{
				//			statecheck.ExpectKnownValue(
				//				"test_resource.one",
				//				tfjsonpath.New("computed_attribute"),
				//				knownvalue.StringRegexp(regexp.MustCompile("str")),
				//			),
				//		},
				//
				// This is only shown as an example.
				output test_resource_one_output {
					value = test_resource.one
				}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownOutputValueAtPath(
						"test_resource_one_output",
						tfjsonpath.New("computed_attribute"),
						knownvalue.StringRegexp(regexp.MustCompile("str"),
					),
				},
			},
		},
	})
}

func TestMatchResourceAttr

func TestMatchResourceAttr(name, key string, r *regexp.Regexp) TestCheckFunc

TestMatchResourceAttr ensures a value matching a regular expression is stored in state for the given name and key combination. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the following special key syntax to inspect list, map, and set attributes:

• .{NUMBER}: List value at index, e.g. .0 to inspect the first element. Use the TestCheckTypeSet* and TestMatchTypeSet* functions instead for sets.
• .{KEY}: Map value at key, e.g. .example to inspect the example key value.
• .#: Number of elements in list or set.
• .%: Number of elements in map.

The value parameter is a compiled regular expression. A typical pattern is using the regexp.MustCompile() function, which will automatically ensure the regular expression is supported by the Go regular expression handlers during compilation.

An experimental interface exists to potentially replace the TestMatchResourceAttr functionality in the future and feedback would be appreciated. This example performs the same check as TestMatchResourceAttr with that experimental interface, by using statecheck.ExpectKnownValue in combination with [knownvalue.StringRegexp]:

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

func TestExpectKnownValue_CheckState_String_Custom(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example resource containing a computed string attribute named "computed_attribute"
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("computed_attribute"),
						knownvalue.StringRegexp(regexp.MustCompile("str")),
				},
			},
		},
	})
}

Example

package main

import (
	"regexp"

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

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_string_attribute = "test-value"
	//     }
	//
	// The following TestMatchResourceAttr can be written to assert against
	// the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestMatchResourceAttr("example_thing.test", "example_string_attribute", regexp.MustCompile(`^test-`))
}

func TestMatchTypeSetElemNestedAttrs

func TestMatchTypeSetElemNestedAttrs(name, attr string, values map[string]*regexp.Regexp) TestCheckFunc

TestMatchTypeSetElemNestedAttrs ensures a subset map of values, compared by regular expressions, is stored in state for the given name and key combination of attributes nested under a list or set block. Use this TestCheckFunc in preference over non-set variants to simplify testing code and ensure compatibility with indicies, which can easily change with schema changes. State value checking is only recommended for testing Computed attributes and attribute defaults.

For managed resources, the name parameter is a combination of the resource type, a period (.), and the name label. The name for the below example configuration would be "myprovider_thing.example".

resource "myprovider_thing" "example" { ... }

For data sources, the name parameter is a combination of the keyword "data", a period (.), the data source type, a period (.), and the name label. The name for the below example configuration would be "data.myprovider_thing.example".

data "myprovider_thing" "example" { ... }

The key parameter is an attribute path in Terraform CLI 0.11 and earlier "flatmap" syntax. Keys start with the attribute name of a top-level attribute. Use the sentinel value '*' to replace the element indexing into a list or set. The sentinel value can be used for each list or set index, if there are multiple lists or sets in the attribute path.

The values parameter is the map of attribute names to regular expressions for matching attribute values expected to be nested under the list or set.

You may check for unset nested attributes, however this will also match keys set to an empty string. Use a map with at least 1 non-empty value.

map[string]*regexp.Regexp{
  "key1": regexp.MustCompile(`^value`),
  "key2": regexp.MustCompile(`^$`),
}

If the values map is not granular enough, it is possible to match an element you were not intending to in the set. Provide the most complete mapping of attributes possible to be sure the unique element exists.

If the values map is not granular enough, it is possible to match an element you were not intending to in the set. Provide the most complete mapping of attributes possible to be sure the unique element exists.

An experimental interface exists to potentially replace the TestMatchTypeSetElemNestedAttrs functionality in the future and feedback would be appreciated. This example performs the same check as TestMatchTypeSetElemNestedAttrs with that experimental interface, by using statecheck.ExpectKnownValue in combination with [knownvalue.SetExact], with a nested [knownvalue.StringRegexp]:

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_SetNestedBlock_Custom(t *testing.T) {
	t.Parallel()

	resource.Test(t, resource.TestCase{
		// Provider definition omitted.
		Steps: []resource.TestStep{
			{
				// Example resource containing a set nested block name "block" which contains a computed string attribute named "computed_attribute"
				Config: `resource "test_resource" "one" {}`,
				ConfigStateChecks: []statecheck.StateCheck{
					statecheck.ExpectKnownValue(
						"test_resource.one",
						tfjsonpath.New("block"),
						knownvalue.SetExact([]knownvalue.Check{
							knownvalue.MapExact(map[string]knownvalue.Check{
								"computed_attribute": knownvalue.StringRegexp(regexp.MustCompile("str")),
							}),
							knownvalue.MapExact(map[string]knownvalue.Check{
								"computed_attribute": knownvalue.StringRegexp(regexp.MustCompile("rts")),
							}),
						}),
					),
				},
			},
		},
	})
}

Example

package main

import (
	"regexp"

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

func main() {
	// This function is typically implemented in a TestStep type Check field,
	// wrapped with ComposeAggregateTestCheckFunc to combine results from
	// multiple checks.
	//
	// Given the following example configuration:
	//
	//     resource "example_thing" "test" {
	//       example_set_block {
	//         key1 = "value1a"
	//         key2 = "value2a"
	//         key3 = "value3a"
	//       }
	//
	//       example_set_block {
	//         key1 = "value1b"
	//         key2 = "value2b"
	//         key3 = "value3b"
	//       }
	//     }
	//
	// The following TestMatchTypeSetElemNestedAttrs can be written to assert
	// against the expected state values.
	//
	// NOTE: State value checking is only necessary for Computed attributes,
	//       as the testing framework will automatically return test failures
	//       for configured attributes that mismatch the saved state, however
	//       this configuration and test is shown for illustrative purposes.
	resource.TestMatchTypeSetElemNestedAttrs(
		"example_thing.test",
		"example_set_block.*",
		map[string]*regexp.Regexp{
			"key1": regexp.MustCompile(`1a$`),
			"key2": regexp.MustCompile(`2a$`),
			"key3": regexp.MustCompile(`3a$`),
		},
	)
	resource.TestMatchTypeSetElemNestedAttrs(
		"example_thing.test",
		"example_set_block.*",
		map[string]*regexp.Regexp{
			"key1": regexp.MustCompile(`1b$`),
			"key2": regexp.MustCompile(`2b$`),
			"key3": regexp.MustCompile(`3b$`),
		},
	)
}

func TestModuleMatchResourceAttr

func TestModuleMatchResourceAttr(mp []string, name string, key string, r *regexp.Regexp) TestCheckFunc

TestModuleMatchResourceAttr - as per TestMatchResourceAttr but with support for non-root modules

Deprecated: This functionality is deprecated without replacement. The terraform-plugin-testing Go module is intended for provider testing, which should always be possible within the root module of a configuration. This functionality is a carryover of when this code was used within Terraform core to test both providers and modules. Modern testing implementations to verify interactions between modules should be tested in Terraform core or using tooling outside this Go module.

type TestStep

type TestStep struct {
	// ResourceName should be set to the name of the resource
	// that is being tested. Example: "aws_instance.foo". Various test
	// modes use this to auto-detect state information.
	//
	// This is only required if the test mode settings below say it is
	// for the mode you're using.
	ResourceName string

	// PreConfig is called before the Config is applied to perform any per-step
	// setup that needs to happen. This is called regardless of "test mode"
	// below.
	PreConfig func()

	// Taint is a list of resource addresses to taint prior to the execution of
	// the step. Be sure to only include this at a step where the referenced
	// address will be present in state, as it will fail the test if the resource
	// is missing.
	//
	// This option is ignored on ImportState tests, and currently only works for
	// resources in the root module path.
	Taint []string

	// Config a string of the configuration to give to Terraform. If this
	// is set, then the TestCase will execute this step with the same logic
	// as a `terraform apply`. If both Config and ConfigDirectory are set
	// an error will be returned.
	//
	// JSON Configuration Syntax can be used and is assumed whenever Config
	// contains valid JSON.
	//
	// Only one of Config, ConfigDirectory or ConfigFile can be set
	// otherwise an error will be returned.
	Config string

	// ConfigDirectory is a function which returns a function that
	// accepts config.TestStepProviderConfig and returns a string
	// representing a directory that contains Terraform
	// configuration files.
	//
	// There are helper functions in the [config] package that can be used,
	// such as:
	//
	//   - [config.StaticDirectory]
	//   - [config.TestNameDirectory]
	//   - [config.TestStepDirectory]
	//
	// When running Terraform operations for the test, Terraform will
	// be executed with copies of the files of this directory as its
	// working directory. Only one of Config, ConfigDirectory or
	// ConfigFile can be set otherwise an error will be returned.
	ConfigDirectory config.TestStepConfigFunc

	// ConfigFile is a function which returns a function that
	// accepts config.TestStepProviderConfig and returns a string
	// representing a file that contains Terraform configuration.
	//
	// There are helper functions in the [config] package that can be used,
	// such as:
	//
	//   - [config.StaticFile]
	//   - [config.TestNameFile]
	//   - [config.TestStepFile]
	//
	// When running Terraform operations for the test, Terraform will
	// be executed with a copy of the file as its working directory.
	// Only one of Config, ConfigDirectory or ConfigFile can be set
	// otherwise an error will be returned.
	ConfigFile config.TestStepConfigFunc

	// ConfigVariables is a map defining variables for use in conjunction
	// with Terraform configuration. If this map is populated then it
	// will be used to assemble an *.auto.tfvars.json which will be
	// written into the working directory. Any variables that are
	// defined within the Terraform configuration that have a matching
	// variable definition in *.auto.tfvars.json will have their value
	// substituted when the acceptance test is executed.
	ConfigVariables config.Variables

	// Check is called after the Config is applied. Use this step to
	// make your own API calls to check the status of things, and to
	// inspect the format of the ResourceState itself.
	//
	// If an error is returned, the test will fail. In this case, a
	// destroy plan will still be attempted.
	//
	// If this is nil, no check is done on this step.
	Check TestCheckFunc

	// Destroy will create a destroy plan if set to true.
	Destroy bool

	// ExpectNonEmptyPlan can be set to true for specific types of tests that are
	// looking to verify that a diff occurs
	ExpectNonEmptyPlan bool

	// ExpectError allows the construction of test cases that we expect to fail
	// with an error. The specified regexp must match against the error for the
	// test to pass.
	//
	// This functionality is only intended for provider-controlled error
	// messaging. While in certain scenarios this can also catch testing logic
	// error messages, those messages are not protected by compatibility
	// promises.
	ExpectError *regexp.Regexp

	// ConfigPlanChecks allows assertions to be made against the plan file at different points of a Config (apply) test using a plan check.
	// Custom plan checks can be created by implementing the [PlanCheck] interface, or by using a PlanCheck implementation from the provided [plancheck] package
	//
	// [PlanCheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck#PlanCheck
	// [plancheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck
	ConfigPlanChecks ConfigPlanChecks

	// RefreshPlanChecks allows assertions to be made against the plan file at different points of a Refresh test using a plan check.
	// Custom plan checks can be created by implementing the [PlanCheck] interface, or by using a PlanCheck implementation from the provided [plancheck] package
	//
	// [PlanCheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck#PlanCheck
	// [plancheck]: https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/plancheck
	RefreshPlanChecks RefreshPlanChecks

	// ConfigStateChecks allow assertions to be made against the state file during a Config (apply) test using a state check.
	// Custom state checks can be created by implementing the [statecheck.StateCheck] interface, or by using a StateCheck implementation from the provided [statecheck] package.
	ConfigStateChecks []statecheck.StateCheck

	// PlanOnly can be set to only run `plan` with this configuration, and not
	// actually apply it. This is useful for ensuring config changes result in
	// no-op plans
	PlanOnly bool

	// PreventDiskCleanup can be set to true for testing terraform modules which
	// require access to disk at runtime. Note that this will leave files in the
	// temp folder
	PreventDiskCleanup bool

	// PreventPostDestroyRefresh can be set to true for cases where data sources
	// are tested alongside real resources
	PreventPostDestroyRefresh bool

	// SkipFunc enables skipping the TestStep, based on environment criteria.
	// For example, this can prevent running certain steps that may be runtime
	// platform or API configuration dependent.
	//
	// Return true with no error to skip the test step. The error return
	// should be used to signify issues that prevented the function from
	// completing as expected.
	//
	// SkipFunc is called after PreConfig but before applying the Config.
	SkipFunc func() (bool, error)

	// ImportState, if true, will test the functionality of ImportState
	// by importing the resource with ResourceName (must be set) and the
	// ID of that resource.
	ImportState bool

	// ImportStateId is the ID to perform an ImportState operation with.
	// This is optional. If it isn't set, then the resource ID is automatically
	// determined by inspecting the state for ResourceName's ID.
	ImportStateId string

	// ImportStateIdPrefix is the prefix added in front of ImportStateId.
	// This can be useful in complex import cases, where more than one
	// attribute needs to be passed on as the Import ID. Mainly in cases
	// where the ID is not known, and a known prefix needs to be added to
	// the unset ImportStateId field.
	ImportStateIdPrefix string

	// ImportStateIdFunc is a function that can be used to dynamically generate
	// the ID for the ImportState tests. It is sent the state, which can be
	// checked to derive the attributes necessary and generate the string in the
	// desired format.
	ImportStateIdFunc ImportStateIdFunc

	// ImportStateCheck checks the results of ImportState. It should be
	// used to verify that the resulting value of ImportState has the
	// proper resources, IDs, and attributes.
	//
	// Prefer ImportStateVerify over ImportStateCheck, unless the resource
	// import explicitly is expected to create multiple resources (not a
	// recommended resource implementation) or if attributes are imported with
	// syntactically different but semantically/functionally equivalent values
	// where special logic is needed.
	//
	// Terraform versions 1.3 and later can include data source states during
	// import, which the testing framework will skip to prevent the need for
	// Terraform version specific logic in provider testing.
	ImportStateCheck ImportStateCheckFunc

	// ImportStateVerify, if true, will also check that the state values
	// that are finally put into the state after import match for all the
	// IDs returned by the Import.  Note that this checks for strict equality
	// and does not respect DiffSuppressFunc or CustomizeDiff.
	//
	// By default, the prior resource state and import resource state are
	// matched by the "id" attribute. If the "id" attribute is not implemented
	// or another attribute more uniquely identifies the resource, set the
	// ImportStateVerifyIdentifierAttribute field to adjust the attribute for
	// matching.
	//
	// If certain attributes cannot be correctly imported, set the
	// ImportStateVerifyIgnore field.
	ImportStateVerify bool

	// ImportStateVerifyIdentifierAttribute is the resource attribute for
	// matching the prior resource state and import resource state during import
	// verification. By default, the "id" attribute is used.
	ImportStateVerifyIdentifierAttribute string

	// ImportStateVerifyIgnore is a list of prefixes of fields that should
	// not be verified to be equal. These can be set to ephemeral fields or
	// fields that can't be refreshed and don't matter.
	ImportStateVerifyIgnore []string

	// ImportStatePersist, if true, will update the persisted state with the
	// state generated by the import operation (i.e., terraform import). When
	// false (default) the state generated by the import operation is discarded
	// at the end of the test step that is verifying import behavior.
	ImportStatePersist bool

	// RefreshState, if true, will test the functionality of `terraform
	// refresh` by refreshing the state, running any checks against the
	// refreshed state, and running a plan to verify against unexpected plan
	// differences.
	//
	// If the refresh is expected to result in a non-empty plan
	// ExpectNonEmptyPlan should be set to true in the same TestStep.
	//
	// RefreshState cannot be the first TestStep and, it is mutually exclusive
	// with ImportState.
	RefreshState bool

	// ProviderFactories can be specified for the providers that are valid for
	// this TestStep. When providers are specified at the TestStep level, all
	// TestStep within a TestCase must declare providers.
	//
	// This can also be specified at the TestCase level for all TestStep,
	// however all provider specifications must be done either at the TestCase
	// level or TestStep level, otherwise the testing framework will raise an
	// error and fail the test.
	//
	// These are the providers that can be referenced within the test. Each key
	// is an individually addressable provider. Typically you will only pass a
	// single value here for the provider you are testing. Aliases are not
	// supported by the test framework, so to use multiple provider instances,
	// you should add additional copies to this map with unique names. To set
	// their configuration, you would reference them similar to the following:
	//
	//  provider "my_factory_key" {
	//    # ...
	//  }
	//
	//  resource "my_resource" "mr" {
	//    provider = my_factory_key
	//
	//    # ...
	//  }
	ProviderFactories map[string]func() (*schema.Provider, error)

	// ProtoV5ProviderFactories serves the same purpose as ProviderFactories,
	// but for protocol v5 providers defined using the terraform-plugin-go
	// ProviderServer interface. When providers are specified at the TestStep
	// level, all TestStep within a TestCase must declare providers.
	//
	// This can also be specified at the TestCase level for all TestStep,
	// however all provider specifications must be done either at the TestCase
	// level or TestStep level, otherwise the testing framework will raise an
	// error and fail the test.
	ProtoV5ProviderFactories map[string]func() (tfprotov5.ProviderServer, error)

	// ProtoV6ProviderFactories serves the same purpose as ProviderFactories,
	// but for protocol v6 providers defined using the terraform-plugin-go
	// ProviderServer interface.
	// The version of Terraform used in acceptance testing must be greater
	// than or equal to v0.15.4 to use ProtoV6ProviderFactories. When providers
	// are specified at the TestStep level, all TestStep within a TestCase must
	// declare providers.
	//
	// This can also be specified at the TestCase level for all TestStep,
	// however all provider specifications must be done either at the TestCase
	// level or TestStep level, otherwise the testing framework will raise an
	// error and fail the test.
	ProtoV6ProviderFactories map[string]func() (tfprotov6.ProviderServer, error)

	// ExternalProviders are providers the TestStep relies on that should
	// be downloaded from the registry during init. When providers are
	// specified at the TestStep level, all TestStep within a TestCase must
	// declare providers.
	//
	// This can also be specified at the TestCase level for all TestStep,
	// however all provider specifications must be done either at the TestCase
	// level or TestStep level, otherwise the testing framework will raise an
	// error and fail the test.
	//
	// Outside specifying an earlier version of the provider under test,
	// typically for state upgrader testing, this is generally only necessary
	// for performing import testing where the prior TestStep configuration
	// contained a provider outside the one under test.
	ExternalProviders map[string]ExternalProvider
}

TestStep is a single apply sequence of a test, done within the context of a state.

Multiple TestSteps can be sequenced in a Test to allow testing potentially complex update logic. In general, simply create/destroy tests will only need one step.

Refer to the Env prefixed constants for environment variables that further control testing functionality.

type TimeoutError

type TimeoutError struct {
	LastError     error
	LastState     string
	Timeout       time.Duration
	ExpectedState []string
}

TimeoutError is returned when WaitForState times out

Deprecated: Copy this type to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.TimeoutError.

func (*TimeoutError) Error

func (e *TimeoutError) Error() string

Error returns a string with any information available.

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.TimeoutError.

func (*TimeoutError) Unwrap

func (e *TimeoutError) Unwrap() error

Unwrap returns the LastError, compatible with errors.Unwrap.

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.TimeoutError.

type UnexpectedStateError

type UnexpectedStateError struct {
	LastError     error
	State         string
	ExpectedState []string
}

UnexpectedStateError is returned when Refresh returns a state that's neither in Target nor Pending

Deprecated: Copy this type to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.UnexpectedStateError.

func (*UnexpectedStateError) Error

func (e *UnexpectedStateError) Error() string

Error returns a string with the unexpected state value, the desired target, and any last error.

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.UnexpectedStateError.

func (*UnexpectedStateError) Unwrap

func (e *UnexpectedStateError) Unwrap() error

Unwrap returns the LastError, compatible with errors.Unwrap.

Deprecated: Copy this method to the provider codebase or use github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry.UnexpectedStateError.