Implement automated testing
In this tutorial, you will add automated acceptance testing capabilities to the data source and resource of a provider that interacts with the API of a fictional coffee-shop application called HashiCups. To do this, you will:
- Implement data source id attribute.
This ensures the data source is compatible with the testing framework. - Implement data source acceptance testing.
This automates the end-to-end testing of the data source. - Run data source acceptance testing.
This ensures that the data source testing works as expected. - Implement resource acceptance testing.
This automates the end-to-end testing of the resource. - Run resource acceptance testing.
This ensures that the resource testing works as expected.
The terraform-plugin-testing
Go module helper/resource
package enables providers
to implement automated acceptance testing. The testing framework is built on top
of standard go test
command functionality and calls actual Terraform commands,
such as terraform apply
, terraform import
, and terraform destroy
. Unlike
manual testing, you do not have to locally reinstall the provider on code
updates or switch directories to use the expected Terraform configuration when
you run the automated tests.
Prerequisites
To follow this tutorial, you need:
- Go 1.19+ installed and configured.
- Terraform v1.0.3+ installed locally.
- Docker and Docker Compose to run an instance of HashiCups locally.
Navigate to your terraform-provider-hashicups-pf
directory.
Your code should match the import-order
branch
from the example repository.
If you're stuck at any point during this tutorial, refer to the
acceptance-tests
branch to see the changes implemented in this tutorial.
Implement data source id attribute
The testing framework requires an id
attribute to be present in every data source and resource. In order to run tests on data sources and resources that do not have their own ID, you must implement an ID field with a placeholder value.
Open the internal/provider/coffees_data_source.go
file.
Add the id
attribute to the Schema
method with the following.
Replace the coffeesDataSourceModel
data source model with the following.
Set a placeholder value near the end of the data source's Read
method
immediately before returning the state with the following.
Implement data source acceptance testing
Data source acceptance testing is used to verify the Terraform state contains data after being read from the API.
Most providers will manage some shared implementation details in a single testing file to simplify the data source and resource testing implementations.
Navigate to the internal/provider
directory and remove the example scaffolding test files.
Open the internal/provider/provider_test.go
file and replace the existing code with the following.
Create a new internal/provider/coffees_data_source_test.go
file with the following.
Verify data source testing functionality
Now that you have implemented the testing functionality to the data source, you can run the tests.
Run Go testing with the TF_ACC
environment variable set. The test framework
will report that your data source's test passed.
Implement resource testing functionality
Resource acceptance testing is used to verify the entire resource lifecycle,
such as the Create
, Read
, Update
, and Delete
functionality, along with
import capabilities. The testing framework automatically handles destroying test
resources and returning any errors as a final step, regardless of whether there
is a destroy step explicitly written.
Create a new internal/provider/order_resource_test.go
file with the following.
Verify resource testing functionality
Now that you have implemented the testing functionality for the order resource, run the tests.
Run Go testing with the TF_ACC
environment variable set and only running the
resource tests. The test framework will report that your resource's test passed.
Navigate to the terraform-provider-hashicups-pf
directory.
Next steps
Congratulations! You have enhanced the provider with acceptance testing capabilities.
If you were stuck during this tutorial, checkout the
acceptance-tests
branch to see the changes implemented in this tutorial.
- To learn more about the Terraform Plugin Framework, refer to the Terraform Plugin Framework documentation.
- For a full capability comparison between the SDKv2 and the Plugin Framework, refer to the Which SDK Should I Use? documentation.
- The Terraform HashiCups (plugin-framework)
provider's
main
branch contains the complete HashiCups provider. It includes a data source written with the plugin framework and implements create, read, update and delete functionality for the order resource. - Submit any Terraform Plugin Framework bug reports or feature requests to the development team in the Terraform Plugin Framework Github repository.
- Submit any Terraform Plugin Framework questions in the Terraform Plugin Framework Discuss forum.