How to perform a test of a terraform action

[remyleone]

terraform-plugin-testing version

github.com/hashicorp/terraform-plugin-testing v1.13.3

Relevant provider source code

package instance

import (
	"context"
	"fmt"

	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
	"github.com/hashicorp/terraform-plugin-framework/action"
	"github.com/hashicorp/terraform-plugin-framework/action/schema"
	"github.com/hashicorp/terraform-plugin-framework/schema/validator"
	"github.com/hashicorp/terraform-plugin-framework/types"
	"github.com/scaleway/scaleway-sdk-go/api/instance/v1"
	"github.com/scaleway/scaleway-sdk-go/scw"
)

var (
	_ action.Action = (*ServerAction)(nil)
)

type ServerAction struct {
	instanceAPI *instance.API
}

func (a *ServerAction) Configure(ctx context.Context, req action.ConfigureRequest, resp *action.ConfigureResponse) {
	if req.ProviderData == nil {
		return
	}

	client, ok := req.ProviderData.(*scw.Client)
	if !ok {
		resp.Diagnostics.AddError(
			"Unexpected Action Configure Type",
			fmt.Sprintf("Expected *scw.Client, got: %T. Please report this issue to the provider developers.", req.ProviderData),
		)

		return
	}

	a.instanceAPI = instance.NewAPI(client)
}

func (a *ServerAction) Metadata(ctx context.Context, req action.MetadataRequest, resp *action.MetadataResponse) {
	resp.TypeName = req.ProviderTypeName + "_instance_server_reboot"
}

type ServerActionModel struct {
	ServerID types.String `tfsdk:"server_id"`
	Zone     types.String `tfsdk:"zone"`
	Wait     types.Bool   `tfsdk:"wait"`
	Action   types.String `tfsdk:"action"`
}

func NewServerAction() action.Action {
	return &ServerAction{}
}

func (a *ServerAction) Schema(ctx context.Context, req action.SchemaRequest, resp *action.SchemaResponse) {
	resp.Schema = schema.Schema{
		Attributes: map[string]schema.Attribute{
			"action": schema.StringAttribute{
				Required:    true,
				Description: "Type of action to perform",
				Validators: []validator.String{
					stringvalidator.ExactlyOneOf(instance.ServerAction.Values()),
				},
			},
			"server_id": schema.StringAttribute{
				Required:    true,
				Description: "Server id to reboot",
			},
			"zone": schema.StringAttribute{
				Optional:    true,
				Description: "Zone of server to reboot",
			},
			"wait": schema.BoolAttribute{
				Optional:    true,
				Description: "Wait for server to finish reboot",
			},
		},
	}
}

func (a *ServerAction) Invoke(ctx context.Context, req action.InvokeRequest, resp *action.InvokeResponse) {
	var data ServerActionModel
	// Read action config data into the model
	resp.Diagnostics.Append(req.Config.Get(ctx, &data)...)
	if resp.Diagnostics.HasError() {
		return
	}

	_, err := a.instanceAPI.ServerAction(&instance.ServerActionRequest{
		ServerID: data.ServerID.String(),
		Zone:     scw.Zone(data.Zone.String()),
		Action:   instance.ServerAction(data.Action.String()),
	})
	if err != nil {
		resp.Diagnostics.AddError(
			"error in server action",
			fmt.Sprintf("%s", err))
	}
	if data.Wait.ValueBool() {
		_, errWait := a.instanceAPI.WaitForServer(&instance.WaitForServerRequest{
			ServerID: data.ServerID.String(),
			Zone:     scw.Zone(data.Zone.String()),
		})
		if errWait != nil {
			resp.Diagnostics.AddError(
				"error in wait server",
				fmt.Sprintf("%s", err))
		}
	}
}

Terraform Configuration Files

Expected Behavior

I should have the action triggered or have a way to trigger it from the tests.

Actual Behavior

The test ignores my action and I don't know how to write a test that will test that an action is triggered.

Steps to Reproduce

Create a terraform action in a provider
Try to test it.

References

I have not found any examples of tests with terraform actions in the official documentation

[bbasata]

👋 @remyleone – we can continue our email conversation here. Any success or new information?

[remyleone]

I've tried to add lifecycle here: scaleway/terraform-provider-scaleway#3390 but I don't see the requests showing up in my acceptance tests.

[bbasata]

I've tried to add lifecycle here: scaleway/terraform-provider-scaleway#3390 but I don't see the requests showing up in my acceptance tests.

Got it. I see that action is a required string attribute in the action schema. I've added an in-line comment in the pull request with a suggestion.

If you run go test with the environment variable TF_LOG=debug, that should display any terraform CLI output, which can be useful in debugging.

[remyleone]

if the action was a required string why didn't I got an error when terraform tried to launch the test? I'm not sure to understand how and when the required part is handled.

[remyleone]

I think I start to understand it is because of the ProviderFactories used in the test. That being said, I'm not sure to understand why this code didn't failed if my action resource was missing 🤔

[bbasata]

if the action was a required string why didn't I got an error when terraform tried to launch the test?

