Acceptance Tests

Acceptance tests for Terraform providers are a feature of the terraform-plugin-testing framework. The testing framework uses standard Go features such as the go test command. It runs a local Terraform binary to perform real plan, apply, refresh, and destroy operations, and enables developers to make assertions about what happens during those actions.

When testing the happy path, developers can make assertions about the data stored in state after successfully provisioning a resource. When testing unhappy paths, developers are able to make assertions about errors returned by Terraform, non-empty plans, and the actual cloud resources created by Terraform.

Test files

Terraform follows many of the Go programming language conventions with regards to testing. Tests are placed in a file that matches the file under test, with an added _test.go suffix. Here's an example file structure:

terraform-plugin-example/
├── provider.go
├── provider_test.go
├── example/
│   ├── resource_example_compute.go
│   ├── resource_example_compute_test.go

To create an acceptance test in the example resource_example_compute_test.go file, add a test function with name that begins with TestAcc.

import "testing"
 
func TestAccExampleComputeResource(*testing.T) {
}

Requirements and recommendations

Acceptance tests have the following requirements:

• Go: The most recent stable version.
• Terraform CLI: Version 0.12.26 or later.
• Provider Access: Network or system access to the provider and any resources being tested.
• Provider Credentials: Authorized credentials to the provider and any resources being tested.
• TF_ACC environment variable: Set to any value. Prevents developers from incurring unintended charges when running other Go tests.

We also recommend the following when running acceptance tests:

• A separate Account: Use a separate provider account or namespace for acceptance testing. This prevents Terraform from unexpectedly modifying or destroying infrastructure due to code or testing issues.
• Previous Terraform CLI Installation: Install Terraform CLI either into the operating system PATH or use the TF_ACC_TERRAFORM_PATH environment variable prior to running acceptance tests. Otherwise, the testing framework will download and install the latest Terraform CLI version into a temporary directory for every test invocation. Refer to the Terraform CLI Installation Behaviors section for details.

Each provider may have additional requirements and setup recommendations. Refer to the provider's codebase for more details.

Running Acceptance Tests

Use the go test command to run acceptance tests. You can run the acceptance tests on any environment capable of running go test, such as a local workstation command line or a continuous integration runner, such as GitHub Actions.

Command Line Workflow

This example will execute all available acceptance tests in a provider codebase:

TF_ACC=1 go test -v ./...

Makefiles

test to make sure the gnu domain is skipped

For convenience, provider codebases can place common tasks in a Makefile.

This example defines a testacc target, which sets TF_ACC and the verbose (-v) flag.

testacc:
    TF_ACC=1 go test -v ./...

To run acceptance tests:

make testacc

Terraform CLI Installation Behaviors

The testing framework implements the following Terraform CLI discovery and installation behaviors:

• If the TF_ACC_TERRAFORM_PATH environment variable is set, the framework will use that Terraform CLI binary if it exists and is executable. If the framework cannot find the binary or it is not executable, the framework returns an error unless the TF_ACC_TERRAFORM_VERSION environment variable is also set.
• If the TF_ACC_TERRAFORM_VERSION environment variable is set, the framework will install and use that Terraform CLI version.
• If both the TF_ACC_TERRAFORM_PATH and TF_ACC_TERRAFORM_VERSION environment variables are unset, the framework will search for the Terraform CLI binary based on the operating system PATH. If the framework cannot find the specified binary, it installs the latest available Terraform CLI binary.

Troubleshooting

This section lists common errors encountered during testing.

Unrecognized remote plugin message

terraform failed: exit status 1
 
    stderr:
 
    Error: Failed to instantiate provider "random" to obtain schema:
Unrecognized remote plugin message: --- FAIL: TestAccResourceID (4.28s)
 
    This usually means that the plugin is either invalid or simply needs to
be recompiled to support the latest protocol.

This error indicates that the provider server could not connect to Terraform Core. Verify that the output of terraform version is v0.12.26 or above.

Next Steps

The next step is to create Test Cases using Terraform's testing framework.build and verify real infrastructure.

Proceed to Test Cases.