feat: add state_key for test run blocks

CHANGELOG.md

@@ -3,6 +3,7 @@
 ENHANCEMENTS:
 
 - `init`: Provider installation will utilise credentials configured in a `.netrc` file for the download and shasum URLs returned by provider registries. ([https://github.com/hashicorp/terraform/pull/35843](35843))
+- The `terraform test` command now supports a `state_key` attribute in `run` blocks. This feature allows multiple Terraform test runs to target the same infrastructure.
 
 EXPERIMENTS:
 

internal/backend/local/test.go

@@ -346,12 +346,16 @@ func (runner *TestFileRunner) Test(file *moduletest.File) {
 				file.Status = moduletest.Error
 				continue // Abort!
 			}
+		}
 
-			if _, exists := runner.RelevantStates[key]; !exists {
-				runner.RelevantStates[key] = &TestFileState{
-					Run:   nil,
-					State: states.NewState(),
-				}
+		if run.Config.StateKey != "" {
+			key = run.Config.StateKey
+		}
+
+		if _, exists := runner.RelevantStates[key]; !exists {
+			runner.RelevantStates[key] = &TestFileState{
+				Run:   nil,
+				State: states.NewState(),
 			}
 		}
 

internal/command/test_test.go

@@ -275,6 +275,11 @@ func TestTest_Runs(t *testing.T) {
 			expectedErr: []string{"Ephemeral resource instance has expired", "Ephemeral resources cannot be asserted"},
 			code:        1,
 		},
+		"with_state_key": {
+			expectedOut: []string{"3 passed, 1 failed."},
+			expectedErr: []string{"Test assertion failed", "resource renamed without moved block"},
+			code:        1,
+		},
 	}
 	for name, tc := range tcs {
 		t.Run(name, func(t *testing.T) {

internal/command/testdata/test/with_state_key/breaking_change.tftest.hcl

@@ -0,0 +1,14 @@
+run "old_version" {
+  state_key = "test1"
+}
+
+run "new_code" {
+  state_key = "test1"
+  module {
+    source = "./breaking_change"
+  }
+  assert {
+    condition = test_resource.renamed_without_move.id == run.old_version.test_id
+    error_message = "resource renamed without moved block"
+  }
+}

internal/command/testdata/test/with_state_key/breaking_change/main.tf

@@ -0,0 +1,7 @@
+resource "test_resource" "renamed_without_move" {
+  value = "test"
+}
+
+output "test_id" {
+  value = test_resource.renamed_without_move.id
+}

internal/command/testdata/test/with_state_key/main.tf

@@ -0,0 +1,11 @@
+resource "test_resource" "test_id_moved" {
+}
+
+output "test_id" {
+  value = test_resource.test_id_moved.id
+}
+
+moved {
+  from = test_resource.test_id
+  to   = test_resource.test_id_moved
+}

internal/command/testdata/test/with_state_key/moved.tftest.hcl

@@ -0,0 +1,14 @@
+run "old_version" {
+  state_key = "test1"
+  module {
+    source = "./old_version"
+  }
+}
+
+run "new_code" {
+  state_key = "test1"
+  assert {
+    condition = test_resource.test_id_moved.id == run.old_version.test_id
+    error_message = "ressource_id differed"
+  }
+}

internal/command/testdata/test/with_state_key/old_version/main.tf

@@ -0,0 +1,7 @@
+resource "test_resource" "test_id" {
+  value = "test"
+}
+
+output "test_id" {
+  value = test_resource.test_id.id
+}

internal/configs/test_file.go

@@ -133,6 +133,8 @@ type TestRun struct {
 	// run.
 	ExpectFailures []hcl.Traversal
 
+	StateKey string
+
 	NameDeclRange      hcl.Range
 	VariablesDeclRange hcl.Range
 	DeclRange          hcl.Range
@@ -606,6 +608,11 @@ func decodeTestRunBlock(block *hcl.Block) (*TestRun, hcl.Diagnostics) {
 		r.ExpectFailures = failures
 	}
 
+	if attr, exists := content.Attributes["state_key"]; exists {
+		rawDiags := gohcl.DecodeExpression(attr.Expr, nil, &r.StateKey)
+		diags = append(diags, rawDiags...)
+	}
+
 	return &r, diags
 }
 
@@ -807,6 +814,7 @@ var testRunBlockSchema = &hcl.BodySchema{
 		{Name: "command"},
 		{Name: "providers"},
 		{Name: "expect_failures"},
+		{Name: "state_key"},
 	},
 	Blocks: []hcl.BlockHeaderSchema{
 		{

website/docs/language/tests/index.mdx

@@ -91,6 +91,7 @@ Each `run` block has the following fields and blocks:
 | [`providers`](#providers) | An optional `providers` attribute.                                                                                       |               |
 | [`assert`](#assertions)   | Optional `assert` blocks.                                                                                                |               |
 | `expect_failures`         | An optional attribute.                                                                                                   |               |
+| `state_key`               | An optional attribute, which can be used to test multiple run blocks on the same infrastructure                          |               |
 
 The `command` attribute and `plan_options` block tell Terraform which command and options to execute for each run block. The default operation, if you do not specify a `command` attribute or the `plan_options` block, is a normal Terraform apply operation.