skip to content

With Terratest, how do you stop parallel test runs in one sandbox account colliding on resource names and on Terraform's working files?

level: middleimportance: should knowfreq 38%

answer

  1. names must be injectable
  2. six random characters per run
  3. local files collide as well
  4. a private copy of the folder
  5. the backend key needs the ID too

basics

~20 s

Expose resource names as module variables and feed them a random.UniqueID suffix, so runs do not clash on names. CopyTerraformFolderToTemp gives each test its own working directory, so .terraform and local state files stay separate.

solid answer

~40 s

I make every name that must be unique a module variable, then pass `random.UniqueID()` through `Vars`. It returns six base-62 characters: short enough for most name limits and random enough to make a clash unlikely. That stops two parallel tests, or a leftover from a killed run, colliding with the current run. Names are only half of it: tests sharing a folder overwrite each other's `.terraform` directory and `terraform.tfstate`, so I call `test_structure.CopyTerraformFolderToTemp` to give each test a private copy. With a remote backend, I also put the ID in the state key through `BackendConfig`. The ID can contain capitals, so for names that must be lowercase I wrap it in `strings.ToLower`.

code

go · 20 lines
go
func TestVpcModule(t *testing.T) {
	t.Parallel()
	ctx := t.Context()

	dir := test_structure.CopyTerraformFolderToTemp(t, "..", "examples/vpc")
	id := strings.ToLower(random.UniqueID())

	options := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
		TerraformDir: dir,
		Vars:         map[string]any{"name": "terratest-vpc-" + id},
		BackendConfig: map[string]any{
			"bucket": "sandbox-test-state",
			"key":    id + "/terraform.tfstate",
			"region": "eu-west-1",
		},
	})

	defer terraform.DestroyContext(t, ctx, options)
	terraform.InitAndApplyContext(t, ctx, options)
}

go deeper

for a junior

Recall that test resources need unique names, that random.UniqueID produces a short suffix, and that the module has to accept names as input variables for that to work.

for a middle

Explain the two collision surfaces separately: cloud names and local files. Know what CopyTerraformFolderToTemp copies, what it leaves out, and why a remote backend key needs the ID too.

for a senior

Connect naming to failure recovery: a per-run state key and a recognisable prefix are what make a leftover findable and removable after a run dies. Point out that quotas remain shared.

for a principal

Decide whether unique naming inside a shared account is enough or whether contention and blast radius now justify separate accounts, and make the naming convention a rule rather than a per-suite habit.

A Terratest suite deploys real resources into a real account, and Go runs tests marked `t.Parallel()` at the same time. Several CI jobs may share that account as well. Two separate things can then collide: the **names of cloud resources** and **Terraform's files on disk**. Each needs its own fix. ## Why names clash Many resources need a name that is unique within an account or region. A hard-coded name causes three problems: - **Parallel tests clash.** Two tests apply the same module at once, and the second fails on a name already taken. - **A leftover blocks the next run.** A killed run leaves its resource behind, and later runs fail on that name until someone removes it. - **Other resources are at risk.** Terratest's docs give this as the first reason to namespace, even though the test environment should be isolated from production anyway. These failures look like defects in the module when the fault is in the test setup, which makes them slow to diagnose. ## Make names injectable, then randomise them The module has to accept names as input variables, because a module that hard-codes them cannot be deployed twice side by side. Terratest's docs treat this as a benefit: passing environment-specific details in tends to make infrastructure code cleaner and more flexible. The test then generates one suffix per run and uses it everywhere in that run. `random.UniqueID()` has these properties: - **Format.** It returns six characters of base 62: digits, uppercase and lowercase letters. - **Odds, not a guarantee.** 62^6 is over 56 billion combinations. The source comment calls the result "unique (ish)" and unlikely to collide with the handful of tests running in parallel. - **Mixed case.** Where a name must be lowercase, wrap it in `strings.ToLower`, as Terratest's own backend example does for a bucket name. That shrinks the alphabet to 36 characters, which still leaves over 2 billion combinations. - **Spelling.** `random.UniqueId` is the deprecated alias in 1.0; new code calls `random.UniqueID`. A readable prefix such as `terratest-vpc-` helps too, because a person or a cleanup job can later recognise a leftover by its name. Generate the ID **once per test** and reuse that one value for every name in the run. Separate IDs for each resource make leftovers harder to group, and they add nothing to the isolation. Terratest's own examples go a step further and pick a random region with `aws.GetRandomStableRegionContext`, which they say helps show that the code works in all regions. ## Separate working directories Unique names do nothing for local files. Running `terraform init` and `terraform apply` in a folder writes `.terraform` there and, on the local backend, `terraform.tfstate`. Two parallel tests pointing at `../examples/vpc` overwrite each other's files. `test_structure.CopyTerraformFolderToTemp(t, rootFolder, moduleFolder)` fixes this in three steps: 1. It copies the whole root folder, not only the module, so relative module paths still resolve. 2. It returns the path of the module inside that copy, which you pass as `TerraformDir`. 3. It leaves out hidden files, `terraform.tfstate` and `terraform.tfvars`, while keeping the dependency lock file. The third step has a consequence. A test that quietly relied on a `terraform.tfvars` in the folder loses those values in the copy, so pass them through `Vars` instead. ## Unique state keys Copying a folder isolates local state only. With a remote backend, two tests using the same key share one state, whichever folder they run from. Pass a per-run key through `BackendConfig`, as Terratest's backend example does with `uniqueID + "/terraform.tfstate"`. A per-run key also means the state outlives the runner, which matters when a job dies before it can clean up. ## What collides and what fixes it | What collides | Typical symptom | Fix | |---|---|---| | Cloud resource name | Apply fails because the name is in use | Name variable fed by `random.UniqueID()` | | `.terraform`, local `terraform.tfstate` | Confusing init or state errors only under parallel runs | `CopyTerraformFolderToTemp` | | Remote state key | One test plans changes to another test's resources | Unique `key` through `BackendConfig` | Unique names do not remove every form of contention. Parallel tests still draw on the same account quotas, so a suite can fail on a limit while every name is distinct. Reducing concurrency or splitting accounts is the answer to that, and no naming scheme will help.

  • Why not keep a fixed resource name in a Terratest test and rely on the deferred destroy to free it?
    The destroy only frees the name after the test ends, so parallel runs still clash during the run. If a runner dies, the destroy never happens and the name stays taken, so every later run fails until someone cleans up. A per-run suffix makes each run independent of what earlier runs left behind.
  • Does lowercasing a Terratest `random.UniqueID()` value make collisions a real concern?
    Rarely, for a normal suite. The alphabet falls from 62 characters to 36, which still gives over 2 billion six-character combinations. The source describes the ID as unlikely to collide among a handful of parallel tests, not as guaranteed unique. If a suite runs very large numbers of concurrent tests, add more of the run's identity to the name.

  • random.UniqueID guarantees that no two runs can ever receive the same ID.
  • Unique resource names alone make parallel tests in one module folder safe.
  • Hard-coded resource names are fine as long as each test destroys its resources.
  • The output of random.UniqueID can be used as is in a lowercase-only name.
  • Copying the folder to temp isolates state even when tests share one remote backend key.