| page_title | description |
|---|---|
Plugin Development - Testing |
Learn how to write successful acceptance and unit tests for 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.
-> Note: Recent versions of Terraform CLI also support developer overrides in the CLI configuration, which can be useful for manually testing providers. The acceptance testing framework uses real Terraform CLI executions, so we only recommend developer overrides as a last resort option for missing functionality.
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 testaccSee Acceptance Testing to learn more.
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 testSee Unit Testing to learn more.