plancheck

Documentation

Overview

Package plancheck contains the plan check interface, request/response structs, and common plan check implementations.

Index

• type CheckPlanRequest
• type CheckPlanResponse
• type PlanCheck
  • func ExpectEmptyPlan() PlanCheck
  • func ExpectKnownOutputValue(outputAddress string, knownValue knownvalue.Check) PlanCheck
  • func ExpectKnownOutputValueAtPath(outputAddress string, outputPath tfjsonpath.Path, knownValue knownvalue.Check) PlanCheck
  • func ExpectKnownValue(resourceAddress string, attributePath tfjsonpath.Path, ...) PlanCheck
  • func ExpectNonEmptyPlan() PlanCheck
  • func ExpectNullOutputValue(outputAddress string) PlanCheck
  • func ExpectNullOutputValueAtPath(outputAddress string, valuePath tfjsonpath.Path) PlanCheck
  • func ExpectResourceAction(resourceAddress string, actionType ResourceActionType) PlanCheck
  • func ExpectSensitiveValue(resourceAddress string, attributePath tfjsonpath.Path) PlanCheck
  • func ExpectUnknownOutputValue(outputAddress string) PlanCheck
  • func ExpectUnknownOutputValueAtPath(outputAddress string, valuePath tfjsonpath.Path) PlanCheck
  • func ExpectUnknownValue(resourceAddress string, attributePath tfjsonpath.Path) PlanCheck
• type ResourceActionType

Types

type CheckPlanRequest

type CheckPlanRequest struct {
	// Plan represents a parsed plan file, retrieved via the `terraform show -json` command.
	Plan *tfjson.Plan
}

CheckPlanRequest is a request for an invoke of the CheckPlan function.

type CheckPlanResponse

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

CheckPlanResponse is a response to an invoke of the CheckPlan function.

type PlanCheck

type PlanCheck interface {
	// CheckPlan should perform the plan check.
	CheckPlan(context.Context, CheckPlanRequest, *CheckPlanResponse)
}

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

func ExpectEmptyPlan

func ExpectEmptyPlan() PlanCheck

ExpectEmptyPlan returns a plan check that asserts that there are no output or resource changes in the plan. All output and resource changes found will be aggregated and returned in a plan check error.

func ExpectKnownOutputValue

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

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

func ExpectKnownOutputValueAtPath

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

ExpectKnownOutputValueAtPath returns a plan check that asserts that the specified output at the given path has a known type and value. Prior to Terraform v1.3.0 a planned output is marked as fully unknown if any attribute is unknown.

func ExpectKnownValue

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

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

func ExpectNonEmptyPlan

func ExpectNonEmptyPlan() PlanCheck

ExpectNonEmptyPlan returns a plan check that asserts there is at least one output or resource change in the plan.

func ExpectNullOutputValue

func ExpectNullOutputValue(outputAddress string) PlanCheck

ExpectNullOutputValue returns a plan check that asserts that the specified output has a null value.

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

Deprecated: Use plancheck.ExpectKnownOutputValue with knownvalue.Null instead. ExpectNullOutputValue will be removed in the next major version release.

func ExpectNullOutputValueAtPath

func ExpectNullOutputValueAtPath(outputAddress string, valuePath tfjsonpath.Path) PlanCheck

ExpectNullOutputValueAtPath returns a plan check that asserts that the specified output has a null value.

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

Deprecated: Use plancheck.ExpectKnownOutputValueAtPath with knownvalue.Null instead. ExpectNullOutputValueAtPath will be removed in the next major version release.

func ExpectResourceAction

func ExpectResourceAction(resourceAddress string, actionType ResourceActionType) PlanCheck

ExpectResourceAction returns a plan check that asserts that a given resource will have a specific resource change type in the plan. Valid actionType are an enum of type plancheck.ResourceActionType, examples: NoOp, DestroyBeforeCreate, Update (in-place), etc.

func ExpectSensitiveValue

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

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

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

func ExpectUnknownOutputValue

func ExpectUnknownOutputValue(outputAddress string) PlanCheck

ExpectUnknownOutputValue returns a plan check that asserts that the specified output has an unknown value.

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

func ExpectUnknownOutputValueAtPath

func ExpectUnknownOutputValueAtPath(outputAddress string, valuePath tfjsonpath.Path) PlanCheck

ExpectUnknownOutputValueAtPath returns a plan check that asserts that the specified output has an unknown value.

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

func ExpectUnknownValue

func ExpectUnknownValue(resourceAddress string, attributePath tfjsonpath.Path) PlanCheck

ExpectUnknownValue returns a plan check that asserts that the specified attribute at the given resource has an unknown value.

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

type ResourceActionType

type ResourceActionType string

ResourceActionType is a string enum type that routes to a specific terraform-json.Actions function for asserting resource changes.

• https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions

More information about expected resource behavior can be found at: https://developer.hashicorp.com/terraform/language/resources/behavior

const (
	// ResourceActionNoop occurs when a resource is not planned to change (no-op).
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.NoOp
	ResourceActionNoop ResourceActionType = "NoOp"

	// ResourceActionCreate occurs when a resource is planned to be created.
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.Create
	ResourceActionCreate ResourceActionType = "Create"

	// ResourceActionRead occurs when a data source is planned to be read during the apply stage (data sources are read during plan stage when possible).
	// See the data source documentation for more information on this behavior: https://developer.hashicorp.com/terraform/language/data-sources#data-resource-behavior
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.Read
	ResourceActionRead ResourceActionType = "Read"

	// ResourceActionUpdate occurs when a resource is planned to be updated in-place.
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.Update
	ResourceActionUpdate ResourceActionType = "Update"

	// ResourceActionDestroy occurs when a resource is planned to be deleted.
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.Delete
	ResourceActionDestroy ResourceActionType = "Destroy"

	// ResourceActionDestroyBeforeCreate occurs when a resource is planned to be deleted and then re-created. This is the default
	// behavior when terraform must change a resource argument that cannot be updated in-place due to remote API limitations.
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.DestroyBeforeCreate
	ResourceActionDestroyBeforeCreate ResourceActionType = "DestroyBeforeCreate"

	// ResourceActionCreateBeforeDestroy occurs when a resource is planned to be created and then deleted. This is opt-in behavior that
	// is enabled with the [create_before_destroy] meta-argument.
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.CreateBeforeDestroy
	//
	// [create_before_destroy]: https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#create_before_destroy
	ResourceActionCreateBeforeDestroy ResourceActionType = "CreateBeforeDestroy"

	// ResourceActionReplace can be used to verify a resource is planned to be deleted and re-created (where the order of delete and create actions are not important).
	// This action matches both ResourceActionDestroyBeforeCreate and ResourceActionCreateBeforeDestroy.
	//   - Routes to: https://pkg.go.dev/github.com/hashicorp/terraform-json#Actions.Replace
	ResourceActionReplace ResourceActionType = "Replace"
)