Documented how to use field validation functions (GoogleCloudPlatform…

…#10472)

docs/content/develop/field-reference.md

@@ -217,6 +217,11 @@ to use for this field. In many cases, a [custom flattener](https://googlecloudpl
 is preferred because it will allow the user to see a clearer diff when the field actually is being changed. See
 [Fix a permadiff]({{< ref "/develop/permadiff.md" >}}) for more information and best practices.
 
+The function specified can be a
+[provider-specific function](https://github.com/hashicorp/terraform-provider-google-beta/blob/main/google-beta/tpgresource/common_diff_suppress.go)
+(for example, `tgpresource.CaseDiffSuppress`) or a function defined in resource-specific
+[custom code]({{<ref "/develop/custom-code#add-reusable-variables-and-functions" >}}).
+
 Example:
 
 ```yaml
@@ -225,6 +230,44 @@ Example:
   diff_suppress_func: 'tpgresource.CaseDiffSuppress'
 ```
 
+### `validation`
+Controls the value set for the field's [`ValidateFunc`](https://developer.hashicorp.com/terraform/plugin/sdkv2/schemas/schema-behaviors#validatefunc).
+
+If `validation` is set on an Enum field, it will override the default validation (that the provided value is in the Enum's [`values`](#values)).
+
+This property has two mutually exclusive child properties:
+
+- `function`: The name of a
+  [validation function](https://developer.hashicorp.com/terraform/plugin/sdkv2/schemas/schema-behaviors#validatefunc)
+  to use for validation. The function can be a
+  [Terraform-provided function](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-sdk/helper/validation)
+  (for example, `validation.IntAtLeast(0)`), a
+  [provider-specific function](https://github.com/hashicorp/terraform-provider-google-beta/blob/main/google-beta/verify/validation.go)
+  (for example, `verify.ValidateBase64String`), or a function defined in
+  resource-specific
+  [custom code]({{<ref "/develop/custom-code#add-reusable-variables-and-functions" >}}).
+- `regex`: A regex string to check values against. This can only be used on simple
+  String fields. It is equivalent to
+  [`function: verify.ValidateRegexp(REGEX_STRING)`](https://github.com/hashicorp/terraform-provider-google-beta/blob/0ef51142a4dd1c1a4fc308c1eb09dce307ebe5f5/google-beta/verify/validation.go#L425).
+
+Example: Provider-specific function
+
+```yaml
+- !ruby/object:Api::Type::String
+  name: 'fieldOne'
+  validation: !ruby/object:Provider::Terraform::Validation
+    function: 'verify.ValidateBase64String'
+```
+
+Example: Regex
+
+```yaml
+- !ruby/object:Api::Type::String
+  name: 'fieldOne'
+  validation: !ruby/object:Provider::Terraform::Validation
+    regex: '^[a-zA-Z][a-zA-Z0-9_]*$'
+```
+
 ### `api_name`
 Specifies a name to use for communication with the API that is different than
 the name of the field in Terraform. In general, setting an `api_name` is not
@@ -246,6 +289,9 @@ to allow better forwards-compatibility, and link to API documentation
 stating the current allowed values in the String field's description. Do not
 include UNSPECIFIED values in this list.
 
+Enums will validate that the provided field is in the allowed list unless a
+custom [`validation`](#validation) is provided.
+
 Example:
 
 ```yaml

docs/content/develop/test/test.md

@@ -222,6 +222,41 @@ An update test is a test that creates the target resource and then makes updates
 {{< /tab >}}
 {{< /tabs >}}
 
+## Add unit tests
+
+A unit test verifies functionality that is not related to interactions with the API, such as
+[diff suppress functions]({{<ref "/develop/field-reference#diff_suppress_func" >}})),
+[validation functions]({{<ref "/develop/field-reference#validation" >}}),
+CustomizeDiff functions, and so on.
+
+Unit tests should be added to the appropriate folder in [`magic-modules/mmv1/third_party/terraform/services`](https://github.com/GoogleCloudPlatform/magic-modules/tree/main/mmv1/third_party/terraform/services) in the file called `resource_PRODUCT_RESOURCE_test.go`. (You may need to create this file if it does not already exist. Replace PRODUCT with the product name and RESOURCE with the resource name; it should match the name of the generated resource file.)
+
+Unit tests should be named like `TestFunctionName` - for example, `TestDiskImageDiffSuppress` would contain tests for the `DiskImageDiffSuppress` function.
+
+Example:
+
+```go
+func TestSignatureAlgorithmDiffSuppress(t *testing.T) {
+   cases := map[string]struct {
+      Old, New           string
+      ExpectDiffSuppress bool
+   }{
+      "ECDSA_P256 equivalent": {
+         Old:                "ECDSA_P256_SHA256",
+         New:                "EC_SIGN_P256_SHA256",
+         ExpectDiffSuppress: true,
+      },
+      // Additional cases excluded for brevity
+   }
+
+   for tn, tc := range cases {
+      if signatureAlgorithmDiffSuppress("signature_algorithm", tc.Old, tc.New, nil) != tc.ExpectDiffSuppress {
+         t.Errorf("bad: %s, %q => %q expect DiffSuppress to return %t", tn, tc.Old, tc.New, tc.ExpectDiffSuppress)
+      }
+   }
+}
+```
+
 ## What's next?
 
 - [Run your tests]({{< ref "/develop/test/run-tests.md" >}})