AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

provider-test-patterns

Terraform provider acceptance test patterns using terraform-plugin-testing with the Plugin Framework. Covers test structure, TestCase/TestStep fields, ConfigStateChecks with custom statecheck.StateCheck implementations, plan checks, CompareValue for cross-step assertions, config helpers, import testing with ImportStateKind, sweepers, and scenario patterns (basic, update, disappears, validation, regression), and ephemeral resource testing with the echoprovider package. Use when writing, reviewing, or debugging provider acceptance tests, including questions about statecheck, plancheck, TestCheckFunc, CheckDestroy, ExpectError, import state verification, ephemeral resources, or how to structure test files.

Original source
hashicorp
License
MPL-2.0
Pinned revision
bc6b14b77481c3cbfbb06a0166be7245ed45798c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read hashicorp--provider-test-patterns at revision bc6b14b77481c3cbfbb06a0166be7245ed45798c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/sweepers.md

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