all: Add ephemeral resource schema and lifecycle tests

go.mod

@@ -11,7 +11,7 @@ require (
 	github.com/hashicorp/terraform-plugin-go v0.25.0
 	github.com/hashicorp/terraform-plugin-mux v0.17.0
 	github.com/hashicorp/terraform-plugin-sdk/v2 v2.35.0
-	github.com/hashicorp/terraform-plugin-testing v1.10.0
+	github.com/hashicorp/terraform-plugin-testing v1.10.1-0.20241112232341-e5b632d36863
 	github.com/zclconf/go-cty v1.15.0
 )
 

go.sum

@@ -95,8 +95,8 @@ github.com/hashicorp/terraform-plugin-mux v0.17.0 h1:/J3vv3Ps2ISkbLPiZOLspFcIZ0v
 github.com/hashicorp/terraform-plugin-mux v0.17.0/go.mod h1:yWuM9U1Jg8DryNfvCp+lH70WcYv6D8aooQxxxIzFDsE=
 github.com/hashicorp/terraform-plugin-sdk/v2 v2.35.0 h1:wyKCCtn6pBBL46c1uIIBNUOWlNfYXfXpVo16iDyLp8Y=
 github.com/hashicorp/terraform-plugin-sdk/v2 v2.35.0/go.mod h1:B0Al8NyYVr8Mp/KLwssKXG1RqnTk7FySqSn4fRuLNgw=
-github.com/hashicorp/terraform-plugin-testing v1.10.0 h1:2+tmRNhvnfE4Bs8rB6v58S/VpqzGC6RCh9Y8ujdn+aw=
-github.com/hashicorp/terraform-plugin-testing v1.10.0/go.mod h1:iWRW3+loP33WMch2P/TEyCxxct/ZEcCGMquSLSCVsrc=
+github.com/hashicorp/terraform-plugin-testing v1.10.1-0.20241112232341-e5b632d36863 h1:1BV2qGnJyCG0j9IuC8tETeEqGm5n32oqZWnPpMCPYJI=
+github.com/hashicorp/terraform-plugin-testing v1.10.1-0.20241112232341-e5b632d36863/go.mod h1:KO4JzpCD5O7tSKZk20W70X2tpna9pIEoiTQD6cS8VrU=
 github.com/hashicorp/terraform-registry-address v0.2.3 h1:2TAiKJ1A3MAkZlH1YI/aTVcLZRu7JseiXNRHbOAyoTI=
 github.com/hashicorp/terraform-registry-address v0.2.3/go.mod h1:lFHA76T8jfQteVfT7caREqguFrW3c4MFSPhZB7HHgUM=
 github.com/hashicorp/terraform-svchost v0.1.1 h1:EZZimZ1GxdqFRinZ1tpJwVxxt49xc/S52uzrw4x0jKQ=

internal/framework5provider/deferred_action_resource_test.go

