Add terraform-plugin-testing documentation for query mode and query checks

content/terraform-plugin-testing/v1.14.x/data/plugin-testing-nav-data.json

@@ -25,7 +25,10 @@
 	}, {
 		"title": "Import mode",
 		"path": "acceptance-tests/import-mode"
-	}]
+	}, {
+        "title": "Query mode",
+        "path": "acceptance-tests/query-mode"
+    }]
       },
       {
         "title": "Terraform Version Checks",
@@ -73,6 +76,23 @@
           }
         ]
       },
+      {
+        "title": "Query Checks",
+        "routes": [
+          {
+            "title": "Overview",
+            "path": "acceptance-tests/query-checks"
+          },
+          {
+            "title": "Query Result Checks",
+            "path": "acceptance-tests/query-checks/query-result"
+          },
+          {
+            "title": "Custom Query Checks",
+            "path": "acceptance-tests/query-checks/custom"
+          }
+        ]
+      },
       {
         "title": "Known Value Checks",
         "routes": [

content/terraform-plugin-testing/v1.14.x/docs/plugin/testing/acceptance-tests/query-checks/custom.mdx

@@ -0,0 +1,95 @@
+---
+page_title: 'Plugin Development - Acceptance Testing: Query Checks'
+description: >-
+  Query Checks are test assertions that can inspect the query results during a TestStep. Custom Query Checks can be implemented.
+---
+
+# Custom Query Checks
+
+The package [`querycheck`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/querycheck) also provides the [`QueryResultCheck`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/querycheck#QueryResultCheck) interface, which can be implemented for a custom query check.
+
+The [`querycheck.CheckQueryRequest`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-testing/querycheck#CheckQueryResultRequest) contains the current query results, parsed by the [terraform-json package](https://pkg.go.dev/github.com/hashicorp/terraform-json#ListResourceFoundData).
+
+Here is an example implementation of a query check that asserts that a specific query result resource object attribute has a known type and value:
+
+```go
+package example_test
+
+import (
+    "context"
+    "fmt"
+
+    tfjson "github.com/hashicorp/terraform-json"
+
+    "github.com/hashicorp/terraform-plugin-testing/knownvalue"
+    "github.com/hashicorp/terraform-plugin-testing/querycheck"
+	"github.com/hashicorp/terraform-plugin-testing/querycheck/queryfilter"
+    "github.com/hashicorp/terraform-plugin-testing/tfjsonpath"
+)
+
+var _ querycheck.QueryResultCheck = expectKnownValue{}
+var _ querycheck.QueryResultCheckWithFilters = expectKnownValue{}
+
+type expectKnownValue struct {
+    listResourceAddress string
+    filter              queryfilter.QueryFilter
+	attributePath       tfjsonpath.Path
+    knownValueCheck     knownvalue.Check
+}
+
+func (e expectResourceKnownValues) QueryFilters(_ context.Context) []queryfilter.QueryFilter {
+	if e.filter == nil {
+		return []queryfilter.QueryFilter{}
+	}
+
+	return []queryfilter.QueryFilter{
+		e.filter,
+	}
+}
+
+func (e expectKnownValue) CheckQuery(_ context.Context, req querycheck.CheckQueryRequest, resp *querycheck.CheckQueryResponse) {
+	listRes := make([]tfjson.ListResourceFoundData, 0)
+	for _, res := range req.Query {
+		if e.listResourceAddress == strings.TrimPrefix(res.Address, "list.") {
+			listRes = append(listRes, res)
+		}
+	}
+
+	if len(listRes) == 0 {
+		resp.Error = fmt.Errorf("%s - no query results found after filtering", e.listResourceAddress)
+		return
+	}
+
+	if len(listRes) > 1 {
+		resp.Error = fmt.Errorf("%s - more than 1 query result found after filtering", e.listResourceAddress)
+		return
+	}
+
+	res := listRes[0]
+
+	if res.ResourceObject == nil {
+		resp.Error = fmt.Errorf("%s - no resource object was returned, ensure `include_resource` has been set to `true` in the list resource config`", e.listResourceAddress)
+		return
+	}
+
+	attribute, err := tfjsonpath.Traverse(res.ResourceObject, e.attributePath)
+    if err != nil {
+        resp.Error = err
+        return
+    }
+
+    if err := e.KnownValue.CheckValue(attribute); err != nil {
+		resp.Error = fmt.Errorf("error checking value for attribute at path: %s for resource with identity %s, err: %s", e.attributePath, e.filter, err)
+        return
+    }
+}
+
+func ExpectKnownValues(listResourceAddress string, filter queryfilter.QueryFilter, attributePath tfjsonpath.Path, knownValueCheck knownvalue.Check) QueryResultCheck {
+	return expectKnownValues{
+		listResourceAddress: listResourceAddress,
+		filter:              filter,
+		attributePath:       attributePath,
+		knownValueCheck:     knownValueCheck,
+	}
+}
+```

content/terraform-plugin-testing/v1.14.x/docs/plugin/testing/acceptance-tests/query-checks/index.mdx

@@ -0,0 +1,18 @@
+---
+page_title: 'Plugin Development - Acceptance Testing: Query Checks'
+description: >-
+  Query Checks are test assertions that can inspect the query results during a Query TestStep. The testing module
+  provides built-in Query Checks for common use-cases, and custom Query Checks can also be implemented.
+---
+
+# Query Checks
+During the **Query** [mode](/terraform/plugin/testing/acceptance-tests/teststep#test-modes) of a `TestStep`, the configuration supplied is used as the content of a `.tfquery.hcl` query file and the testing framework will run `terraform query`.
+
+The execution of `terraform query` results in a set of query results.
+
+A **query check** is a test assertion that inspects the query results. Multiple query checks can be run, all assertion errors returned are aggregated, reported as a test failure, and all test cleanup logic is executed.
+
+Refer to:
+
+- [Query Result Query Checks](/terraform/plugin/testing/acceptance-tests/query-checks/query-results) for built-in query checks.
+- [Custom Query Checks](/terraform/plugin/testing/acceptance-tests/query-checks/custom) for defining bespoke query checks.