docs/contributing: Add service-specific region acceptance testing sec…

…tion (#16039)

Reference: #8316
Reference: #15737

docs/contributing/running-and-writing-acceptance-tests.md

@@ -21,6 +21,7 @@
         - [Per Attribute Acceptance Tests](#per-attribute-acceptance-tests)
         - [Cross-Account Acceptance Tests](#cross-account-acceptance-tests)
         - [Cross-Region Acceptance Tests](#cross-region-acceptance-tests)
+        - [Service-Specific Region Acceptance Tests](#service-specific-region-acceptance-tests)
     - [Data Source Acceptance Testing](#data-source-acceptance-testing)
 - [Acceptance Test Sweepers](#acceptance-test-sweepers)
     - [Running Test Sweepers](#running-test-sweepers)
@@ -803,6 +804,116 @@ resource "aws_example" "test" {
 
 Searching for usage of `testAccMultipleRegionPreCheck` in the codebase will yield real world examples of this setup in action.
 
+#### Service-Specific Region Acceptance Testing
+
+Certain AWS service APIs are only available in specific AWS regions. For example as of this writing, the `pricing` service is available in `ap-south-1` and `us-east-1`, but no other regions or partitions. When encountering these types of services, the acceptance testing can be setup to automatically detect the correct region(s), while skipping the testing in unsupported partitions.
+
+To prepare the shared service functionality, create a file named `aws/{SERVICE}_test.go`. A starting example with the Pricing service (`aws/pricing_test.go`):
+
+```go
+package aws
+
+import (
+  "context"
+  "sync"
+  "testing"
+
+  "github.com/aws/aws-sdk-go/aws/endpoints"
+  "github.com/aws/aws-sdk-go/service/pricing"
+  "github.com/hashicorp/terraform-plugin-sdk/v2/diag"
+  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
+  "github.com/hashicorp/terraform-plugin-sdk/v2/terraform"
+)
+
+// testAccPricingRegion is the chosen Pricing testing region
+//
+// Cached to prevent issues should multiple regions become available.
+var testAccPricingRegion string
+
+// testAccProviderPricing is the Pricing provider instance
+//
+// This Provider can be used in testing code for API calls without requiring
+// the use of saving and referencing specific ProviderFactories instances.
+//
+// testAccPreCheckPricing(t) must be called before using this provider instance.
+var testAccProviderPricing *schema.Provider
+
+// testAccProviderPricingConfigure ensures the provider is only configured once
+var testAccProviderPricingConfigure sync.Once
+
+// testAccPreCheckPricing verifies AWS credentials and that Pricing is supported
+func testAccPreCheckPricing(t *testing.T) {
+  testAccPartitionHasServicePreCheck(pricing.EndpointsID, t)
+
+  // Since we are outside the scope of the Terraform configuration we must
+  // call Configure() to properly initialize the provider configuration.
+  testAccProviderPricingConfigure.Do(func() {
+    testAccProviderPricing = Provider()
+
+    config := map[string]interface{}{
+      "region": testAccGetPricingRegion(),
+    }
+
+    diags := testAccProviderPricing.Configure(context.Background(), terraform.NewResourceConfigRaw(config))
+
+    if diags != nil && diags.HasError() {
+      for _, d := range diags {
+        if d.Severity == diag.Error {
+          t.Fatalf("error configuring Pricing provider: %s", d.Summary)
+        }
+      }
+    }
+  })
+}
+
+// testAccPricingRegionProviderConfig is the Terraform provider configuration for Pricing region testing
+//
+// Testing Pricing assumes no other provider configurations
+// are necessary and overwrites the "aws" provider configuration.
+func testAccPricingRegionProviderConfig() string {
+  return testAccRegionalProviderConfig(testAccGetPricingRegion())
+}
+
+// testAccGetPricingRegion returns the Pricing region for testing
+func testAccGetPricingRegion() string {
+  if testAccPricingRegion != "" {
+    return testAccPricingRegion
+  }
+
+  if rs, ok := endpoints.RegionsForService(endpoints.DefaultPartitions(), testAccGetPartition(), pricing.ServiceName); ok {
+    // return available region (random if multiple)
+    for regionID := range rs {
+      testAccPricingRegion = regionID
+      return testAccPricingRegion
+    }
+  }
+
+  testAccPricingRegion = testAccGetRegion()
+
+  return testAccPricingRegion
+}
+```
+
+For the resource or data source acceptance tests, the key items to adjust are:
+
+* Ensure `TestCase` uses `ProviderFactories: testAccProviderFactories` instead of `Providers: testAccProviders`
+* Add the call for the new `PreCheck` function (keeping `testAccPreCheck(t)`), e.g. `PreCheck: func() { testAccPreCheck(t); testAccPreCheckPricing(t) },`
+* If the testing is for a managed resource with a `CheckDestroy` function, ensure it uses the new provider instance, e.g. `testAccProviderPricing`, instead of `testAccProvider`.
+* If the testing is for a managed resource with a `Check...Exists` function, ensure it uses the new provider instance, e.g. `testAccProviderPricing`, instead of `testAccProvider`.
+* In each `TestStep` configuration, ensure the new provider configuration function is called, e.g.
+
+```go
+func testAccDataSourceAwsPricingProductConfigRedshift() string {
+  return composeConfig(
+    testAccPricingRegionProviderConfig(),
+    `
+# ... test configuration ...
+`)
+}
+```
+
+If the testing configurations require more than one region, reach out to the maintainers for further assistance.
+
 ### Data Source Acceptance Testing
 
 Writing acceptance testing for data sources is similar to resources, with the biggest changes being: