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.

Note

This functionality is in beta. Do not use beta features in production environments.

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.
An optional inputs block to set policy input values for all test cases.
An optional locals block to define local values.

Test block attributes

The following table lists the optional arguments that configuration blocks in test files support.

Name	Description	`provider`	`resource`	`data`	`module`
`attrs`	Sets the attributes for the provider, resource, data source, or module.	Yes	Yes	Yes	Yes
`expect_failure`	Expect the mock to fail the matching policies. Use to test that your policy fails in expected cases.	Yes	Yes	No	Yes
`inputs`	Set input values	Yes	Yes	No	Yes
`meta`	Provides data to configure meta-arguments for the mock.	Yes	Yes	No	Yes
`prior_attrs`	The value of the prior attributes for `update` or `delete` operations.	No	Yes	No	No
`skip`	Skip evaluating the mock against policies. Use for mocks that only establish relationships.	No	Yes	No	No

Note

Terraform policy will error if it encounters invalid policies or tests, such as policies that request resources or data sources that have no data configured, or those that cannot be parsed due to invalid syntax. Terraform policy will raise these errors even if the expect_failure or skip attributes are set to true.

Testing operation-based policies

When a resource policy uses the operations argument to select Terraform lifecycle operations, your test cases must indicate which action each mock resource represents.

The testing framework provides optional attributes within mock resource blocks for this purpose. The meta.operation declares which planned action a mock resource represents. The prior_attrs operation populates the mock data for the prior_attrs variables used by the policy evaluation context.

`meta.operation` attribute

The meta.operation attribute declares which planned action a mock resource represents. Valid values are "create", "update", and "delete". When you omit meta.operation, Terraform policy infers the operation from the presence and values of attrs and prior_attrs.

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.