Output Plan Checks

The terraform-plugin-testing module provides a package plancheck with built-in output value plan checks for common use-cases:

Check	Description
`ExpectKnownOutputValue`	Asserts the output at the specified address has the specified type, and value.
`ExpectKnownOutputValueAtPath`	Asserts the output at the specified address, and path has the specified type, and value.
`ExpectNullOutputValue`	Asserts the output at the specified address has a null value.
`ExpectNullOutputValueAtPath`	Asserts the output at the specified address, and path has a null value.
`ExpectUnknownOutputValue`	Asserts the output at the specified address has an unknown value.
`ExpectUnknownOutputValueAtPath`	Asserts the output at the specified address, and path has an unknown value.

`ExpectKnownOutputValue` Plan Check

The plancheck.ExpectKnownOutputValue(address, value) plan check verifies that a specific output value has a known type, and value.

Refer to Known Value Checks for details, and examples of the available knownvalue.Check types that can be used with the ExpectKnownOutputValue plan check.

package example_test

import (
    "testing"

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

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

    resource.UnitTest(t, resource.TestCase{
        TerraformVersionChecks: []tfversion.TerraformVersionCheck{
            tfversion.SkipBelow(tfversion.Version1_8_0),
        },
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                Config: `
                output "test" {
                    value = provider::example::bool(true)
                }`,
                ConfigPlanChecks: resource.ConfigPlanChecks{
                    PreApply: []plancheck.PlanCheck{
                        plancheck.ExpectKnownOutputValue(
                            "test",
                            knownvalue.Bool(true),
                        ),
                    },
                },
            },
        },
    })
}

`ExpectKnownOutputValueAtPath` Plan Check

The plancheck.ExpectKnownOutputValueAtPath(address, path, value) plan check verifies that a specific output value at a defined path has a known type, and value.

Note: Prior to Terraform v1.3.0 a planned output is marked as fully unknown if any attribute is unknown.

Refer to Known Value Checks for details, and examples of the available knownvalue.Check types that can be used with the ExpectKnownOutputValueAtPath plan check.

package example_test

import (
    "testing"

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

func TestExpectKnownOutputValue_CheckPlan_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. This is only shown as
                // an example.
                //
                //      ConfigPlanChecks: resource.ConfigPlanChecks{
                //          PreApply: []plancheck.PlanCheck{
                //              plancheck.ExpectKnownValue(
                //                  "test_resource.one",
                //                  tfjsonpath.New("computed_attribute"),
                //                  knownvalue.Bool(true),
                //              ),
                //          },
                //      },
                //
                // This is only shown as an example.
                output test {
                    value = test_resource.one
                }`,
                ConfigPlanChecks: resource.ConfigPlanChecks{
                    PreApply: []plancheck.PlanCheck{
                        plancheck.ExpectKnownOutputValueAtPath(
                            "test",
                            tfjsonpath.New("computed_attribute"),
                            knownvalue.Bool(true),
                        ),
                    },
                },
            },
        },
    })
}

`ExpectNullOutputValue` Plan Check

Note: ExpectNullOutputValue is deprecated. Use ExpectKnownOutputValue with knownvalue.Null() instead.

The built-in plancheck.ExpectNullOutputValue(address) plan check determines whether an output at the specified address has a null value.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                Config: `resource "test_resource" "test" {
                    string_attribute = null
                }

                output "string_attribute" {
                    value = test_resource.test.string_attribute
                }
                `,
                ConfigPlanChecks: resource.ConfigPlanChecks{
                    PreApply: []plancheck.PlanCheck{
                        plancheck.ExpectNullOutputValue("string_attribute"),
                    },
                },
            },
        },
    })
}

`ExpectNullOutputValueAtPath` Plan Check

Note: ExpectNullOutputValueAtPath is deprecated. Use ExpectKnownOutputValueAtPath with knownvalue.Null() instead.

The built-in plancheck.ExpectNullOutputValueAtPath(address, path) plan check determines whether an output at the specified address, and path has a null value. |

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Prior to Terraform v1.3.0 a planned output is marked as fully unknown
        // if any attribute is unknown. The id attribute within the test provider
        // is unknown.
        // Reference: https://github.com/hashicorp/terraform/blob/v1.3/CHANGELOG.md#130-september-21-2022
        TerraformVersionChecks: []tfversion.TerraformVersionCheck{
            tfversion.SkipBelow(tfversion.Version1_3_0),
        },
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                Config: `resource "test_resource" "test" {
                    string_attribute = null
                }

                output "resource" {
                    value = test_resource.test
                }
                `,
                ConfigPlanChecks: resource.ConfigPlanChecks{
                    PreApply: []plancheck.PlanCheck{
                        plancheck.ExpectNullOutputValueAtPath("resource", tfjsonpath.New("string_attribute")),
                    },
                },
            },
        },
    })
}

`ExpectUnknownOutputValue` Plan Check

One of the built-in plan checks, plancheck.ExpectUnknownOutputValue, determines whether an output value is unknown, for example, prior to the terraform apply phase.

The following uses the time_offset resource from the time provider, to illustrate usage of the plancheck.ExpectUnknownOutputValue, and verifies that day is unknown.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        ExternalProviders: map[string]resource.ExternalProvider{
            "time": {
                Source: "registry.terraform.io/hashicorp/time",
            },
        },
        Steps: []resource.TestStep{
            {
                Config: `resource "time_offset" "one" {
                    offset_days = 1
                  }

                  output day {
                    value = time_offset.one.day
                  }`,
                ConfigPlanChecks: resource.ConfigPlanChecks{
                    PreApply: []plancheck.PlanCheck{
                        plancheck.ExpectUnknownOutputValue("day"),
                    },
                },
            },
        },
    })
}

`ExpectUnknownOutputValueAtPath` Plan Check

Output values can contain objects or collections as well as primitive (e.g., string) values. Output value plan checks provide two forms for the plan checks, for example ExpectUnknownOutputValue(), and ExpectUnknownOutputValueAtPath(). The Expect<...>OutputValueAtPath() form is used to access a value contained within an object or collection, as illustrated in the following example.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        ExternalProviders: map[string]resource.ExternalProvider{
            "time": {
                Source: "registry.terraform.io/hashicorp/time",
            },
        },
        Steps: []resource.TestStep{
            {
                Config: `resource "time_offset" "one" {
                    offset_days = 1
                  }

                  output time_offset_one {
                    value = time_offset.one
                  }`,
                ConfigPlanChecks: resource.ConfigPlanChecks{
                    PreApply: []plancheck.PlanCheck{
                        plancheck.ExpectUnknownOutputValueAtPath("time_offset_one", tfjsonpath.New("day")),
                    },
                },
            },
        },
    })
}

Output Plan Checks

ExpectKnownOutputValue Plan Check

ExpectKnownOutputValueAtPath Plan Check

ExpectNullOutputValue Plan Check

ExpectNullOutputValueAtPath Plan Check

ExpectUnknownOutputValue Plan Check

ExpectUnknownOutputValueAtPath Plan Check