tftest: Terraform Python Testing Helper

1.8.7 · active · verified Thu Apr 16

tftest is a Python package that simplifies testing Terraform modules from Python unit tests. It wraps the Terraform executable, providing convenience methods to set up fixtures, execute Terraform commands (like `init`, `plan`, `apply`, `output`, `destroy`), and parse their outputs. The library is actively maintained, with frequent releases addressing bug fixes, new features, and compatibility updates, often leveraging `pytest` for testing frameworks.

Common errors

```
ModuleNotFoundError: No module named 'tftest'
```
cause The `tftest` library has not been installed in your Python environment or the environment where your script is being run.

fix Run `pip install tftest` to install the package.
```
FileNotFoundError: [Errno 2] No such file or directory: 'terraform'
```
cause The `terraform` executable is not found in the system's PATH. `tftest` relies on invoking the `terraform` CLI.

fix Install the Terraform CLI and ensure its executable path is added to your system's PATH environment variable.
```
tftest failed when terraform plan is empty
```
cause This error occurs when `tftest` attempts to parse the output of a `terraform plan` command that results in no changes, and thus produces an unexpected or empty JSON structure.

fix Modify your test logic to anticipate and handle empty plans, for example, by checking if the plan indicates 'no changes' before attempting to parse resource-specific outputs, or by ensuring your test infrastructure always has a change to report.

Warnings

breaking Terragrunt support has been dropped in v1.8.7. Projects relying on `tftest` to interact with Terragrunt configurations will need to refactor their tests.
Fix: Migrate Terragrunt-specific logic to native Terraform configurations or use a different testing approach for Terragrunt. For testing Terragrunt, consider using Terratest (Go-based) or a direct Terragrunt wrapper.
breaking tftest versions 1.0.0 and above require Terraform 0.12 or newer. Tests written for older Terraform versions with previous `tftest` versions might be incompatible due to changes in Terraform's output format and command-line interface.
Fix: Ensure your Terraform modules target Terraform 0.12+ and update your `tftest` code to reflect any necessary API changes (e.g., how outputs are parsed).
gotcha The `terraform` CLI binary must be installed and accessible in your system's PATH for `tftest` to function. `tftest` acts as a Python wrapper around the `terraform` executable.
Fix: Install Terraform (e.g., via `brew install terraform` on macOS, or follow official HashiCorp instructions) and verify it's in your PATH by running `terraform --version` in your terminal.
gotcha Calling `tf.plan(output=True)` when the Terraform plan is empty (i.e., no changes to infrastructure) can lead to an error because `tftest` expects a structured output that might not be present in an empty plan.
Fix: Handle empty plan scenarios explicitly in your tests, possibly by checking the plan's content before attempting to parse specific outputs, or by ensuring the test case always expects some changes if `output=True` is used.
gotcha As `tftest` is commonly used with `pytest`, be aware of `pytest`'s own Python version compatibility changes. Newer `pytest` versions have dropped support for older Python versions (e.g., `pytest` 8.0 dropped Python 3.7/3.8, and future versions will drop Python 3.9).
Fix: Align your Python environment with the `pytest` version you're using. If `tftest` is installed in a project, update your `pytest` dependency and Python version accordingly to avoid compatibility issues.

Install

pip install tftest Install latest version

Imports

TerraformTest
```
from tftest import TerraformTest
```

Quickstart

This quickstart demonstrates how to use `tftest.TerraformTest` with `pytest` to initialize a simple Terraform module, run `terraform output`, and assert the expected value. Ensure the `terraform` CLI is installed and available in your system's PATH for this example to run successfully.

import pytest
import tftest
import os

# This fixture creates a temporary Terraform module for the test.
# In a real project, 'tf_module' would point to your actual Terraform module directory.
@pytest.fixture(scope="module")
def tf_module(tmp_path_factory):
    tf_dir = tmp_path_factory.mktemp("terraform_module_for_tftest")
    (tf_dir / "main.tf").write_text("""
output "greeting" {
  value = "Hello from Terraform!"
}
""")
    
    tf = tftest.TerraformTest(tf_dir)
    tf.setup() # Runs 'terraform init'
    return tf

def test_greeting_output(tf_module):
    # Run 'terraform output' and assert its value
    output = tf_module.output()
    assert output["greeting"]["value"] == "Hello from Terraform!"

view raw JSON →