--- page_title: terraform test command reference description: >- The `terraform test` command loads and executes Terraform testing files. --- # `terraform test` command The `terraform test` command loads and exectures Terraform testing files. ## Introduction The `terraform test` command and the test file syntax help module authors validate and test their shared modules. You can also use the `terraform test` command to validate root modules. ## Usage Usage: `terraform test [options]` This command searches the current directory and the specified testing directory for Terraform testing files and executes the specified tests. By default, the directory containing test files is named `tests`. Refer to [Tests](/terraform/language/tests) for more details on test files. Terraform then executes a series of Terraform plan or apply commands according to the test files' specifications, and also validates the relevant plan and state files according to the test files' specifications. !> **Warning:** The Terraform test command can create real infrastructure than can cost you money. Refer to the [Terraform Test Cleanup](#terraform-test-cleanup) section for best practices on ensuring created infrastructure is destroyed. ## General Options The following options apply to the Terraform `terraform test` command: * `-cloud-run=` - This test run executes remotely on HCP Terraform within the specified Terraform [private registry](/terraform/language/modules/sources#terraform-registry) module. * `-filter=testfile` - Limits the `terraform test` operation to the specified test files. * `-json` - Displays machine-readable JSON output for your testing results. * `-junit-xml=` - Saves a test report in JUnit XML format to the specified file. This is currently incompatible with remote test execution using the the `-cloud-run` option. The file path must be relative or absolute. * `-test-directory=` - Overrides the directory that Terraform looks into for test files. Note that Terraform always loads testing files within the main configuration directory. The default testing directory is `tests`. * `-verbose` - Prints out the plan or state for each `run` block within a test file, based on the `command` attribute of each `run` block. * `-parallelism=` - Specifies the number of plan/apply operations to execute in parallel within a single test run. The default is 10. ## State Management Each Terraform test file will maintain all Terraform state it requires within memory as it executes, starting empty. This state is entirely separate from any existing state for the configuration under test, so you can safely execute Terraform test commands without affecting any live infrastructure. ### Terraform Test Cleanup The Terraform `terraform test` command creates _real_ infrastructure. Once Terraform fully executes each test file, Terraform attempts to destroy any remaining infrastructure. If it cannot do this, Terraform reports a list of resources it created but could not destroy. You should monitor the output of the test command closely to ensure Terraform removes the infrastructure it created or perform manual cleanup if not. We recommend creating dedicated testing accounts within the target providers that you can routinely and safely purge to ensure any accidental and costly resources aren't left behind. Terraform also provides diagnostics explaining why it could not automatically clean up. You should review these diagnostics to ensure that future clean-up operations are successful. ## HCP Terraform execution You can execute tests remotely on HCP Terraform using the `-cloud-run` option. The `-cloud-run` option accepts a [private registry module source](/terraform/language/modules/sources#terraform-registry). This option associates the test run with your specified private module within the HCP Terraform user interface. You must provide a module from a _private_ registry, not the public Terraform registry. You must execute [`terraform login`](/terraform/cli/commands/login) before using this option, and ensure that your `hostname` argument matches the private registry hostname of your target module. ## Example: Test Directory Structure and Commands The following directory structure represents an example directory tree for a Terraform module with tests and a setup module. ``` project/ |-- main.tf |-- outputs.tf |-- terraform.tf |-- variables.tf |-- tests/ | |-- validations.tftest.hcl | |-- outputs.tftest.hcl |-- testing/ |-- setup/ |-- main.tf |-- outputs.tf |-- terraform.tf |-- variables.tf ``` At the root directory of the project, there are some typical Terraform configuration files: `main.tf`, `outputs.tf`, `terraform.tf`, and `variables.tf`. The test files, `validations.tftest.hcl` and `outputs.tftest.hcl`, are within the default tests directory: `tests`. In addition, a [setup module](/terraform/language/tests#modules) for the tests exists within the `testing` directory. In order to execute the tests you should run `terraform test` from the root configuration directory as if running `terraform plan` or `terraform apply`. Despite the actual test files being in the nested `tests` directory, Terraform executes from the main configuration directory. Specific test files can be executed using the `-filter` option. Linux, Mac OS, and UNIX: ```shell terraform test -filter=tests/validations.tftest.hcl ``` PowerShell: ```shell terraform test -filter='tests\validations.tftest.hcl' ``` Windows `cmd.exe`: ```shell terraform test -filter=tests\validations.tftest.hcl ``` ### Alternate Test Directories In the above example the tests are in the default testing directory of `tests`. Test files can also be included directly within the main configuration directory: ``` project/ |-- main.tf |-- outputs.tf |-- terraform.tf |-- variables.tf |-- validations.tftest.hcl |-- outputs.tftest.hcl |-- testing/ |-- setup/ |-- main.tf |-- outputs.tf |-- terraform.tf |-- variables.tf ``` The location of the testing files does not affect the operation of `terraform test`. All references to, and absolute file paths within, the testing files should be relative to the main configuration directory. You can also use the `-test-directory` argument to change the location of the testing files. For example, `terraform test -test-directory=testing` would instruct Terraform to load tests from the directory `testing` instead of `tests`. The testing directory must be beneath the main configuration directory, but it can be nested many times. > Note: Test files within the root configuration directory are always loaded, regardless of the `-test-directory` value. We do not recommend changing the default test directory. The option for customization is included for configuration authors who may have included a `tests` submodule in their configuration before the `terraform test` command was released. In general, the default test directory of `tests` should always be used. ## Example: Test Output Format Options Below is a contrived example of Terraform testing that makes assertions about the values of local variables `true` and `false`. There are two test files: one contains a passing test, and one contains a failing test. ```hcl # main.tf locals { true = "true" false = "true" # incorrect, should be "false"! } ``` The assertion that `local.true == "true"` in `example_1.tftest.hcl` will pass: ```hcl # example_1.tftest.hcl run "true_is_true" { assert { condition = local.true == "true" error_message = "local.true did not match expected value" } } ``` The assertion that `local.false == "false"` in `example_2.tftest.hcl` will fail: ```hcl # example_2.tftest.hcl run "false_is_false" { assert { condition = local.false == "false" error_message = "local.false did not match expected value" } } ``` ### Test output in JUnit XML format, saved to file Below is the output of the `terraform test -junit-xml=./output.xml` command using the example files above. The test output is: * Printed to the terminal in the default, human-readable format. * Also saved in JUnit XML format in the file specified by the flag. Below is the contents of the resulting `output.xml` file: ```xml ``` If a run block contains a failing assertion, the `` element will contain a `` element that includes the error message and further details. A `` element could contain a `` element that includes details about why a test was skipped. This could either be due to an error causing remaining run blocks to be skipped, or due to the command being interrupted. #### Mapping Terraform test command concepts to JUnit XML format The test report generated when using `-junit-xml` maps Terraform test command concepts to JUnit XML format according to the table below: | Terraform test concept | Element in JUnit XML output | | ----------------------------------| --------------------------------------------| | Test directory | `` | | Test file | `` | | Run block | `` | | Run block assertion | None; details are included only on failure | | Test failure | `` | | Test was skipped | `` | | Test stopped due to error | `` | | Any unhandled warnings or errors | `` |