Query Result Checks

The terraform-plugin-testing module provides a package querycheck with built-in query checks for common use-cases:

Check	Description
`ExpectIdentity`	Asserts that a specified resource identity object is present in the query result.
`ExpectLengthAtLeast`	Asserts that the number of query results returned is at least a given value.
`ExpectLengthExact`	Asserts that the number of query results returned is equal to the given value.
`ExpectNoIdentity`	Asserts that a specified resource identity object is absent from the query results.
`ExpectResourceDisplayName`	Asserts that a particular query result has the specified display name.
`ExpectResourceKnownValues`	Asserts that a specific query result's resource attribute has a specified value.

Query Filter

Several built-in query checks can only be applied to a specific query result which is identified by a query filter. The terraform-plugin-testing module provides a package queryfilter with built-in query filters for common use-cases:

Filtering by Display Name: queryfilter.ByDisplayName(displayName) is used to filter query results by matching the display name of the resource.
Filtering by Resource Identity: queryfilter.ByResourceIdentity(identity) is used to filter query results by matching a resource identity object.

`ExpectIdentity` Query Check

The querycheck.ExpectIdentity(resourceAddress, identity) query check is used to assert that the query results returned by a list resource contain a resource with the specified identity.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                // Example config creating three resources for querying
                Config: `
                  resource "test_resource" "one" {}
                  resource "test_resource" "two" {}
                  resource "test_resource" "three" {}
                `,
            },
            {
                // Config for the .tfquery.hcl query file
                Config: `
                  list "test_resource" "test" {
                  provider = examplecloud

                  config {}
                }
                `,
                Query: true,
                QueryResultChecks: []querycheck.QueryResultCheck{
                    querycheck.ExpectIdentity(
                        "test_resource.test",
                        map[string]knownvalue.Check{"attr_1": "foo", "attr_1": "bar"},
                    ),
                },
            },
        },
    })
}

`ExpectLengthAtLeast` Query Check

The querycheck.ExpectLengthAtLeast(resourceAddress, length) query check is used to assert that a query returns a minimum number of results.

This is intended to be used when the exact number of results cannot be guaranteed due to the testing environment.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                // Example config creating three resources for querying
                Config: `
                  resource "test_resource" "one" {}
                  resource "test_resource" "two" {}
                  resource "test_resource" "three" {}
                `,
            },
            {
                // Config for the .tfquery.hcl query file
                Config: `
                  list "test_resource" "test" {
                  provider = examplecloud

                  config {}
                }
                `,
                Query: true,
                QueryResultChecks: []querycheck.QueryResultCheck{
                    querycheck.ExpectLengthAtLeast("test_resource.test", 3),
                },
            },
        },
    })
}

`ExpectLengthExact` Query Check

The querycheck.ExpectLengthExact(resourceAddress, length) query check is used to assert that a query returns a specific number of results.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                // Example config creating three resources for querying
                Config: `
                  resource "test_resource" "one" {}
                  resource "test_resource" "two" {}
                  resource "test_resource" "three" {}
                `,
            },
            {
                // Config for the .tfquery.hcl query file
                Config: `
                  list "test_resource" "test" {
                  provider = examplecloud

                  config {}
                }
                `,
                Query: true,
                QueryResultChecks: []querycheck.QueryResultCheck{
                    querycheck.ExpectLength("test_resource.test", 3),
                },
            },
        },
    })
}

`ExpectNoIdentity` Query Check

The querycheck.ExpectNoIdentity(resourceAddress, identity) query check is used to assert that the query results returned by a list resource do not contain a resource with the specified identity.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                // Example config creating three resources for querying
                Config: `
                  resource "test_resource" "one" {}
                  resource "test_resource" "two" {}
                  resource "test_resource" "three" {}
                `,
            },
            {
                // Config for the .tfquery.hcl query file
                Config: `
                  list "test_resource" "test" {
                  provider = examplecloud

                  config {}
                }
                `,
                Query: true,
                QueryResultChecks: []querycheck.QueryResultCheck{
                    querycheck.ExpectNoIdentity(
                        "test_resource.test",
                        map[string]knownvalue.Check{"attr_1": "foo", "attr_1": "bar"}
                    ),
                },
            },
        },
    })
}

`ExpectResourceDisplayName` Query Check

The querycheck.ExpectResourceDisplayName(resourceAddress, filter, displayName) query check is used to assert that a particular query result which is returned by a query filter has a given display name.

This check requires a query filter to identify the query result on which the assertion should be performed. If the query filter returns zero or multiple results, the check will fail.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                // Example config creating three resources for querying
                Config: `
                  resource "test_resource" "one" {}
                  resource "test_resource" "two" {}
                  resource "test_resource" "three" {}
                `,
            },
            {
                // Config for the .tfquery.hcl query file
                Config: `
                  list "test_resource" "test" {
                  provider = examplecloud

                  config {}
                }
                `,
                Query: true,
                QueryResultChecks: []querycheck.QueryResultCheck{
                    querycheck.ExpectResourceDisplayName(
                        "test_resource.test",
                        queryfilter.ByResourceIdentity(map[string]knownvalue.Check{"attr_1": knownvalue.StringExact("foo"), "attr_2": knownvalue.StringExact("bar")}),
                        knownvalue.StringExact("foobar"),
                    ),
                },
            },
        },
    })
}

`ExpectResourceKnownValues` Query Check

The querycheck.ExpectResourceKnownValues(resourceAddress, filter, knownValueChecks) query check is used to assert that a particular query result's resource object has the given values.

This check requires a query filter to identify the query result on which the assertion should be performed. If the query filter returns zero or multiple results, the check will fail.

package example_test

import (
    "testing"

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

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

    resource.Test(t, resource.TestCase{
        // Provider definition omitted.
        Steps: []resource.TestStep{
            {
                // Example config creating three resources for querying
                Config: `
                  resource "test_resource" "one" {}
                  resource "test_resource" "two" {}
                  resource "test_resource" "three" {}
                `,
            },
            {
                // Config for the .tfquery.hcl query file
                Config: `
                  list "test_resource" "test" {
                  provider         = examplecloud
                  include_resource = true

                  config {}
                }
                `,
                Query: true,
                QueryResultChecks: []querycheck.QueryResultCheck{
                    querycheck.ExpectResourceKnownValues(
                        "test_resource.test",
                        queryfilter.ByResourceIdentity(map[string]knownvalue.Check{"attr_1": knownvalue.StringExact("foo"), "attr_2": knownvalue.StringExact("bar")}),
                        []querycheck.KnownValueCheck{
                            {
                                tfjsonpath.New("attr_3"),
                                knownvalue.StringExact("foobar"),
                            },
                            {
                                tfjsonpath.New("attr_4"),
                                knownvalue.StringExact("baz"),
                            },
                        },
                    ),
                },
            },
        },
    })
}

Query Result Checks

Query Filter

ExpectIdentity Query Check

ExpectLengthAtLeast Query Check

ExpectLengthExact Query Check

ExpectNoIdentity Query Check

ExpectResourceDisplayName Query Check

ExpectResourceKnownValues Query Check