Updating docs for config pkg (#150)

config/config.go

@@ -4,12 +4,24 @@
 package config
 
 // TestStepConfigFunc is the callback type used with acceptance tests to
-// specify a string which identifies a directory containing Terraform
-// configuration files, or a file that contains Terraform configuration.
+// specify a string which either identifies a directory containing
+// Terraform configuration files, or a file that contains Terraform
+// configuration.
 type TestStepConfigFunc func(TestStepConfigRequest) string
 
 // TestStepConfigRequest defines the request supplied to types
-// implementing TestStepConfigFunc.
+// implementing TestStepConfigFunc. StepNumber is used in the
+// predefined helper functions:
+//
+//   - [config.TestStepDirectory]
+//   - [config.TestStepFile].
+//
+// TestName is used in the predefined helper functions:
+//
+//   - [config.TestNameDirectory]
+//   - [config.TestStepDirectory]
+//   - [config.TestNameFile]
+//   - [config.TestStepFile]
 type TestStepConfigRequest struct {
 	StepNumber int
 	TestName   string

config/directory.go

@@ -8,17 +8,15 @@ import (
 	"strconv"
 )
 
-// StaticDirectory is a helper function that returns the supplied
-// directory when TestStepConfigFunc is executed.
+// StaticDirectory returns the supplied directory.
 func StaticDirectory(directory string) func(TestStepConfigRequest) string {
 	return func(_ TestStepConfigRequest) string {
 		return directory
 	}
 }
 
-// TestNameDirectory returns the name of the test when TestStepConfigFunc
-// is executed. This facilitates a convention of naming directories
-// containing Terraform configuration files with the name of the test.
+// TestNameDirectory returns the name of the test prefixed with
+// "testdata".
 //
 // For example, given test code:
 //
@@ -40,8 +38,23 @@ func TestNameDirectory() func(TestStepConfigRequest) string {
 	}
 }
 
-// TestStepDirectory returns the name of the test suffixed
-// with the test step number.
+// TestStepDirectory returns the name of the test suffixed with the
+// test step number and prefixed with "testdata".
+//
+// For example, given test code:
+//
+//	func TestExampleCloudThing_basic(t *testing.T) {
+//	    resource.Test(t, resource.TestCase{
+//	        Steps: []resource.TestStep{
+//	            {
+//	                ConfigDirectory: config.TestStepDirectory(),
+//	            },
+//	        },
+//	    })
+//	}
+//
+// The testing configurations will be expected in the
+// testdata/TestExampleCloudThing_basic/1 directory.
 func TestStepDirectory() func(TestStepConfigRequest) string { //nolint:paralleltest //Not a test
 	return func(req TestStepConfigRequest) string {
 		return filepath.Join("testdata", req.TestName, strconv.Itoa(req.StepNumber))

config/config_test.go → config/directory_test.go

@@ -9,7 +9,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-testing/config"
 )
 
-func TestTestStepConfigFunc_Exec(t *testing.T) {
+func TestTestStepConfigFunc_Exec_Directory(t *testing.T) {
 	t.Parallel()
 
 	testCases := map[string]struct {
@@ -36,25 +36,6 @@ func TestTestStepConfigFunc_Exec(t *testing.T) {
 			},
 			expected: "testdata/TestTestStepConfigFunc_Exec/1",
 		},
-		"static_file": {
-			testStepConfigFunc: config.StaticFile("name_of_file"),
-			expected:           "name_of_file",
-		},
-		"test_name_file": {
-			testStepConfigFunc: config.TestNameFile("test.tf"),
-			testStepConfigRequest: config.TestStepConfigRequest{
-				TestName: "TestTestStepConfigFunc_Exec",
-			},
-			expected: "testdata/TestTestStepConfigFunc_Exec/test.tf",
-		},
-		"test_step_file": {
-			testStepConfigFunc: config.TestStepFile("test.tf"),
-			testStepConfigRequest: config.TestStepConfigRequest{
-				StepNumber: 1,
-				TestName:   "TestTestStepConfigFunc_Exec",
-			},
-			expected: "testdata/TestTestStepConfigFunc_Exec/1/test.tf",
-		},
 	}
 
 	for name, testCase := range testCases {

config/file.go

@@ -8,16 +8,15 @@ import (
 	"strconv"
 )
 
-// StaticFile is a helper function that returns the supplied
-// file when TestStepConfigFunc is executed.
+// StaticFile returns the supplied file.
 func StaticFile(file string) func(TestStepConfigRequest) string {
 	return func(_ TestStepConfigRequest) string {
 		return file
 	}
 }
 
 // TestNameFile returns the name of the test suffixed with the supplied
-// file name when TestStepConfigFunc is executed (e.g., "testdata/TestExampleCloudThing_basic/test.tf.
+// file and prefixed with "testdata".
 //
 // For example, given test code:
 //
@@ -39,8 +38,23 @@ func TestNameFile(file string) func(TestStepConfigRequest) string {
 	}
 }
 
-// TestStepFile returns the name of the test suffixed
-// with the test step number and the supplied file name.
+// TestStepFile returns the name of the test suffixed with the test
+// step number and the supplied file, and prefixed with "testdata".
+//
+// For example, given test code:
+//
+//	func TestExampleCloudThing_basic(t *testing.T) {
+//	    resource.Test(t, resource.TestCase{
+//	        Steps: []resource.TestStep{
+//	            {
+//	                ConfigFile: config.TestStepFile("test.tf"),
+//	            },
+//	        },
+//	    })
+//	}
+//
+// The testing configuration will be expected in the
+// testdata/TestExampleCloudThing_basic/1/test.tf file.
 func TestStepFile(file string) func(TestStepConfigRequest) string { //nolint:paralleltest //Not a test
 	return func(req TestStepConfigRequest) string {
 		return filepath.Join("testdata", req.TestName, strconv.Itoa(req.StepNumber), file)

config/file_test.go

@@ -0,0 +1,54 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package config_test
+
+import (
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-testing/config"
+)
+
+func TestTestStepConfigFunc_Exec_File(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		testStepConfigFunc    config.TestStepConfigFunc
+		testStepConfigRequest config.TestStepConfigRequest
+		expected              string
+	}{
+		"static_file": {
+			testStepConfigFunc: config.StaticFile("name_of_file"),
+			expected:           "name_of_file",
+		},
+		"test_name_file": {
+			testStepConfigFunc: config.TestNameFile("test.tf"),
+			testStepConfigRequest: config.TestStepConfigRequest{
+				TestName: "TestTestStepConfigFunc_Exec",
+			},
+			expected: "testdata/TestTestStepConfigFunc_Exec/test.tf",
+		},
+		"test_step_file": {
+			testStepConfigFunc: config.TestStepFile("test.tf"),
+			testStepConfigRequest: config.TestStepConfigRequest{
+				StepNumber: 1,
+				TestName:   "TestTestStepConfigFunc_Exec",
+			},
+			expected: "testdata/TestTestStepConfigFunc_Exec/1/test.tf",
+		},
+	}
+
+	for name, testCase := range testCases {
+		name, testCase := name, testCase
+
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			got := testCase.testStepConfigFunc.Exec(testCase.testStepConfigRequest)
+
+			if testCase.expected != got {
+				t.Errorf("expected %s, got %s", testCase.expected, got)
+			}
+		})
+	}
+}