resource

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 22, 2023 License: MPL-2.0 Imports: 33 Imported by: 23

Documentation

Index

Examples

Constants

View Source 
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.

View Source 
const TestEnvVar = EnvTfAcc

Deprecated: Use EnvTfAcc instead.

View Source 
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.

View Source 
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.

Variables

This section is empty.

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 deprecated 

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 deprecated 

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 deprecated 

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-failues: 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 deprecated 

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 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.

type ConfigPlanChecks added in v1.2.0 

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 deprecated 

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 deprecated 

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 deprecated 

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 RefreshPlanChecks added in v1.2.0 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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

	// 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.
	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
}

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

Output:

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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.

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

Output:

func TestCheckOutput 

func TestCheckOutput(name, value string) TestCheckFunc

TestCheckOutput checks an output in the Terraform configuration

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

Output:
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")
}

Output:
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")
}

Output:
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")
}

Output:
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")
}

Output:
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")
}

Output:
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")
}

Output:

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

Output:

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.

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

Output:

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.

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

Output:
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
	})
}

Output:

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

Output:

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

Output:

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.

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

Output:

func TestMatchOutput 

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

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.

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

Output:

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.

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

Output:

func TestModuleMatchResourceAttr deprecated 

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`.
	//
	// JSON Configuration Syntax can be used and is assumed whenever Config
	// contains valid JSON.
	Config string

	// 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.
	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

	// 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.
	//
	// 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.
	ImportStateVerify       bool
	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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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 deprecated 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.