policytest

The policytest block defines the policies that Terraform policy will test.

Configuration model

The policytest block supports the following configuration:

• policytest   block
  • plugins   block | optional
    • <plugin_label>   map | repeatable
      • source   string | required
  • targets   list of strings | optional
  • terraform_config   block | optional
    • required_version   string | optional

Complete configuration example

The following example demonstrates a policytest block with all configuration options specified:

policytest {
  terraform_config {
    required_version = ">= 1.16.0"
  }

  targets = [
    "path/to/single_policy.policy.hcl",
    "path/containing/multiple_policies/"
  ]

  plugins {
    example = {
      source = "../plugins/example"
    }
  }
}

Specification

A policytest block supports the following configuration.

plugins

Specifies plugins that provide custom functions to use in your policy tests. Plugins must be compiled binaries. Refer to Policy plugins for more information.

Specify each plugin as a map within the plugins block.

• Data type: Block
• Default: None

A plugins block supports the following configuration.

Plugin map label

The plugin block label gives a name to the plugin. Must be unique within the test file.

Plugin map key source

The source attribute is the path to the plugin binary. The binary must be a valid Terraform policy Go plugin server. Refer to Policy plugins for more information about creating and using policy plugins.

• Data type: String
• Required

In your policies, reference your functions with the syntax plugin::<plugin_label>::<function_name>(<function_arguments>...).

targets

A list of policy files or directories containing policy files for Terraform policy to test against the mock providers, resources, data sources, and modules defined in the test file.

• Data type: List of strings
• Default: None

If you do not specify targets in your policytest {} block, Terraform policy will evaluate the policy files in the path you provide when you run your tests using the --policies flag.

terraform_config

The terraform_config block declares the Terraform version required to run the test.

• Data type: Block
• Default: None

A terraform_config block supports the following configuration.

required_version

A version constraint specifying which versions of Terraform the test is compatible with.

• Data type: String
• Default: None

Examples

The following examples demonstrate common policytest block configuration patterns for specific use cases.

Test specific policy files

In the following example, the policytest block specifies two specific policy files to test against the mock resources defined in the test file.

policytest {
  targets = [
    "../policies/aws_provider.policy.hcl",
    "../policies/encrypted_ebs.policy.hcl"
  ]
}

provider "aws" "example" {
  meta = {
    source  = "hashicorp/aws"
    version = "5.0.0"
  }
  
  attrs = {
    region = "us-east-1"
  }
}

resource "aws_ebs_volume" "encrypted" {
  attrs = {
    availability_zone = "us-east-1a"
    size              = 10
    encrypted         = true
  }
}

Test all policies in a directory

In the following example, the policytest block specifies a directory containing multiple policy files to test.

policytest {
  targets = [
    "../policies"
  ]
}

resource "aws_instance" "example" {
  attrs = {
    instance_type = "t3.micro"
    ami           = "ami-12345678"
  }
}

Omit targets to use command-line path

In the following example, the test file omits the policytest block, allowing the policy path to be specified via the --policies command-line flag.

resource "aws_instance" "example" {
  attrs = {
    instance_type = "t3.micro"
    ami           = "ami-12345678"
  }
}

When running tests without a policytest block, specify the path to the policies for Terraform policy to test.

$ tfpolicy test --policies=../policies --tests=.