helper/resource: introduce testOutcome type

In the plugin test framework, the core test step logic can indicate
error in two different ways:

- Return an `error` to the plugin test framework. This is the plugin
  test framework's facility for test authors to make positive or
  negative assertions for their provider's behavior. The test author
  supplies a `TestStep.ExpectError` to match on the error.

- Call the Go testing library's `t.Fatal`. This is a lower-level error
  that a test author cannot make assertions on.

Core test step logic -- such as `ImportState` -- does both of these. The
reason for using one or the other can be subtle and implicit. This
poses a cognitive hurdle for contributing code changes. It also poses a
hurdle to refactoring and breaking down large functions into smaller
ones: does every smaller function need a `testing.T` parameter so that
it can call `t.Fatal`?

This change separates concerns by introducing a type to embed the first
type of error in a result object: framework: `testOutcome`.

Smaller functions can return two values: `testOutcome` and `error`, with
the latter indicating a fatal error.

A test step's entry point -- such as `testStepNewImportState` -- is the
one place that knows that an `error` translates to `t.Fatalf` and a
failed `testOutcome` is simply returned to the plugin test framework.

Author: bbasata

helper/resource/testing_new_import_state.go

@@ -25,17 +25,54 @@ import (
 	"github.com/hashicorp/terraform-plugin-testing/tfversion"
 )
 
+type testOutcome struct {
+	ok      bool
+	message string
+	err     error
+}
+
+var testOK = testOutcome{ok: true}
+var testFail = func(format string, a ...any) testOutcome {
+	return testOutcome{
+		ok:      false,
+		message: fmt.Sprintf(format, a...),
+	}
+}
+var testFailErr = func(err error) testOutcome {
+	return testOutcome{
+		ok:  false,
+		err: err,
+	}
+}
+
 func testStepNewImportState(ctx context.Context, t testing.T, helper *plugintest.Helper, wd *plugintest.WorkingDir, step TestStep, cfgRaw string, providers *providerFactories, stepNumber int) error {
 	t.Helper()
 
+	outcome, fatalErr := runImportTestStep(ctx, t, helper, wd, step, cfgRaw, providers, stepNumber)
+	if fatalErr != nil {
+		t.Fatal(fatalErr)
+	}
+
+	switch {
+	case outcome.err != nil:
+		return outcome.err
+	case !outcome.ok:
+		return fmt.Errorf(outcome.message)
+	default:
+		return nil
+	}
+}
+func runImportTestStep(ctx context.Context, t testing.T, helper *plugintest.Helper, wd *plugintest.WorkingDir, step TestStep, cfgRaw string, providers *providerFactories, stepNumber int) (testOutcome, error) {
+	t.Helper()
+
 	// step.ImportStateKind implicitly defaults to the zero-value (ImportCommandWithID) for backward compatibility
 	kind := step.ImportStateKind
 	if kind.plannable() {
 		// Instead of calling [t.Fatal], return an error. This package's unit tests can use [TestStep.ExpectError] to match on the error message.
 		// An alternative, [plugintest.TestExpectTFatal], does not have access to logged error messages, so it is open to false positives on this
 		// complex code path.
 		if err := requirePlannableImport(t, *helper.TerraformVersion()); err != nil {
-			return err
+			return testFailErr(err), nil
 		}
 	}
 
@@ -172,7 +209,7 @@ func testStepNewImportState(ctx context.Context, t testing.T, helper *plugintest
 			return importWd.CreatePlan(ctx, opts...)
 		}, importWd, providers)
 		if err != nil {
-			return err
+			return testFailErr(err), nil
 		}
 
 		err = runProviderCommand(ctx, t, func() error {
@@ -182,7 +219,7 @@ func testStepNewImportState(ctx context.Context, t testing.T, helper *plugintest
 			return err
 		}, importWd, providers)
 		if err != nil {
-			return err
+			return testFailErr(err), nil
 		}
 
 		if plan.ResourceChanges != nil {
@@ -204,10 +241,10 @@ func testStepNewImportState(ctx context.Context, t testing.T, helper *plugintest
 								return err
 							}, importWd, providers)
 							if err != nil {
-								return fmt.Errorf("retrieving formatted plan output: %w", err)
+								return testFail("retrieving formatted plan output: %w", err), nil
 							}
 
-							return fmt.Errorf("importing resource %s: expected a no-op resource action, got %q action with plan \nstdout:\n\n%s", rc.Address, action, stdout)
+							return testFail("importing resource %s: expected a no-op resource action, got %q action with plan \nstdout:\n\n%s", rc.Address, action, stdout), nil
 						}
 					}
 				}
@@ -217,14 +254,14 @@ func testStepNewImportState(ctx context.Context, t testing.T, helper *plugintest
 		// TODO compare plan to state from previous step
 
 		if err := runPlanChecks(ctx, t, plan, step.ImportPlanChecks.PreApply); err != nil {
-			return err
+			return testFailErr(err), nil
 		}
 	} else {
 		err = runProviderCommand(ctx, t, func() error {
 			return importWd.Import(ctx, resourceName, importId)
 		}, importWd, providers)
 		if err != nil {
-			return err
+			return testFailErr(err), nil
 		}
 	}
 
@@ -380,13 +417,13 @@ func testStepNewImportState(ctx context.Context, t testing.T, helper *plugintest
 				}
 
 				if diff := cmp.Diff(expected, actual); diff != "" {
-					return fmt.Errorf("ImportStateVerify attributes not equivalent. Difference is shown below. The - symbol indicates attributes missing after import.\n\n%s", diff)
+					return testFail("ImportStateVerify attributes not equivalent. Difference is shown below. The - symbol indicates attributes missing after import.\n\n%s", diff), nil
 				}
 			}
 		}
 	}
 
-	return nil
+	return testOK, nil
 }
 
 func appendImportBlock(config string, resourceName string, importID string) string {