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
- Only registry sources support the
versionargument. - 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
| Source | Example | Version pinning |
|---|---|---|
| Public registry | terraform-aws-modules/vpc/aws | version argument |
| Private registry | app.terraform.io/acme/vpc/aws | version argument |
| Git | git::https://example.com/vpc.git?ref=v1.2.0 | ref in the URL |
| Local path | ./modules/vpc | None; 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
| Rule | Public registry | Private registry |
|---|---|---|
| Repository | Public GitHub | Connected VCS provider |
| Name | terraform-<PROVIDER>-<NAME> | Same pattern in common use |
| Versions | Semantic version tags such as v1.0.4 | Tags, or branch-based publishing |
| Structure | Standard module structure | Standard 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.
Plan, apply and mocks
| Approach | Creates real objects | Good for |
|---|---|---|
command = plan | No | Logic, unit-style tests |
command = apply (the default) | Yes, then destroyed | Integration tests |
mock_provider (1.7 and later) | No | Testing without credentials |
override_resource, override_data, override_module | No, for that target | Slow 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 runterraform init -upgrade. - "A test must check naming logic with no cloud credentials." Use
mock_providerorcommand = planwith mocks. - "Tests must prove bad input is rejected." Use
expect_failureson the variable.
What to remember for the exam
- Only registry sources support the
versionargument. - 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_failuresfails if the listed object does not fail. - Terraform destroys test resources in reverse run order.
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.