Testing Terraform Plugins

Here we cover information needed to write successful tests for Terraform Plugins. Tests are a vital part of the Terraform ecosystem, verifying we can deliver on our mission to safely and predictably create, change, and improve infrastructure. Documentation for Terraform tests falls into categories briefly described on this page. Each category has more detailed information on a separate page within the documentation.

Acceptance Tests

In order to deliver on our promise to be safe and predictable, we need to be able to easily and routinely verify that Terraform Plugins produce the expected outcome. The most common usage of an acceptance test is in Terraform Providers, where each Resource is tested with configuration files and the resulting infrastructure is verified. Terraform includes a framework for constructing acceptance tests that imitate the execution of one or more steps of applying one or more configuration files, allowing multiple scenarios to be tested.

It’s important to reiterate that acceptance tests in resources create actual cloud infrastructure, with possible expenses incurred, and are the responsibility of the user running the tests. Creating real infrastructure in tests verifies the described behavior of Terraform Plugins in real world use cases against the actual APIs, and verifies both local state and remote values match. Acceptance tests require a network connection and often require credentials to access an account for the given API. When writing and testing plugins, it is highly recommended to use an account dedicated to testing, to ensure no infrastructure is created in error in any environment that cannot be completely and safely destroyed.

HashiCorp runs nightly acceptance tests of providers found in the Terraform Providers GitHub Organization to ensure each Provider is working correctly.

For a given plugin, Acceptance Tests can be run from the root of the project by using a common make task:

$ make testacc

See Acceptance Testing to learn more.

Unit Tests

Testing plugin code in small, isolated units is distinct from Acceptance Tests, and does not require network connections. Unit tests are commonly used for testing helper methods that expand or flatten API response data into data structures for storage into state by Terraform. This section covers the specifics of writing Unit Tests for Terraform Plugin code.

For a given plugin, Unit Tests can be run from the root of the project by using a common make task:

$ make test

See Unit Testing to learn more.

Testing Patterns

Terraform developers are encouraged to write acceptance tests that create real resource to verify the behavior of plugins, ensuring a reliable and safe way to manage infrastructure. In Testing Patterns we cover some basic acceptance tests that almost all resources should have to validate not only the functionality of the resource, but that the resource behaves as Terraform would expect.