🧹 Enhance Terraform Sweeper documentation

[oscarhermoso]

Does this documentation exist?

• This is new documentation #386
• This is an enhancement to existing documentation

Where would you expect to find this documentation?

• On terraform.io
• In the GoDoc for this module
• In this repo as a markdown file
  • https://developer.hashicorp.com/terraform/plugin/testing/acceptance-tests/sweepers
  • https://github.com/hashicorp/terraform-plugin-testing/blob/main/website/docs/plugin/testing/acceptance-tests/sweepers.mdx
• Somewhere else - in the Hashicups example
  • https://github.com/hashicorp/terraform-provider-hashicups/blob/main/10-acceptance-tests/GNUmakefile
  • https://github.com/search?q=repo%3Ahashicorp%2Fterraform-provider-hashicups%20sweep&type=code

Description

I would like to follow an idiomatic example of Sweepers, so I can implement them for a provider that is based on the terraform-plugin-framework package.

I'm fairly new to Go and creating Terraform providers; I have tried to follow the Terraform docs, but my sweepers do not run. (No need for you to debug my code, just trying to give some context.)

• The documentation refers to a Makefile, but there is no explanation for what should be in that Makefile
  • Ideally document how to sweep without a Makefile also
• Sweeper seems to rely on some environment variables, (I'm assuming SWEEP / SWEEP_ARGS / SWEEP_DIR based on unofficial GitHub code?) but these are not documented
• Not clear what the intended use is of the region argument for SweeperFunc
• The documentation refers to TestMain - I'm not sure if the name is important, or it could be replaced with TestWhatever
• Ideally, also include Sweepers in the Hashicups example, because there is very little code for Terraform Framework that can be used as a reference for Sweepers:
  • Compare 20k+ result count for mostly SDK v2: https://github.com/search?q=resource.AddTestSweepers&type=code
  • and ~600 results for TF Framework - https://github.com/search?q=resource.AddTestSweepers+NOT+sdk&type=code

References

N/A

[oscarhermoso]

Update - I got my Sweeper working - but have some more feedback:

• Crucial to document command: go test -v ./... -sweep=all
• The documentation recommends using log.Printf in some of the error handling, but these would only be visible if go test was ran with the -v flag
• Would be good to document the CLI flags below - these can be revealed with go test -v ./... -sweep-args=asdasd

  -sweep string
        List of Regions to run available Sweepers
  -sweep-allow-failures
        Enable to allow Sweeper Tests to continue after failures
  -sweep-run string
        Comma separated list of Sweeper Tests to run

And if someone else finds has the same issue - see below my working code below...

Working code

Create a sweeper_test.tf

// sweeper_test.tf
package provider

import (
	"testing"
	
	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
	
	// if your resources are in different packages, import here
	// _ "terraform-provider-example/internal/example"

)

func TestMain(m *testing.M) {
	resource.TestMain(m)
}

Extend your existing test files with an init() method:

// resource_example_test.tf
package provider

import (
	"testing"

	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
)

func TestExampleResource(t *testing.T) {
  // ...
}

// init is special, no issues with multiple init functions with same name
func init() {
  resource.AddTestSweepers("example", &resource.Sweeper{
    Name: "example",
    F: func(_ string) error {
      // ...
    }
}

Run sweeper with:

go test -v  ./... -sweep=all