Test Sweepers Reference
Sweepers clean up infrastructure resources that leak during acceptance tests — when test infrastructure fails to be destroyed due to API errors or test failures.
Source: Sweepers
Setup
TestMain (required)
Add to a dedicated file (e.g., sweep_test.go):
func TestMain(m *testing.M) {
resource.TestMain(m)
}This parses the -sweep flag and invokes registered sweepers.
Register a Sweeper
Register in the test file for the resource being swept, using init():
func init() {
resource.AddTestSweepers("example_widget", &resource.Sweeper{
Name: "example_widget",
F: sweepWidgets,
})
}
func sweepWidgets(region string) error {
client, err := sharedClientForRegion(region)
if err != nil {
return fmt.Errorf("getting client: %w", err)
}
conn := client.(*Client)
widgets, err := conn.ListWidgets()
if err != nil {
return fmt.Errorf("listing widgets: %w", err)
}
for _, w := range widgets {
if !strings.HasPrefix(w.Name, "test-acc") {
continue
}
if err := conn.DeleteWidget(w.ID); err != nil {
log.Printf("[WARN] Failed to delete widget %s: %s", w.ID, err)
}
}
return nil
}Use a consistent test name prefix (e.g., "test-acc") to identify
test-created resources.
Dependencies
When resources have ordering requirements (e.g., child resources must be deleted before parents), the parent sweeper declares children as dependencies so they run first:
resource.AddTestSweepers("example_widget", &resource.Sweeper{
Name: "example_widget",
Dependencies: []string{"example_widget_child"},
F: sweepWidgets,
})Dependencies run before the sweeper that declares them. In this example,
example_widget_child is swept first, then example_widget.
Shared Client
Create a helper to build an API client for the sweep region:
func sharedClientForRegion(region string) (any, error) {
// Build and return a configured API client
return NewClient(region)
}Running Sweepers
# Run all sweepers for a region
TF_ACC=1 go test ./internal/service/example -sweep=us-east-1 -v
# Makefile target (common convention)
make sweep