Terraform Framework migration testing

  1. We are getting this error in our provider when running a test for the Mux server (using tf5to6server for existing SDKv2 provider) as mentioned here:
    Plugin Development: Migrating testing from SDKv2 to the testing module | Terraform | HashiCorp Developer

  2. For existing SDKv2 resource acceptance tests:
    We updated some existing SDKv2 resource tests to use the upgraded server as mentioned in Plugin Development - Translating Protocol Version 5 to 6 | Terraform | HashiCorp Developer.

Q1: How can we ensure via our acceptance tests that Muxing doesn’t affect any existing resources?
Q2: I understand that there is also a migration to plugin testing module - Does this mean before migrating to the Plugin Framework, we will first need to migrate all existing SDKv2 tests to plugin testing module? Because looks like “github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource” and “github.com/hashicorp/terraform-plugin-testing/helper/resource” can’t co-exist in a provider?

Hi @maastha :wave:

Please refer to Testing Migration: Migrating from SDKv2 to the Framework | Terraform | HashiCorp Developer which is generally applicable to testing a released provider resource with new provider code. The Plugin Development - Combining Protocol Version 6 Providers | Terraform | HashiCorp Developer documentation attempts to show how to “wire” the mux server for testing purposes. (It explicitly mentions terraform-plugin-sdk/v2 there which is errant – discussed further below.)

It’s generally unnecessary to test every resource when introducing muxing though since the general behavior of the mux server is more of a request router, rather than anything interfering with how requests/responses to the underlying provider of a resource type are handled. Instead, most providers typically verify the mux server setup with a single acceptance test against a single data source or resource.

The terraform-plugin-testing and terraform-plugin-sdk Go modules are functionally equivalent for provider acceptance testing today, except that terraform-plugin-testing is the only Go module receiving new features (such as plan checks and Terraform version checks). The terraform-plugin-testing code was essentially “copied” from terraform-plugin-sdk. The terraform-plugin-sdk Go module will have its testing functionality deprecated soon though.

You can treat the migration to terraform-plugin-testing separately of other provider development changes unless you need a provider acceptance testing feature that is only available in terraform-plugin-testing. Many of the code examples in the documentation have been updated to use terraform-plugin-testing to raise awareness of that separate Go module, but terraform-plugin-sdk/v2 is also largely usable/applicable in those cases.

To directly answer your question though, the answer is no. The helper/resource packages in both are incompatible for the Go compiler because they both include a TestMain function with a sweep flag since the underlying code was “copied” between the two Go modules. Unless you are using the helper/resource package ID or retry functionality though, migrating over to terraform-plugin-testing is typically a find-and-replace operation in your provider codebase, if you did want to migrate.

Thanks a lot for the guidance @bflad !

We actually do use ID and retry functionality. resource.UniqueID for example, which I’m aware can be migrated using “/terraform-plugin-sdk/v2/helper/id”

As long as it is just a matter of replacing some existing imports, we should be okay migrating to terraform-plugin-testing.

Since you also mentioned retry functionality, what does the migration for that look like?

Release v2.26.0 · hashicorp/terraform-plugin-sdk · GitHub has:

  • helper/resource: Deprecated RetryContext(), StateChangeConf, and associated *Error types. Use the helper/retry package instead. These deprecations are to assist in migrating to terraform-plugin-testing (#1167)

From the pull request noted there, we can see the retry code was moved by relocating the files. It should be a matter of updating the import from github.com/hashicorp/terraform-plugin-sdk/v2/helper/resource to github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry and updating the package name when using the functions/types, for example, calling retry.RetryContext() instead of resource.RetryContext(). You can verify all this by looking at the associated Go documentation for the new package: retry package - github.com/hashicorp/terraform-plugin-sdk/v2/helper/retry - Go Packages

The terraform-plugin-sdk Go module unfortunately suffered from a sprawling random assortment of functionality in a small number of packages over time, which we’re trying to avoid nowadays. These migration paths have tried to be as low effort as possible, but its understandably frustrating to try to tackle all of this at the same time. :slightly_frowning_face: