Advanced Module Usage and Registry Practices · Topic 2 of 2

Registry Practices and Module Tests

Terraform Professional (002): registry source addresses, upgrading module versions, publishing rules, and reading terraform test files with mocks.

  • 5 min
In a nutshell
  • Only registry sources support the version argument.
  • The lock file records providers, not module versions.
  • Run blocks default to command = apply, which creates real infrastructure.

What it is

A registry gives modules an address and version numbers, so configurations can reuse tested code and upgrade on purpose. terraform test is the built-in way to prove that a module does what its contract promises, using files that end in .tftest.hcl.

How it works

Source addresses

SourceExampleVersion pinning
Public registryterraform-aws-modules/vpc/awsversion argument
Private registryapp.terraform.io/acme/vpc/awsversion argument
Gitgit::https://example.com/vpc.git?ref=v1.2.0ref in the URL
Local path./modules/vpcNone; it travels with the code

The registry format is <NAMESPACE>/<NAME>/<PROVIDER>, with a hostname in front for a private registry. Only registry sources accept version. To reach a private registry, the CLI needs a token from terraform login, a credentials block or a TF_TOKEN_ variable.

Upgrading a module

Suppose a module is pinned at version = "3.0.2" and you need a feature from a later release.

module "vpc" {
  source  = "app.terraform.io/acme/vpc/aws"
  version = "3.2.0"
}
terraform init -upgrade
terraform plan

Change the version argument first, because -upgrade alone cannot move past an exact pin. It only selects the newest version the constraint allows. The dependency lock file tracks providers, not modules, so deleting it does not help here.

Publishing

RulePublic registryPrivate registry
RepositoryPublic GitHubConnected VCS provider
Nameterraform-<PROVIDER>-<NAME>Same pattern in common use
VersionsSemantic version tags such as v1.0.4Tags, or branch-based publishing
StructureStandard module structureStandard module structure

Tags that are not version numbers are ignored, and pushing a new tag publishes the release. In a private registry, publishing needs the owners team or the manage private registry permission, and deleting a Git tag does not delete the published version.

The standard structure is main.tf, variables.tf and outputs.tf in the root, plus a README and LICENSE, a modules/ directory for nested modules and an examples/ directory. A nested module without a README is treated as internal.

Writing a test

Assume the module has output "bucket_name" { value = "prod-${var.name}" } and a validation block requiring var.name to have at least 3 characters.

variables {
  name = "site"
}

run "adds_prefix" {
  command = plan
  assert {
    condition     = output.bucket_name == "prod-site"
    error_message = "Missing prefix"
  }
}

Trace it: name is site, so the output is prod-site, the condition is true, and the run passes. No infrastructure is created, because command = plan.

run "rejects_short_name" {
  command = plan
  variables {
    name = "ab"
  }
  expect_failures = [var.name]
}

Here the run-level name beats the file-level value. Validation fails as expected, so the run passes. If validation had succeeded, this run would fail.

Test fileterraform initProviders readyterraform testRun blocks in orderAssertionspass or failCleanupreverse run order

Plan, apply and mocks

ApproachCreates real objectsGood for
command = planNoLogic, unit-style tests
command = apply (the default)Yes, then destroyedIntegration tests
mock_provider (1.7 and later)NoTesting without credentials
override_resource, override_data, override_moduleNo, for that targetSlow or unwanted dependencies

With command = plan, computed attributes are unknown. A mocked provider generates values at apply by default, but override_during = plan makes them available during plan.

mock_provider "aws" {
  mock_resource "aws_s3_bucket" {
    defaults = {
      arn = "arn:aws:s3:::test-bucket"
    }
  }
}

Required attributes come from you. Unset computed attributes are generated by type: numbers 0, booleans false, strings a random value, collections empty.

Running tests

terraform init
terraform test -filter=tests/naming.tftest.hcl -junit-xml=results.xml

Terraform looks for tests in the configuration root and the tests directory. Variables in test files beat -var, environment variables and var files, and your real state is untouched. -verbose prints the plan or state for each run, and -junit-xml suits CI reporting.

expect_failures works only on user-defined custom conditions in the operation named by command. It is best paired with command = plan, since a plan-time failure under command = apply still fails the run.

How the exam asks about this

  • "The module block pins an exact release, and a later one is needed." Change version, then run terraform init -upgrade.
  • "A test must check naming logic with no cloud credentials." Use mock_provider or command = plan with mocks.
  • "Tests must prove bad input is rejected." Use expect_failures on the variable.

What to remember for the exam

  • Only registry sources support the version argument.
  • The lock file records providers, not module versions.
  • Run blocks default to command = apply, which creates real infrastructure.
  • Run-level variables beat file-level variables, which beat -var.
  • A run with expect_failures fails if the listed object does not fail.
  • Terraform destroys test resources in reverse run order.
Watch out

A run with no command line uses apply and builds real, possibly billable infrastructure. Set command = plan or use mocks when you mean a unit test.

Common mistakes

Running terraform init -upgrade with an exact pin. An exact version leaves nothing newer to select. Edit the constraint first.

Using version with a Git source. Terraform accepts version only for registry modules. Use ?ref= for Git.

Asserting on a computed attribute during plan. The value is known only after apply. Use command = apply, or a mock with override_during = plan.

Check yourself

  • What command updates a registry module after you change its version argument?

    terraform init -upgrade, which installs the release allowed by the new constraint.

  • What does a run block do if command is not set?

    It uses apply, creating real short-lived infrastructure that Terraform tries to destroy at the end of the test file.

  • When does a run with expect_failures pass?

    When the listed object, such as a variable with a validation rule, reports the expected failure in the operation named by command.

Topic 2 of 2 in Advanced Module Usage and Registry Practices

Test yourself on Advanced Module Usage and Registry Practices

The full HashiCorp Terraform Infrastructure Engineer Professional question bank has 600 questions, with timed practice exams and an explanation for every answer.

This study guide is independent and is not affiliated with, endorsed by, or sponsored by HashiCorp. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.