OpenTofu Testing: Migrating from Terraform and Test Compatibility

OpenTofu is the open-source, community-driven fork of Terraform, created after HashiCorp changed Terraform's license from MPL to BSL 1.1 in August 2023. If you've been using Terraform — and especially if you've built tests with Terratest or the native .tftest.hcl framework — you need to know what migrating to OpenTofu means for your test suite.

The short answer: most things work without changes. The longer answer: there are differences worth understanding.

What Is OpenTofu?

OpenTofu was forked from Terraform 1.5.x by the Linux Foundation. It maintains backward compatibility with Terraform configurations while adding features and moving faster than HashiCorp's Terraform on some fronts.

As of OpenTofu 1.7+, it supports:

• The same .tf configuration syntax
• Same provider ecosystem (Terraform Registry providers work in OpenTofu)
• The .tftest.hcl native testing framework
• State file compatibility with Terraform
• The same backends (S3, GCS, Azure Blob, etc.)

Installing OpenTofu

# macOS
brew install opentofu

# Linux (official install script)
curl --proto '=https' --tlsv1.2 -fsSL https://get.opentofu.org/install-opentofu.sh | sh

# Verify
tofu version
# OpenTofu v1.7.x

The binary is tofu, not terraform.

Migration: What Changes

The Binary Name

The most immediate change: replace terraform with tofu in your scripts, CI pipelines, and local workflows.

# Before (Terraform)
terraform init
terraform plan
terraform apply
terraform test

# After (OpenTofu)
tofu init
tofu plan
tofu apply
tofu test

That's it for basic workflows. Your .tf files don't change.

Provider Sources

OpenTofu uses a different default registry:

• Terraform: registry.terraform.io
• OpenTofu: registry.opentofu.org

In practice, most providers are mirrored to both registries. If you're using HashiCorp-maintained providers (AWS, GCP, Azure), they work on both. For obscure providers, check availability on registry.opentofu.org.

If your required_providers block specifies source explicitly, no change needed:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

OpenTofu will find hashicorp/aws on its registry automatically.

State File Compatibility

State files are fully compatible. You can switch a project from Terraform to OpenTofu without migrating state:

# Initialize with OpenTofu (existing Terraform state works)
tofu init
tofu plan  # reads existing terraform.tfstate

The state format hasn't diverged. You can switch back and forth between tofu and terraform against the same state file.

Testing with OpenTofu

Native Testing Framework (.tftest.hcl)

OpenTofu fully supports the .tftest.hcl testing framework. Existing Terraform test files work as-is:

# Runs exactly the same as terraform test
tofu test

# Specific file
tofu test -filter=tests/unit.tftest.hcl

# Verbose output
tofu test -verbose

All the features covered in the Terraform native testing guide apply directly:

# tests/vpc_test.tftest.hcl
mock_provider "aws" {}

variables {
  cidr_block  = "10.0.0.0/16"
  environment = "test"
}

run "vpc_creates_with_correct_cidr" {
  command = plan

  assert {
    condition     = aws_vpc.main.cidr_block == var.cidr_block
    error_message = "VPC CIDR doesn't match input"
  }
}

tofu test
# tests/vpc_test.tftest.hcl... in progress
#   run "vpc_creates_with_correct_cidr"... pass
# Success! 1 passed, 0 failed.

OpenTofu-Specific Testing Features

OpenTofu has been adding features that aren't in Terraform:

Provider functions (1.7+): Call provider-defined functions in tests and configurations. This opens up dynamic logic that previously required workarounds.

Encrypted state (1.7+): Test configurations that use OpenTofu's built-in state encryption — a feature Terraform doesn't have.

Terratest with OpenTofu

Terratest doesn't care whether you're running terraform or tofu — it shells out to the binary. Tell it to use tofu:

terraformOptions := &terraform.Options{
    TerraformDir:    "../",
    TerraformBinary: "tofu",  // use tofu instead of terraform
}

Or set it via environment variable:

export TERRAFORM_CLI_PATH=$(which tofu)

Everything else in your Terratest tests works unchanged.

Migration Checklist

Before switching a project from Terraform to OpenTofu:

□ Install OpenTofu: brew install opentofu
□ Run tofu init — verify providers download correctly
□ Run tofu plan — compare output to terraform plan
□ Run tofu test — verify all existing tests pass
□ Update CI/CD: replace terraform with tofu in pipeline steps
□ Update setup steps in GitHub Actions (use opentofu/setup-opentofu@v1)
□ Check any tooling that shells out to terraform binary
□ Update team documentation

CI/CD with OpenTofu

GitHub Actions

Use the official OpenTofu setup action:

name: OpenTofu Tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup OpenTofu
        uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: "1.7.0"

      - name: OpenTofu Init
        run: tofu init
        working-directory: modules/vpc

      - name: OpenTofu Test (Unit - no credentials)
        run: tofu test -filter=tests/unit.tftest.hcl
        working-directory: modules/vpc

      - name: OpenTofu Test (Integration)
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: tofu test -filter=tests/integration.tftest.hcl
        working-directory: modules/vpc

GitLab CI

opentofu-test:
  image: ghcr.io/opentofu/opentofu:1.7
  stage: test
  script:
    - tofu init
    - tofu test
  variables:
    AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
    AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY

Tool Compatibility

For Terraform Cloud, alternatives include: Spacelift, Scalr, env0, or self-hosted Atlantis.

OpenTofu-Only Testing Features

OpenTofu is diverging from Terraform in meaningful ways. Features you can test with OpenTofu that Terraform doesn't have:

State Encryption Testing

# OpenTofu 1.7+: state encryption
terraform {
  encryption {
    key_provider "pbkdf2" "my_passphrase" {
      passphrase = var.state_passphrase
    }
    method "aes_gcm" "default" {
      keys = key_provider.pbkdf2.my_passphrase
    }
    state {
      method = method.aes_gcm.default
    }
  }
}

You can test that your state encryption configuration is correct with tofu plan — it will fail with a clear error if the encryption configuration is invalid.

Provider Functions

# OpenTofu 1.7+: provider-defined functions
locals {
  # Call a function defined by the provider
  ami_id = provider::aws::arn_parse(var.ami_arn).account_id
}

These can be tested with mock_provider blocks in .tftest.hcl.

When to Stay on Terraform

OpenTofu is the right choice if:

• You're using open-source Terraform and want to stay open-source
• You need features OpenTofu ships before Terraform
• You want to avoid BSL licensing concerns
• You use community modules that have moved to OpenTofu

Stay on Terraform if:

• You're using Terraform Cloud / HCP Terraform
• Your organization has a Terraform Enterprise contract
• You use HashiCorp-specific features (Sentinel policies, private registry)

For most teams running open-source Terraform with AWS/GCP/Azure providers, OpenTofu is a drop-in replacement.

Migrating your test suite from Terraform to OpenTofu is mostly a find-and-replace of terraform with tofu. Your .tftest.hcl files, Terratest tests, Checkov scans, and CI pipelines all work with minimal changes. The investment is small; the benefit is freedom from licensing uncertainty and access to features HashiCorp may not ship.