|
| 1 | +--- |
| 2 | +layout: collection-browser-doc |
| 3 | +title: Overview |
| 4 | +category: migrating-to-v1 |
| 5 | +excerpt: >- |
| 6 | + Summary of breaking changes in Terratest v1.0.0 and where to look first. |
| 7 | +tags: ["migration", "v1"] |
| 8 | +order: 300 |
| 9 | +nav_title: Documentation |
| 10 | +nav_title_link: /docs/ |
| 11 | +--- |
| 12 | + |
| 13 | +Terratest v1.0.0 is the first stable release. Once you are on v1, breaking |
| 14 | +changes to the public API only happen in major releases (e.g. v2.0.0), per |
| 15 | +[semver](https://semver.org/). Renamed or replaced symbols stay around as |
| 16 | +deprecated aliases inside v1; full removal is deferred to v2. |
| 17 | + |
| 18 | +This page is the orientation map for v0.x to v1.0.0. It tells you what |
| 19 | +shape the changes take and where to look; the per-service guides hold the |
| 20 | +mechanical details. |
| 21 | + |
| 22 | +## Prerequisites |
| 23 | + |
| 24 | +- **Go 1.26 or newer.** v1.0.0 raised the minimum. |
| 25 | +- After upgrading, run `go mod tidy` from the directory that holds your |
| 26 | + test module's `go.mod`. The AWS, Azure, and GCP SDK pins all moved. |
| 27 | + |
| 28 | +## Function naming conventions |
| 29 | + |
| 30 | +Most public Terratest helpers come in up to four variants. Knowing which |
| 31 | +to call is the most common source of confusion when reading v1 godoc: |
| 32 | + |
| 33 | +| Suffix | Takes `context.Context` | On error | |
| 34 | +| --- | --- | --- | |
| 35 | +| `Foo` | no | calls `t.Fatal` (fails the test) | |
| 36 | +| `FooE` | no | returns `error` to the caller | |
| 37 | +| `FooContext` | yes | calls `t.Fatal` | |
| 38 | +| `FooContextE` | yes | returns `error` | |
| 39 | + |
| 40 | +Two independent suffixes: |
| 41 | + |
| 42 | +- **`E` suffix.** Long-standing Terratest convention. Use the bare name |
| 43 | + (`Apply`) when you want any failure to fail the test, and the `E` |
| 44 | + variant (`ApplyE`) when you want the error back to assert on it or |
| 45 | + retry. |
| 46 | +- **`Context` suffix.** Added in v1. Takes an explicit `context.Context` |
| 47 | + as the second argument so callers can plumb timeouts, cancellation, |
| 48 | + and tracing through. The non-`Context` variants are now deprecated |
| 49 | + in favor of their `*Context*` counterparts. |
| 50 | + |
| 51 | +The preferred v1 call is `FooContext` (or `FooContextE`). For example, |
| 52 | +prefer `terraform.ApplyContext(t, ctx, opts)` over |
| 53 | +`terraform.Apply(t, opts)`. |
| 54 | + |
| 55 | +A small number of helpers do not yet expose all four variants (some |
| 56 | +packages added `Context` and dropped the bare `Foo` form, others have |
| 57 | +not grown a `Context` variant at all). Trust godoc and the deprecation |
| 58 | +warnings over the table when they disagree. |
| 59 | + |
| 60 | +## Migrating to the `Context` variants |
| 61 | + |
| 62 | +The Context migration is the single largest source of deprecation |
| 63 | +warnings you will see when upgrading. It touches nearly every helper |
| 64 | +package: `terraform`, `helm`, `dns-helper`, `http-helper`, `packer`, |
| 65 | +`docker`, `ssh`, `oci`, `k8s`, `aws`, `azure`, `gcp`. The non-`Context` |
| 66 | +variants compile and behave the same as before; they just emit a |
| 67 | +`// Deprecated:` godoc warning. |
| 68 | + |
| 69 | +Mechanical migration: |
| 70 | + |
| 71 | +```go |
| 72 | +// Before |
| 73 | +out := terraform.Apply(t, options) |
| 74 | +out, err := terraform.ApplyE(t, options) |
| 75 | + |
| 76 | +// After |
| 77 | +ctx := context.Background() // or context.WithTimeout(...) for cancellation |
| 78 | +out := terraform.ApplyContext(t, ctx, options) |
| 79 | +out, err := terraform.ApplyContextE(t, ctx, options) |
| 80 | +``` |
| 81 | + |
| 82 | +The `*Context*` variants always take `(t, ctx, ...originalArgs)`. If |
| 83 | +you do not need cancellation or timeouts, `context.Background()` gives |
| 84 | +you the same behavior as the deprecated wrapper. When `t` is |
| 85 | +`*testing.T` (Go 1.24+), `t.Context()` is an even better default |
| 86 | +because it ties the context lifetime to the test. |
| 87 | + |
| 88 | +You can do this incrementally. The deprecated wrappers will keep |
| 89 | +working for the entire v1 line; they only disappear in v2. |
| 90 | + |
| 91 | +## What changed by service |
| 92 | + |
| 93 | +### Azure |
| 94 | + |
| 95 | +The largest set of breaking changes by far. The whole `modules/azure` |
| 96 | +package was moved from the archived `services/...` SDK to the actively |
| 97 | +maintained `sdk/resourcemanager/...` SDK, plus a handful of naming |
| 98 | +cleanups. Updating imports and the resulting compile errors is the bulk |
| 99 | +of the work; per-service tables and a search-and-replace cheatsheet are |
| 100 | +in [Azure modules](./azure/). |
| 101 | + |
| 102 | +### AWS |
| 103 | + |
| 104 | +`modules/aws/s3.go` migrated off the deprecated |
| 105 | +`s3/manager` package onto `s3/transfermanager`. Four exported functions |
| 106 | +that returned `*manager.Uploader` now return `*transfermanager.Client`: |
| 107 | +`NewS3Uploader`, `NewS3UploaderE`, `NewS3UploaderContext`, and |
| 108 | +`NewS3UploaderContextE`. The call shape moves from |
| 109 | +`uploader.Upload(ctx, &s3.PutObjectInput{...})` to |
| 110 | +`client.UploadObject(ctx, &transfermanager.UploadObjectInput{...})`, |
| 111 | +with the input/output types under |
| 112 | +`github.com/aws/aws-sdk-go-v2/feature/s3/transfermanager`. |
| 113 | + |
| 114 | +Every direct `github.com/aws/aws-*` dependency was bumped to the |
| 115 | +versions current at the v1.0.0 cut. If your tests import the AWS SDKs |
| 116 | +directly, expect to run `go mod tidy` and resolve a small number of |
| 117 | +type renames at the SDK level. |
| 118 | + |
| 119 | +### GCP |
| 120 | + |
| 121 | +`modules/gcp/pubsub.go` moved from `cloud.google.com/go/pubsub` (v1) to |
| 122 | +`cloud.google.com/go/pubsub/v2`. The wrapper functions in `modules/gcp` |
| 123 | +are unchanged in shape, but callers that drove the underlying client |
| 124 | +directly need to switch from `client.Topic("name")` / |
| 125 | +`client.Subscription("name")` handles to `TopicAdminClient` / |
| 126 | +`SubscriptionAdminClient` calls that take fully qualified resource |
| 127 | +names (`projects/<id>/topics/<name>`). |
| 128 | + |
| 129 | +A new family of `*WithClient` helpers was added across `modules/gcp` |
| 130 | +(compute, oslogin, region, pubsub, storage, cloudbuild, gcr) so tests |
| 131 | +can inject a pre-built SDK client. This parallels the Azure |
| 132 | +`*WithClient` change and is purely additive. |
| 133 | + |
| 134 | +### Kubernetes |
| 135 | + |
| 136 | +`GetKubernetesClientFromOptionsContextE` now logs the kubeconfig load |
| 137 | +error before falling back to `rest.InClusterConfig()`; previously the |
| 138 | +fallback was silent. |
| 139 | + |
| 140 | +This was a silent-failure footgun: a typo in |
| 141 | +`KubectlOptions.ConfigPath` would send tests against the test runner's |
| 142 | +in-cluster identity (potentially a different cluster) with no signal |
| 143 | +that anything had happened. v1 surfaces the error in the test log, and |
| 144 | +adds an explicit `KubectlOptions.InClusterAuth = true` opt-in that |
| 145 | +skips kubeconfig loading entirely for callers who want fully explicit |
| 146 | +auth. |
| 147 | + |
| 148 | +## Other deprecations you can defer |
| 149 | + |
| 150 | +A large set of legacy spellings picked up Go-idiomatic replacements in |
| 151 | +v1, all preserved as deprecated aliases. Most follow common acronym |
| 152 | +casing (`Id` → `ID`, `Ip` → `IP`, `Json` → `JSON`, `Url` → `URL`, |
| 153 | +`Ssh` → `SSH`, `Gcp` → `GCP`); a few drop redundant prefixes (Azure's |
| 154 | +`CreateNew*Client*` becomes `Create*Client*`); and a few rename for |
| 155 | +clarity (e.g. `SaveAmiId` / `LoadAmiId` became |
| 156 | +`SaveArtifactID` / `LoadArtifactID` to reflect that the helpers are |
| 157 | +not AMI-specific). |
| 158 | + |
| 159 | +You do not need to track these one by one. Run `go vet` or |
| 160 | +`staticcheck` against your test module after upgrading; the deprecated |
| 161 | +aliases all carry `// Deprecated:` annotations and the linter will |
| 162 | +list them with the replacement to use. Aliases stay for the v1 line |
| 163 | +and are removed in v2. |
| 164 | + |
| 165 | +## Need help |
| 166 | + |
| 167 | +Open an issue on the [Terratest |
| 168 | +repo](https://github.com/gruntwork-io/terratest/issues) with a snippet |
| 169 | +of the failing code and the relevant module label. If you spot a gap |
| 170 | +in this guide, send a PR against `docs/_docs/03_migrating-to-v1/`. |
0 commit comments