🧹 Enhance Terraform Sweeper documentation

[oscarhermoso]

Does this documentation exist?

• [x] This is new documentation
• [x] This is an enhancement to existing documentation

Where would you expect to find this documentation?

• [ ] On terraform.io
• [ ] In the GoDoc for this module
• [x] In this repo as a markdown file
  • [x] https://developer.hashicorp.com/terraform/plugin/testing/acceptance-tests/sweepers
  • [x] https://github.com/hashicorp/terraform-plugin-testing/blob/main/website/docs/plugin/testing/acceptance-tests/sweepers.mdx
• [x] Somewhere else - in the Hashicups example
  • [x] https://github.com/hashicorp/terraform-provider-hashicups/blob/main/10-acceptance-tests/GNUmakefile
  • [x] 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` ```go // 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: ```go // 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: ```sh go test -v ./... -sweep=all ```