Terratest 2.0 Released!

Terratest 2.0 is officially released! 🎉

The library is now 16 independent Go modules instead of one monolithic module, each released and versioned on its own. A test that imports the Terratest AWS helpers no longer pulls in the Kubernetes client, the Azure and GCP SDKs, or the dependencies of any other module.

When we released 1.0 in May we said 2.0 would do this, and that the upgrade should be as small as adding /v2 to your imports. That is how it turned out. The rest of this post explains why we did it and what else changed.

The problem with one module

Up until 2.0, Terratest was a single Go module. Import any package from it and Go had to resolve the dependencies of every package in it. A project that tested one Lambda function got the Kubernetes client, the Azure and GCP SDKs, Docker's CLI, and the OpenAPI tooling in its go.sum, regardless of whether any of this was used. Security scanners could make this pretty annoying for Terratest users. They flag vulnerabilities for dependencies in the dependency graph, even when the dependency isn't used in a particular test.

The community has been asking for this split for a while. Most Terratest users only use a small subset of the features in the library, and don't want to have to install dependencies they don't use.

At the same time, the scope of capabilities in Terratest has expanded due to demand from the community: Terratest has testing utilities for Terragrunt, OpenTofu/Terraform, Kubernetes, Helm, Docker, OPA, SSH, and more. Every new capability added made the problem worse for everyone who didn't take advantage of it.

Rolling this out responsibly meant a major release, so it shipped as v2 of the library.

What changed

Each area of the library is its own Go module with a /v2-suffixed import path: modules/aws/v2, modules/k8s/v2, modules/terraform/v2, and so on.

Usage of the library remains identical for everything that wasn't deprecated. All you have to do to start using v2 is to update your import path:

// v1
import "github.com/gruntwork-io/terratest/modules/aws"

// v2
import "github.com/gruntwork-io/terratest/modules/aws/v2"

If you only use the AWS helpers, your dependency graph will drop from 247 modules to 85.

What we removed

Given that we were already making a major version bump, it was also a good opportunity to drop functionality that was deprecated in 1.0 or never belonged in Terratest to begin with.

The following are removed in 2.0:

• The cmd/ binaries, terratest_log_parser and pick-instance-type.
• The collections, environment, and git helpers in core. The standard library or a one-line os/exec call does the same job.
• version-checker and slack.
• Every // Deprecated: alias left over from the 0.x to 1.0 renames.

Three packages have been renamed to drop their hyphens:

• http-helper is now httphelper
• dns-helper is dnshelper
• test-structure is teststructure

The package name now matches the import path, which is what linters and editors expect.

The minimum required version of Go is now 1.26.

Upgrading from v1

If your tests already run without deprecation warnings, add /v2 to every import, rename any imports of the three previously hyphenated packages, then run go mod tidy.

Each module you import is now its own requirement in go.mod, so a test that uses both the Terragrunt and AWS helpers pins both:

go get github.com/gruntwork-io/terratest/modules/terragrunt/v2@v2.0.0
go get github.com/gruntwork-io/terratest/modules/aws/v2@v2.0.0
go mod tidy

go mod tidy drops the dependencies nothing imports any more.

If your tests still use functionality that 1.0 deprecated, staticcheck or your editor will point at each call, and the deprecation notice names the replacement.

The v2 migration guide lists the removed helpers and what replaces each one.

1.0 remains importable at v1.0.1 on proxy.golang.org. 2.0 is a different import path, so nothing upgrades until you edit an import. You can move one module at a time.

Beyond 2.0

We don't plan on many more major versions. We needed a v2.y.z release to get the /v2-suffixed import paths, so users can opt in to this breaking change in dependency resolution.

When a breaking change is coming, it will appear as // Deprecated: notices in the major version before removal, so staticcheck, your editor, and your agents warn you ahead of time.

If we do end up creating a 3.0, you will be able to adopt it when convenient, the same way, through a /v3 import path.

Join the community

Terratest shares a community with Terragrunt, and most of the conversation happens on the Terragrunt Discord server. The maintainers and the Terragrunt Ambassadors hang out there. Bring questions about cloud integration testing, Kubernetes, Helm, OPA, or anything else Terratest touches.

Thanks to everyone who kept pushing us to split up the library and supplied their feedback. 2.0 exists because you did.