{"id":15221682,"url":"https://github.com/googlecloudplatform/terraform-python-testing-helper","last_synced_at":"2025-04-12T17:44:42.005Z","repository":{"id":34307580,"uuid":"177010080","full_name":"GoogleCloudPlatform/terraform-python-testing-helper","owner":"GoogleCloudPlatform","description":"Simple Python test helper for Terraform.","archived":false,"fork":false,"pushed_at":"2024-06-21T11:38:50.000Z","size":200,"stargazers_count":222,"open_issues_count":8,"forks_count":32,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-12T05:05:37.942Z","etag":null,"topics":["python","terraform","testing"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/tftest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GoogleCloudPlatform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-21T19:20:33.000Z","updated_at":"2025-04-06T13:39:37.000Z","dependencies_parsed_at":"2024-01-13T16:25:45.818Z","dependency_job_id":"a949d80d-2294-4461-bb68-7f0d25e7f15e","html_url":"https://github.com/GoogleCloudPlatform/terraform-python-testing-helper","commit_stats":{"total_commits":110,"total_committers":15,"mean_commits":7.333333333333333,"dds":0.2090909090909091,"last_synced_commit":"e11c6a97ab60eeacdf17665049dcdd38d01508e4"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fterraform-python-testing-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fterraform-python-testing-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fterraform-python-testing-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GoogleCloudPlatform%2Fterraform-python-testing-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GoogleCloudPlatform","download_url":"https://codeload.github.com/GoogleCloudPlatform/terraform-python-testing-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248609462,"owners_count":21132914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","terraform","testing"],"created_at":"2024-09-28T15:06:45.449Z","updated_at":"2025-04-12T17:44:41.979Z","avatar_url":"https://github.com/GoogleCloudPlatform.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Test Helper for Terraform\n\nThis 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.\n\nIt 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.\n\nAs 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.\n\nThis module is heavily inspired by two projects: [Terratest](https://github.com/gruntwork-io/terratest) for the lightweight approach to testing Terraform, and [python-terraform](https://github.com/beelit94/python-terraform) for wrapping the Terraform command in Python.\n\n## Example Usage\n\nThe [`test`](https://github.com/GoogleCloudPlatform/terraform-python-testing-helper/tree/master/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](https://github.com/terraform-google-modules/cloud-foundation-fabric) repository, for which this module was developed.\n\nThis is a test that uses plan output on an actual module:\n\n```hcl\nimport pytest\nimport tftest\n\n\n@pytest.fixture\ndef plan(fixtures_dir):\n  tf = tftest.TerraformTest('plan', fixtures_dir)\n  tf.setup(extra_files=['plan.auto.tfvars'])\n  return tf.plan(output=True)\n\n\ndef test_variables(plan):\n  assert 'prefix' in plan.variables\n  assert plan.variables['names'] == ['one', 'two']\n\n\ndef test_outputs(plan):\n  assert sorted(plan.outputs['gcs_buckets'].keys()) == plan.variables['names']\n\n\ndef test_root_resource(plan):\n  res = plan.resources['google_project_iam_member.test_root_resource']\n  assert res['values']['project'] == plan.variables['project_id']\n\n\ndef test_modules(plan):\n  mod = plan.modules['module.gcs-buckets']\n  res = mod.resources['google_storage_bucket.buckets[0]']\n  assert res['values']['location'] == plan.variables['gcs_location']\n```\n\n## Terragrunt support\n\nSupport for Terragrunt actually follows the same principle of the thin `TerraformTest` wrapper.\n\nPlease see the following example for how to use it:\n\n```python\nimport pytest\nimport tftest\n\n\n@pytest.fixture\ndef run_all_apply_out(fixtures_dir):\n  # notice for run-all, you need to specify when TerragruntTest is constructed\n  tg = tftest.TerragruntTest('tg_apply_all', fixtures_dir, tg_run_all=True)\n  # the rest is very similar to how you use TerraformTest\n  tg.setup()\n  # to use --terragrunt-\u003coption\u003e, pass in tg_\u003coption in snake case\u003e\n  tg.apply(output=False, tg_non_interactive=True)\n  yield tg.output()\n  tg.destroy(auto_approve=True, tg_non_interactive=True)\n\n  \ndef test_run_all_apply(run_all_apply_out):\n    triggers = [o[\"triggers\"] for o in run_all_apply_out]\n    assert [{'name': 'foo', 'template': 'sample template foo'}] in triggers\n    assert [{'name': 'bar', 'template': 'sample template bar'}] in triggers\n    assert [{'name': 'one', 'template': 'sample template one'},\n            {'name': 'two', 'template': 'sample template two'}] in triggers\n    assert len(run_all_apply_out) == 3\n```\n\n## Caching\n\nThe `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.\n\nTo 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.\n\nThe benefits of the caching feature include:\n- Faster setup time for testing terraform modules that don't change between testing sessions\n- Writing tests without worrying about errors within their test code resulting in the Terraform setup logic to run again\n\nPlease see the following example for how to use it:\n\n```python\nimport pytest\nimport tftest\n\n\n@pytest.fixture\ndef output(fixtures_dir):\n  tf = tftest.TerraformTest('apply', fixtures_dir, enable_cache=True)\n  tf.setup(use_cache=True)\n  tf.apply(use_cache=True)\n  yield tf.output(use_cache=True)\n  tf.destroy(use_cache=True, **{\"auto_approve\": True})\n\n\ndef test_apply(output):\n  value = output['triggers']\n  assert len(value) == 2\n  assert list(value[0].keys()) == ['name', 'template']\n  assert value[0]['name'] == 'one'\n\n```\n\n\n\n## Compatibility\n\nStarting 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`](https://github.com/GoogleCloudPlatform/terraform-python-testing-helper/blob/master/CHANGELOG.md) file for details on what's changed.\n\n## Testing\n\nTests 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.\n\n## Disclaimer\n\nThis is not an officially supported Google product.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Fterraform-python-testing-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgooglecloudplatform%2Fterraform-python-testing-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgooglecloudplatform%2Fterraform-python-testing-helper/lists"}