How to fix Error: Test run failed in Terraform

First, validate your configuration syntax to ensure there are no basic HCL errors:

terraform validate

If validate fails, fix the syntax errors before running tests. This command checks for basic structural issues in your configuration files.

Re-run the test command with the -verbose flag to see detailed information about what each test run is doing:

terraform test -verbose

This prints the plan or state for each run block, helping you understand exactly which assertions are failing and why.

Examine the assert blocks in your .tftest.hcl file. Each assertion has a condition that must evaluate to true. For example:

assert {
  condition     = aws_s3_bucket.example.bucket != null
  error_message = "S3 bucket should be created."
}

Verify that your conditions match the actual resource outputs and values being created.

If your test intentionally expects failures, ensure the expect_failures attribute is correctly configured:

run "validate_required_field" {
  command = plan
  expect_failures = [
    var.required_variable
  ]
}

Note: Use expect_failures primarily with command = plan operations, not with apply.

Set the TF_LOG environment variable to DEBUG for detailed execution logs:

export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform-debug.log
terraform test

Review the generated log file to understand what's happening during each run block and identify where assertions are failing.

After a test fails, Terraform attempts to destroy created resources. Check the test output to see if cleanup was successful:

terraform test

If resources weren't cleaned up, manually destroy them to avoid accumulating test infrastructure:

terraform destroy

Ensure your test is properly configured to clean up test infrastructure between runs.