@@ -21,7 +21,7 @@ func TestDeferredActionResource_ProviderDeferral(t *testing.T) {
 	resource.UnitTest(t, resource.TestCase{
 		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
 			tfversion.SkipBelow(tfversion.Version1_9_0),
-			tfversion.SkipIfNotPrerelease(),
+			tfversion.SkipIfNotAlpha(),
 		},
 		AdditionalCLIOptions: &resource.AdditionalCLIOptions{
 			Plan:  resource.PlanOptions{AllowDeferral: true},
@@ -90,7 +90,7 @@ func TestDeferredActionPlanModificationResource_ProviderDeferral(t *testing.T) {
 	resource.UnitTest(t, resource.TestCase{
 		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
 			tfversion.SkipBelow(tfversion.Version1_9_0),
-			tfversion.SkipIfNotPrerelease(),
+			tfversion.SkipIfNotAlpha(),
 		},
 		AdditionalCLIOptions: &resource.AdditionalCLIOptions{
 			Plan:  resource.PlanOptions{AllowDeferral: true},
@@ -169,7 +169,7 @@ func TestDeferredActionResource_ModifyPlanDeferral(t *testing.T) {
 	resource.UnitTest(t, resource.TestCase{
 		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
 			tfversion.SkipBelow(tfversion.Version1_9_0),
-			tfversion.SkipIfNotPrerelease(),
+			tfversion.SkipIfNotAlpha(),
 		},
 		AdditionalCLIOptions: &resource.AdditionalCLIOptions{
 			Plan:  resource.PlanOptions{AllowDeferral: true},
@@ -211,7 +211,7 @@ func TestDeferredActionResource_ReadDeferral(t *testing.T) {
 	resource.UnitTest(t, resource.TestCase{
 		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
 			tfversion.SkipBelow(tfversion.Version1_9_0),
-			tfversion.SkipIfNotPrerelease(),
+			tfversion.SkipIfNotAlpha(),
 		},
 		AdditionalCLIOptions: &resource.AdditionalCLIOptions{
 			Plan:  resource.PlanOptions{AllowDeferral: true},
@@ -240,7 +240,7 @@ func TestDeferredActionResource_ImportStateDeferral(t *testing.T) {
 	resource.UnitTest(t, resource.TestCase{
 		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
 			tfversion.SkipBelow(tfversion.Version1_9_0),
-			tfversion.SkipIfNotPrerelease(),
+			tfversion.SkipIfNotAlpha(),
 		},
 		AdditionalCLIOptions: &resource.AdditionalCLIOptions{
 			Plan:  resource.PlanOptions{AllowDeferral: true},

internal/framework5provider/ephemeral_lifecycle_resource.go

@@ -0,0 +1,107 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package framework
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral/schema"
+	"github.com/hashicorp/terraform-plugin-framework/path"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+var (
+	_ ephemeral.EphemeralResourceWithConfigure = &EphemeralLifecycleResource{}
+	_ ephemeral.EphemeralResourceWithRenew     = &EphemeralLifecycleResource{}
+	_ ephemeral.EphemeralResourceWithClose     = &EphemeralLifecycleResource{}
+)
+
+func NewEphemeralLifecycleResource() ephemeral.EphemeralResource {
+	return &EphemeralLifecycleResource{}
+}
+
+// EphemeralLifecycleResource is for testing the ephemeral resource lifecycle (Open, Renew, Close)
+type EphemeralLifecycleResource struct {
+	spyClient *EphemeralResourceSpyClient
+}
+
+type EphemeralLifecycleResourceModel struct {
+	Name  types.String `tfsdk:"name"`
+	Token types.String `tfsdk:"token"`
+}
+
+func (e *EphemeralLifecycleResource) Metadata(ctx context.Context, req ephemeral.MetadataRequest, resp *ephemeral.MetadataResponse) {
+	resp.TypeName = req.ProviderTypeName + "_lifecycle"
+}
+
+func (e *EphemeralLifecycleResource) Schema(ctx context.Context, req ephemeral.SchemaRequest, resp *ephemeral.SchemaResponse) {
+	resp.Schema = schema.Schema{
+		Attributes: map[string]schema.Attribute{
+			"name": schema.StringAttribute{
+				Required: true,
+			},
+			"token": schema.StringAttribute{
+				Computed: true,
+			},
+		},
+	}
+}
+
+func (e *EphemeralLifecycleResource) Configure(ctx context.Context, req ephemeral.ConfigureRequest, resp *ephemeral.ConfigureResponse) {
+	if req.ProviderData == nil {
+		return
+	}
+
+	spyClient, ok := req.ProviderData.(*EphemeralResourceSpyClient)
+
+	if !ok {
+		resp.Diagnostics.AddError(
+			"Unexpected Ephemeral Resource Configure Type",
+			fmt.Sprintf("Expected *EphemeralResourceSpyClient, got: %T.", req.ProviderData),
+		)
+
+		return
+	}
+
+	e.spyClient = spyClient
+}
+
+func (e *EphemeralLifecycleResource) Open(ctx context.Context, req ephemeral.OpenRequest, resp *ephemeral.OpenResponse) {
+	var data EphemeralLifecycleResourceModel
+
+	resp.Diagnostics.Append(req.Config.Get(ctx, &data)...)
+	if resp.Diagnostics.HasError() {
+		return
+	}
+
+	if data.Name.IsUnknown() {
+		resp.Diagnostics.AddAttributeError(
+			path.Root("name"),
+			"Unknown value encountered in Open lifecycle handler",
+			`The "name" attribute should never be unknown, Terraform core should skip executing the Open lifecycle handler until the value becomes known.`,
+		)
+		return
+	}
+
+	data.Token = types.StringValue("fake-token-12345")
+
+	// Renew in 5 seconds
+	resp.RenewAt = time.Now().Add(5 * time.Second)
+
+	resp.Diagnostics.Append(resp.Result.Set(ctx, &data)...)
+}
+
+func (e *EphemeralLifecycleResource) Renew(ctx context.Context, req ephemeral.RenewRequest, resp *ephemeral.RenewResponse) {
+	e.spyClient.Renew()
+
+	// Renew again in 5 seconds
+	resp.RenewAt = time.Now().Add(5 * time.Second)
+}
+
+func (e *EphemeralLifecycleResource) Close(ctx context.Context, req ephemeral.CloseRequest, resp *ephemeral.CloseResponse) {
+	e.spyClient.Close()
+}

internal/framework5provider/ephemeral_lifecycle_resource_test.go

@@ -0,0 +1,121 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package framework
+
+import (
+	"fmt"
+	"regexp"
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-framework/providerserver"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov5"
+	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
+	"github.com/hashicorp/terraform-plugin-testing/echoprovider"
+	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
+	"github.com/hashicorp/terraform-plugin-testing/terraform"
+	"github.com/hashicorp/terraform-plugin-testing/tfversion"
+)
+
+// This test is a smoke test for the ephemeral resource lifecycle (Open, Renew, and Close).
+func TestEphemeralLifecycleResource_basic(t *testing.T) {
+	t.Parallel()
+
+	spyClient := &EphemeralResourceSpyClient{}
+	resource.UnitTest(t, resource.TestCase{
+		// Ephemeral resources are only available in 1.10 and later
+		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
+			tfversion.SkipBelow(tfversion.Version1_10_0),
+		},
+		ExternalProviders: map[string]resource.ExternalProvider{
+			"time": {
+				Source: "hashicorp/time",
+			},
+		},
+		ProtoV5ProviderFactories: map[string]func() (tfprotov5.ProviderServer, error){
+			"framework": providerserver.NewProtocol5WithError(NewWithEphemeralSpy(spyClient)),
+		},
+		ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error){
+			"echo": echoprovider.NewProviderServer(),
+		},
+		Steps: []resource.TestStep{
+			{
+				Config: `
+				ephemeral "framework_lifecycle" "test" {
+					name = "John Doe"
+				}
+				resource "time_sleep" "wait_20_seconds" {
+					depends_on = [ephemeral.framework_lifecycle.test]
+					create_duration = "20s"
+				}`,
+			},
+		},
+		CheckDestroy: func(_ *terraform.State) error {
+			// We only really care that renew was being invoked multiple times, it should always be 4 invocations (with no skew), but we'll give a little leeway here.
+			if spyClient.RenewInvocations() < 3 {
+				t.Errorf("Renew lifecycle handler should have been executed at least 3 times (5s renewals in 20s), but was only executed %d times", spyClient.RenewInvocations())
+			}
+
+			// Close will be invoked 6 times (due to all of the planning/refreshing of the testing framework), but we only care that it was executed once.
+			if spyClient.CloseInvocations() < 1 {
+				t.Errorf("Close lifecycle handler should have been executed at least once")
+			}
+
+			return nil
+		},
+	})
+}
+
+// This test ensures that Terraform will skip invoking an ephemeral resource when unknown values are present in configuration.
+// The framework_lifecycle ephemeral resource will return a diagnostic if an unknown value is encountered in "name".
+func TestEphemeralLifecycleResource_SkipWithUnknown(t *testing.T) {
+	t.Parallel()
+
+	resource.UnitTest(t, resource.TestCase{
+		// Ephemeral resources are only available in 1.10 and later
+		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
+			tfversion.SkipBelow(tfversion.Version1_10_0),
+		},
+		ExternalProviders: map[string]resource.ExternalProvider{
+			"random": {
+				Source: "hashicorp/random",
+			},
+		},
+		ProtoV5ProviderFactories: map[string]func() (tfprotov5.ProviderServer, error){
+			"framework": providerserver.NewProtocol5WithError(New()),
+		},
+		ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error){
+			"echo": echoprovider.NewProviderServer(),
+		},
+		Steps: []resource.TestStep{
+			{
+				Config: addEchoToEphemeralLifecycleConfig(`
+					resource "random_string" "str" {
+						length = 12
+					}
+
+					ephemeral "framework_lifecycle" "test" {
+						name = "John ${random_string.str.result}"
+					}`),
+				// TODO: This is currently a known bug in Terraform v1.10.0-beta1. Once that bug is fixed, this test will fail, and then
+				// we can remove the ExpectError and uncomment the state checks.
+				ExpectError: regexp.MustCompile(`Unknown value encountered in Open lifecycle handler`),
+				// ConfigStateChecks: []statecheck.StateCheck{
+				// 	statecheck.ExpectKnownValue("echo.lifecycle_test", echoDataPath.AtMapKey("name"), knownvalue.StringRegexp(regexp.MustCompile(`^John\s.{12}$`))),
+				// 	statecheck.ExpectKnownValue("echo.lifecycle_test", echoDataPath.AtMapKey("token"), knownvalue.StringExact("fake-token-12345")),
+				// },
+			},
+		},
+	})
+}
+
+// Adds the test echo provider to enable using state checks with ephemeral resources
+func addEchoToEphemeralLifecycleConfig(cfg string) string {
+	return fmt.Sprintf(`
+	%s
+	provider "echo" {
+		data = ephemeral.framework_lifecycle.test
+	}
+	resource "echo" "lifecycle_test" {}
+	`, cfg)
+}

internal/framework5provider/ephemeral_resource_spy_client.go

@@ -0,0 +1,30 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package framework
+
+// EphemeralResourceSpyClient is used in tests to verify that an ephemeral resource lifecycle handler has been executed.
+type EphemeralResourceSpyClient struct {
+	renewInvocations int
+	closeInvocations int
+}
+
+// Renew will increment the number of invocations for this instance, which can be retrieved with the `RenewInvocations` method
+func (e *EphemeralResourceSpyClient) Renew() {
+	e.renewInvocations++
+}
+
+// RenewInvocations returns the number of times the `Renew` method has been called on this instance.
+func (e *EphemeralResourceSpyClient) RenewInvocations() int {
+	return e.renewInvocations
+}
+
+// Close will increment the number of invocations for this instance, which can be retrieved with the `CloseInvocations` method
+func (e *EphemeralResourceSpyClient) Close() {
+	e.closeInvocations++
+}
+
+// CloseInvocations returns the number of times the `Close` method has been called on this instance.
+func (e *EphemeralResourceSpyClient) CloseInvocations() int {
+	return e.closeInvocations
+}

internal/framework5provider/provider.go

@@ -7,6 +7,7 @@ import (
 	"context"
 
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/ephemeral"
 	"github.com/hashicorp/terraform-plugin-framework/function"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
 	"github.com/hashicorp/terraform-plugin-framework/provider/schema"
@@ -17,14 +18,25 @@ import (
 )
 
 var (
-	_ provider.ProviderWithFunctions = (*testProvider)(nil)
+	_ provider.ProviderWithFunctions          = (*testProvider)(nil)
+	_ provider.ProviderWithEphemeralResources = (*testProvider)(nil)
 )
 
 func New() provider.Provider {
-	return &testProvider{}
+	return &testProvider{
+		ephSpyClient: &EphemeralResourceSpyClient{},
+	}
+}
+
+func NewWithEphemeralSpy(spy *EphemeralResourceSpyClient) provider.Provider {
+	return &testProvider{
+		ephSpyClient: spy,
+	}
 }
 
-type testProvider struct{}
+type testProvider struct {
+	ephSpyClient *EphemeralResourceSpyClient
+}
 
 func (p *testProvider) Metadata(_ context.Context, _ provider.MetadataRequest, resp *provider.MetadataResponse) {
 	resp.TypeName = "framework"
@@ -61,6 +73,7 @@ func (p *testProvider) Configure(ctx context.Context, req provider.ConfigureRequ
 		}
 	}
 	resp.ResourceData = client
+	resp.EphemeralResourceData = p.ephSpyClient
 }
 
 func (p *testProvider) Resources(_ context.Context) []func() resource.Resource {
@@ -105,6 +118,13 @@ func (p *testProvider) Functions(ctx context.Context) []func() function.Function
 	}
 }
 
+func (p *testProvider) EphemeralResources(ctx context.Context) []func() ephemeral.EphemeralResource {
+	return []func() ephemeral.EphemeralResource{
+		NewSchemaEphemeralResource,
+		NewEphemeralLifecycleResource,
+	}
+}
+
 type providerConfig struct {
 	Dummy    types.String `tfsdk:"dummy"`
 	Deferral types.Bool   `tfsdk:"deferral"`