pytest-terraform is a pytest plugin that enables provisioning infrastructure via Terraform as a fixture within unit and functional tests.
The plugin solves the problem of integrating Terraform-based infrastructure provisioning into test suites by providing a decorator-based fixture factory pattern. Tests can reference Terraform modules through a `terraform` decorator that accepts parameters for the module directory, fixture scope, teardown behavior, and fixture naming. The plugin automatically discovers Terraform modules in standard locations relative to test files or in an explicitly specified directory. It supports three teardown modes: always destroy resources, destroy while ignoring failures, or skip teardown entirely.
The tool suits projects that need to validate infrastructure code or test applications against real or simulated infrastructure. It is particularly valuable for teams already using pytest and Terraform together. The plugin's replay mode, enabled by default, allows tests to run against recorded resource snapshots rather than invoking Terraform each time, enabling faster test execution and offline testing. Tests using Terraform fixtures are automatically marked so they can be selected and run separately from other tests. Developers can provide an explicit path to the Terraform binary or let the plugin auto-discover it. The plugin also provides pytest hooks, specifically `pytest_terraform_modify_state`, that can be implemented in conftest.py files to customize behavior.
The project maintains active engagement with its codebase through regular updates and refinements to its core functionality. Development includes ongoing work to expand scope support beyond the fully tested function and session scopes. The maintainers actively document edge cases and provide clear guidance on when specific features like the OFF teardown mode should be used. The project demonstrates responsiveness to practical testing scenarios, such as supporting tests that perform destructive actions against provisioned resources.
