Merge pull request hashicorp#22594 from hashicorp/d-add-short-test-gu…

…ard-docs

docs: Long-running test guards

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

@@ -4,6 +4,7 @@
 - [Running an Acceptance Test](#running-an-acceptance-test)
     - [Running Cross-Account Tests](#running-cross-account-tests)
     - [Running Cross-Region Tests](#running-cross-region-tests)
+    - [Running Only Short Tests](#running-only-short-tests)
 - [Writing an Acceptance Test](#writing-an-acceptance-test)
     - [Anatomy of an Acceptance Test](#anatomy-of-an-acceptance-test)
     - [Resource Acceptance Testing](#resource-acceptance-testing)
@@ -20,6 +21,7 @@
         - [ErrorChecks](#errorchecks)
             - [Common ErrorCheck](#common-errorcheck)
             - [Service-Specific ErrorChecks](#service-specific-errorchecks)
+        - [Long-Running Test Guards](#long-running-test-guards)
         - [Disappears Acceptance Tests](#disappears-acceptance-tests)
         - [Per Attribute Acceptance Tests](#per-attribute-acceptance-tests)
         - [Cross-Account Acceptance Tests](#cross-account-acceptance-tests)
@@ -173,6 +175,26 @@ export AWS_ALTERNATE_REGION=...
 export AWS_THIRD_REGION=...
 ```
 
+### Running Only Short Tests
+
+Some tests have been manually marked as long-running (longer than 300 seconds) and can be skipped using the `-short` flag. However, implementation of the long-running guards is a work in progress and many services have no tests guarded.
+
+Where guards have been implemented, do not always skip long-running tests. However, for intermediate test runs during development, or to verify functionality unrelated to the specific long-running tests, skipping long-running tests makes work more efficient. We recommend that for the final test run before submitting a PR that you run affected tests without the `-short` flag.
+
+If you want to run only short-running tests, you can use either one of these equivalent statements. Note the use of `-short`.
+
+For example:
+
+```console
+% make testacc TESTS='TestAccECSTaskDefinition_' PKG=ecs TESTARGS=-short
+```
+
+Or:
+
+```console
+% TF_ACC=1 go test ./internal/service/ecs/... -v -count 1 -parallel 20 -run='TestAccECSTaskDefinition_' -short -timeout 180m
+```
+
 ## Writing an Acceptance Test
 
 Terraform has a framework for writing acceptance tests which minimises the
@@ -446,6 +468,22 @@ resource "aws_example_thing" "test" {
 
 Typically the `rName` is always the first argument to the test configuration function, if used, for consistency.
 
+Note that if `rName` (or any other variable) is used multiple times in the `fmt.Sprintf()` statement, _do not_ repeat `rName` in the `fmt.Sprintf()` arguments. Using `fmt.Sprintf(..., rName, rName)`, for example, would not be correct. Instead, use the indexed `%[1]q` (or `%[x]q`, `%[x]s`, `%[x]t`, or `%[x]d`, where `x` represents the index number) verb multiple times. For example:
+
+```go
+func testAccExampleThingConfigName(rName string) string {
+  return fmt.Sprintf(`
+resource "aws_example_thing" "test" {
+  name = %[1]q
+
+  tags = {
+    Name = %[1]q
+  }
+}
+`, rName)
+}
+```
+
 #### Other Recommended Variables
 
 We also typically recommend saving a `resourceName` variable in the test that contains the resource reference, e.g., `aws_example_thing.test`, which is repeatedly used in the checks.
@@ -665,6 +703,29 @@ func testAccErrorCheckSkipService(t *testing.T) resource.ErrorCheckFunc {
 }
 ```
 
+#### Long-Running Test Guards
+
+For any acceptance tests that typically run longer than 300 seconds (5 minutes), add a `-short` test guard before the `resource.ParallelTest()` (or `resource.Test()`) statement.
+
+For example:
+
+```go
+func TestAccExampleThing_longRunningTest(t *testing.T) {
+  rName := sdkacctest.RandomWithPrefix(acctest.ResourcePrefix)
+  resourceName := "aws_example_thing.test"
+
+  if testing.Short() {
+    t.Skip("skipping long-running test in short mode")
+  }
+
+  resource.ParallelTest(t, resource.TestCase{
+    // ... omitted for brevity ...
+  })
+}
+```
+
+When running acceptances tests, tests with these guards can be skipped using the Go `-short` flag. See [Running Only Short Tests](#running-only-short-tests) for examples.
+
 #### Disappears Acceptance Tests
 
 This test is generally implemented second. It is straightforward to setup once the basic test is passing since it can reuse that test configuration. It prevents a common bug report with Terraform resources that error when they can not be found (e.g., deleted outside Terraform).