Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hashicorp/terraform/llms.txt

Use this file to discover all available pages before exploring further.

​
Command: test

The terraform test command executes automated integration tests against the current Terraform configuration.

​
Usage

terraform test [options]
Terraform will search for .tftest.hcl files within the current configuration and testing directories. Terraform will then execute the testing run blocks within any testing files in order, and verify conditional checks and assertions against the created infrastructure.
This command creates real infrastructure and will attempt to clean up the testing infrastructure on completion. Monitor the output carefully to ensure this cleanup process is successful.

​
Options

  • -cloud-run=source - If specified, Terraform will execute this test run remotely using HCP Terraform or Terraform Enterprise. You must specify the source of a module registered in a private module registry as the argument to this flag. This allows Terraform to associate the cloud run with the correct HCP Terraform or Terraform Enterprise module and organization.
  • -filter=testfile - If specified, Terraform will only execute the test files specified by this flag. You can use this option multiple times to execute more than one test file.
  • -json - If specified, machine readable output will be printed in JSON format.
  • -junit-xml=path - Saves a test report in JUnit XML format to the specified file. This is currently incompatible with remote test execution using the -cloud-run option. The file path must be relative or absolute.
  • -no-color - If specified, output won’t contain any color.
  • -parallelism=n - Limit the number of concurrent operations within the plan/apply operation of a test run. Defaults to 10.
  • -test-directory=path - Set the Terraform test directory. Defaults to "tests".
  • -var 'NAME=VALUE' - Set a value for one of the input variables in the root module of the configuration. Use this option multiple times to set more than one variable.
  • -var-file=FILENAME - Load variable values from the given file, in addition to the default files terraform.tfvars and *.auto.tfvars. Use this option multiple times to include more than one variables file.
  • -verbose - Print the plan or state for each test run block as it executes.

​
Test File Structure

Test files use the .tftest.hcl extension and contain one or more run blocks. Each run block represents a test case. Example test file: 
run "test_instance" {
  command = plan

  assert {
    condition     = aws_instance.example.instance_type == "t2.micro"
    error_message = "Instance type must be t2.micro"
  }
}

run "test_apply" {
  command = apply

  assert {
    condition     = aws_instance.example.ami != ""
    error_message = "AMI must be set"
  }
}

​
Test Directory

By default, Terraform looks for test files in a tests/ directory relative to your configuration. You can customize this location using the -test-directory flag.

​
Examples

Run all tests: 
terraform test
Run specific test files: 
terraform test -filter=example.tftest.hcl
Run tests with verbose output: 
terraform test -verbose
Run tests and generate JUnit XML report: 
terraform test -junit-xml=test-results.xml

Build docs developers (and LLMs) love

Get started for freeTalk to us