True, that is interesting. I think you are correct that the required string is not the fundamental issue here. Something else may be stopping the test before terraform plan. Extended logging with TF_LOG=debug will be useful for debugging this.

I have an unpublished example provider that confirms the behavior when a required argument is missing.

▶︎ 🔎 internal/cloudlite/machines/restart_test.go

package machines_test

import (
	"testing"

	"github.com/bbasata/terraform-provider-cloudlite/internal/provider"
	"github.com/hashicorp/terraform-plugin-framework/providerserver"
	"github.com/hashicorp/terraform-plugin-go/tfprotov6"
	r "github.com/hashicorp/terraform-plugin-testing/helper/resource"
	"github.com/hashicorp/terraform-plugin-testing/tfversion"
)

func TestRestart(t *testing.T) {
	r.Test(t, r.TestCase{
		TerraformVersionChecks: []tfversion.TerraformVersionCheck{
			tfversion.RequireAbove(tfversion.Version1_14_0),
		},
		ProtoV6ProviderFactories: map[string]func() (tfprotov6.ProviderServer, error){
			"cloudlite": func() (tfprotov6.ProviderServer, error) {
				provider := provider.New("0.0.0-dev")()
				return providerserver.NewProtocol6WithError(provider)()
			},
		},
		Steps: []r.TestStep{
			{
				Config: `
					resource "terraform_data" "x" {
						lifecycle {
							action_trigger {
								events = [after_create]
								actions = [action.cloudlite_machine_restart.power_cycle]
							}
						}
					}

					action "cloudlite_machine_restart" "power_cycle" {
					}
				`,
			},
		},
	})
}

▶︎  TF_ACC=1 go test ./internal/cloudlite/machines -test.v -test.run=Restart

=== RUN   TestRestart
    restart_test.go:14: Step 1/1 error: Error running pre-apply plan: exit status 1

        Error: Missing required argument

        The argument "delay" is required, but was not set.

        Error: Missing required argument

        The argument "machine_id" is required, but was not set.

        Error: Missing required argument

        The argument "region" is required, but was not set.
--- FAIL: TestRestart (0.12s)
FAIL
FAIL    github.com/bbasata/terraform-provider-cloudlite/internal/cloudlite/machines     0.454s
FAIL

[marshallford]

1.14 was just released, any updates on this? Is it possible to write action tests? @austinvalle

[austinvalle]

Hey there @marshallford 👋🏻,

Action testing can be done using the existing Config mode today, since it can be executed through the typical plan/apply workflow: https://developer.hashicorp.com/terraform/language/invoke-actions#trigger-an-action-when-applying-a-configuration. For the local_command action we recently published, it just uses a terraform_data resource with a lifecycle trigger:

• https://github.com/hashicorp/terraform-provider-local/blob/main/internal/provider/action_local_command_test.go
• https://github.com/hashicorp/terraform-provider-local/blob/main/internal/provider/testdata/TestLocalCommandAction_bash/main.tf

You can run test assertions on the remote system in the (TestStep).Check method at the moment, although since that was originally meant for state checking, we are planning on releasing just a generic PostApplyFunc hook. Either will work fine.

In terms of assertions outside of the remote system, there actually isn't anything that actions can do today to store data in plan/state artifacts (we don't return any data to Terraform after invoking/planning), so there's not much else the testing framework can do to help in that area.

---

There are some future ideas (as well as we're open to feedback/suggestions):

• Asserting action progress messages sent back to Terraform: Add ActionChecks #570
  • From our friends on the AWS provider team, that PR is introducing an interceptor to plugin-testing to catch and assert on the RPC messages we send back to Terraform.
• Invoking an action directly with flag: Add --invoke flag to CLI options for config mode testing of actions #580
  • I just wrote this one down, but generally, we should be able to invoke an action directly with a flag, we just need the resource address to do so. That would cut down on the extra managed resource config needed to trigger the action.

[marshallford]

Thanks for the info. To read that back:

Testing the local_command action with (TestStep).Check works because the action writes to the local filesystem. For remote systems I'd likely want use the API SDK used by the provider itself to validate that the action was successful?

For my Ansible provider that isn't really an option, so I suspect most my testing will rely on the TestCheckProgressMessageContains check that is added by #570.

[austinvalle]

Yeah, essentially you need to test the outcome of invoking said action, which Terraform does not observe/record in any way (unlike data sources, for example, which return data that Terraform stores in plan/state artifacts). So the only real option is reaching out to an API that does have that information.

For my Ansible provider that isn't really an option, so I suspect most my testing will rely on the TestCheckProgressMessageContains check that is added by #570.

Yeah for systems that don't have a remote backend (like local), you're kind of restricted to testing that the data came through properly and went to whatever subsystem that actually interacts with the remote data. So we just verify that using bash as the "subsystem" and the script persists to a local temp directory to satisfy our goal of testing "we passed data to a local executable".

I'm not sure how feasible it is to implement a similar approach with anisble navigator (ironic now that I work at IBM, I know nothing about ansible 😏 ) to produce some artifact you can read that allows you to assert your action worked as expected 🤔