Policy test configuration reference
Like policy files, Terraform policy's test syntax is based on HCL, and supports a number of block types that you can use when you write tests for your policies.
Test file structure
Each policy test file can include:
- An optional
policytest {}block to configure which policies Terraform policy will test. - One or more mock blocks to define test cases by mocking the Terraform construct to test the policy against:
provider {}blocks to mock providers.resource {}blocks to mock resources.data {}blocks to mock data sources.module {}blocks to mock modules.
- Any number of
input {}blocks to set values for policy inputs. - Any number of
locals {}blocks to define local values.
Test block attributes
Terraform policy supports the following optional attributes within provider, resource, data source, and module blocks in test files:
| Name | Description | Type | Example |
|---|---|---|---|
attrs | Sets the attributes for the provider, resource, data source, or module. | Object | {bucket = "my-bucket", acl = "private"} |
expect_failure | Expect the mock to fail the matching policies. Use to test that your policy fails in expected cases. | Boolean | true, false |
meta | Provides data to configure meta-arguments for the mock. | Object | {address = "aws_s3_bucket.example"} |
skip | Skip evaluating the mock against policies. Use for mocks that only establish relationships. | Boolean | true, false |
Terraform policy supports the following additional attributes within resource blocks in test files:
| Name | Description | Type | Example |
|---|---|---|---|
operation | Set the operation to test. | String | "create", "update", "delete" |
prior_attrs | The value of the prior attributes for update or delete operations. | Object | {bucket = "old-bucket"} |
Testing operation-based policies
When a resource policy uses the operation meta-argument to scope itself to a specific Terraform operation, your test cases must indicate which action each mock resource represents.
The testing framework provides two optional attributes within mock resource blocks for this purpose: operation and prior_attrs.
The operation attribute
The operation attribute declares which planned action a mock resource represents with values: "create", "update" or "delete". If you do not specify a value for the operation attribute, Terraform policy will default to "create", unless you set the prior_attrs attribute, in which case it will default to "update".
Depending on the operation being tested, set the value of the attrs and prior_attrs attributes to mock operations as described in the following table.
| Operation | attrs.<name> | prior_attrs.<name> |
|---|---|---|
| create | Target State | (unavailable/null) |
| update | Target State | Current State |
| delete | Target State (all resource attributes are null) | Current State |
The prior_attrs attribute
The prior_attrs attribute populates the mock data for the prior_attrs variables used by the policy evaluation context.
Test resource and data source relationships
Policies often need to validate relationships between different resources and data sources. For example, ensuring that an AWS CloudTrail resource is correctly linked to an encrypted S3 bucket. You can model these dependencies by allowing mock resources and data sources to reference one another, just as they would in a real Terraform configuration.
When testing policies that use the core::getresources() function, Terraform policy builds a graph of the mock resources defined in your test file. You can create a relationship between two mock resources by referencing an attribute of one resource within the attrs block of another.
You may mock resources or data sources to establish resource relationships that your policies will test, without needing to test the policies against those particular resources directly. Set the skip attribute to true on resource blocks you do not want Terraform policy to evaluate against your policies. Terraform policy does not enforce policies against data sources, so you do not need to set the skip attribute on data source blocks.
Reference pages
- The
policytest {}block - Configure test targets - Mock provider blocks - Define mock providers
- Mock resource blocks - Define mock resources
- Mock data source blocks - Define mock data sources
- Mock module blocks - Define mock modules
- The
input {}block - Set input values for tests - The
locals {}block - Define local values for tests