tfpolicy test

The tfpolicy test command runs policy tests to verify that your policies work as expected.

Usage

$ tfpolicy test [options]

Description

Once you have written your policy tests, run them using the tfpolicy test command. You can provide the path to both the policy files and the test files. If you only specify the path to your policy files, the tests in that path will be executed.

Available options

Examples

Basic usage

Test policies in the current directory:

$ tfpolicy test

Specify policy and test paths

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

Test specific evaluation stage

Not all policies run at every stage of a Terraform run. Use the --evaluation-stage argument to have Terraform policy run the tests either pre-plan (setup) time, or after the plan has been created.

$ tfpolicy test --policies=./policies --tests=./tests --evaluation-stage=setup

Set input values

Set input values using environment variables:

$ export TF_VAR_instance_type=t3.medium
$ tfpolicy test --policies=./policies --tests=./tests

Or using the --input flag:

$ tfpolicy test --policies=./policies --input="instance_type=t3.medium"

Or using an input file:

$ tfpolicy test --policies=./policies --input-file=test-inputs.tfvars

Setting input values

When Terraform policy runs your tests, it will set values for inputs in your policies through the following methods, in order of precedence:

1. In an input {} block inside a provider, resource, or module block.
2. In an input {} block at the top level of each test file.
3. On the command line with --input option.
4. From a TFPOLICY_INPUT_name environment variable matching the name of the input.
5. From a variable definition file, with the --input-file option.
6. From an environment variable with a name exactly matching the name of the input.
7. The default value of the input configured in the policy file.

If Terraform policy cannot assign a value to an input through one of the above methods, it will error.

Test output

When you run tests, tfpolicy provides detailed output showing the status of each test case:

$ tfpolicy test --policies=.
# encrypted_ebs.policytest.hcl... running
# resource.aws_ebs_volume.ebs_vol... running
# resource.aws_ebs_volume.ebs_vol... fail
Error: Policy violation
  Expected: pass
  Actual: fail
  Message: EBS volumes must be encrypted
# resource.aws_ebs_volume.ebs_vol2... running
# resource.aws_ebs_volume.ebs_vol2... pass
# encrypted_ebs.policytest.hcl... pass

Successful test output

$ tfpolicy test --policies=./policies --tests=./tests
# tests/example-policy.policytest.hcl... running
  # provider.aws.approved_config... running
  # provider.aws.approved_config... pass
  # provider.aws.wrong_version... running
  # provider.aws.wrong_version... pass
  # resource.aws_instance.correct_type... running
  # resource.aws_instance.correct_type... pass
# tests/example-policy.policytest.hcl... pass

Debugging failed tests

When a test fails, tfpolicy will provide detailed error messages indicating:

• Which policy failed
• Which test case failed
• The specific condition that was not met
• The error message defined in the policy

# resource.aws_instance.test_case... fail
Error: Policy violation
  Expected: pass
  Actual: fail
  Message: Instance type must be t3.micro

Use this information to debug failed tests by:

1. Reviewing the policy condition that failed
2. Checking the test case attributes match your expectations
3. Verifying the policy logic is correct
4. Ensuring input values are set correctly

Related documentation

• Write and run policy tests - Learn how to write and run tests
• Test configuration reference - Reference for test file syntax