Python Test Helper for Terraform
This simple helper facilitates testing Terraform modules from Python unit tests, by wrapping the Terraform executable and exposing convenience methods to set up fixtures, execute Terraform commands, and parse their output.
It allows for different types of tests: lightweight tests that only use Terraform init and plan to ensure code is syntactically correct and the right number and type of resources should be created, or full-fledged tests that run the full apply/output/destroy cycle, and can then be used to test the actual created resources, or the state file.
As an additional convenience, the module also provides an easy way to request and access the plan output (via terraform plan -out and terraform show) and the outputs (via terraform output -json), and return them wrapped in simple classes that streamline accessing their attributes.
This module is heavily inspired by two projects: Terratest for the lightweight approach to testing Terraform, and python-terraform for wrapping the Terraform command in Python.
Example Usage
The test folder contains simple examples on how to write tests for both plan and apply, using either synthetic fixtures (simple representations of the plan output and output files), or minimal root modules. More examples can be found in the Cloud Foundation Fabric repository, for which this module was developed.
This is a test that uses plan output on an actual module:
import pytest
import tftest
@pytest.fixture
def plan(fixtures_dir):
tf = tftest.TerraformTest('plan', fixtures_dir)
tf.setup(extra_files=['plan.auto.tfvars'])
return tf.plan(output=True)
def test_variables(plan):
assert 'prefix' in plan.variables
assert plan.variables['names'] == ['one', 'two']
def test_outputs(plan):
assert sorted(plan.outputs['gcs_buckets'].keys()) == plan.variables['names']
def test_root_resource(plan):
res = plan.resources['google_project_iam_member.test_root_resource']
assert res['values']['project'] == plan.variables['project_id']
def test_modules(plan):
mod = plan.modules['module.gcs-buckets']
res = mod.resources['google_storage_bucket.buckets[0]']
assert res['values']['location'] == plan.variables['gcs_location']
Caching
The TerraformTest setup, init, plan, apply, output and destroy methods have the ability to cache it's associate output to a local .tftest-cache directory. For subsequent calls of the method, the cached value can be returned instead of calling the actual underlying terraform command. Using the cache value can be significantly faster than running the Terraform command again especially if the command is time-intensive.
To determine if the cache should be used, first a hash value is generated using the current TerraformTest instance __init__ and calling method arguments, file contents of the tfdir and file contents of any tf_var_file or extra_files method argument. The hash value is compared to the hash value of the cached instance's associated arguments. If the hash is the same then the cache is used, otherwise the method is executed.
The benefits of the caching feature include:
- Faster setup time for testing terraform modules that don't change between testing sessions
- Writing tests without worrying about errors within their test code resulting in the Terraform setup logic to run again
Please see the following example for how to use it:
import pytest
import tftest
@pytest.fixture
def output(fixtures_dir):
tf = tftest.TerraformTest('apply', fixtures_dir, enable_cache=True)
tf.setup(use_cache=True)
tf.apply(use_cache=True)
yield tf.output(use_cache=True)
tf.destroy(use_cache=True, **{"auto_approve": True})
def test_apply(output):
value = output['triggers']
assert len(value) == 2
assert list(value[0].keys()) == ['name', 'template']
assert value[0]['name'] == 'one'
Compatibility
Starting from version 1.0.0 Terraform 0.12 is required, and tests written with previous versions of this module are incompatible. Check the CHANGELOG.md file for details on what's changed.
Testing
Tests use the pytest framework and have no other dependency except on the Terraform binary. The version used during development is in the DEV-REQUIREMENTS.txt file.
Disclaimer
This is not an officially supported Google product.
2 maintainers
Release files for tftest 1.8.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tftest-1.8.8.tar.gz | 20.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tftest-1.8.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 35.7 kB
Release files / tftest-1.8.8.tar.gz
| Download URL | tftest-1.8.8.tar.gz |
|---|---|
| Size | 20.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7e51e1bb817cfa4e2917af1c2407a85af0f8dbf33aee403884b9a14a40ab179f
|
|
BLAKE2b-256 checksum How to use checksums |
2962874d68c1296ff933e9ad3559cc93197f72094b970e2d983ccbf1cfc3d52b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.
Transparency logRelease files / tftest-1.8.8-py3-none-any.whl
| Download URL | tftest-1.8.8-py3-none-any.whl |
|---|---|
| Size | 14.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
484cf569ccc29fbf521259e18a279ec5a350179c85876603fca4f0edcad8f86b
|
|
BLAKE2b-256 checksum How to use checksums |
0a6600a08b1ec64ef9560563c313734a61c56ae8df29e3ec92c142bf194ba1fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.
Transparency log
