tftest

library1.8.7pypypi✓ verified 87d ago

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.

testing devops

pip install tftest

github ↗package ↗

INSTALL

IMPORT

SIG · TFTEST

tftest

testingpythonv1.8.7

Install

1.5s avg

Import

85ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.8.7 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.086s · 17.8MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.5s · import 0.083s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TerraformTest

✓ from tftest import TerraformTest

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!"

Debug

Known issues

breakingTerragrunt 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.

affects: >=1.8.7

breakingtftest 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).

affects: >=1.0.0

gotchaThe `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.

affects: All

gotchaCalling `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.

affects: All

gotchaAs `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.

affects: All (indirectly)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'tftest'

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'

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

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.

Upgrade

Version history

1.8.7latest on PyPI · released Mar 31, 2026

Audit

Dependencies

pytestoptionalCommonly used testing framework with tftest.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/GoogleCloudPlatform/terraform-python-testing-helper ↗

packagehttps://pypi.org/project/tftest/ ↗