🧪 Using mock_provider with configuration_aliases in Terraform Tests

Why Aliased Providers Complicate Tests

Many real modules use more than one configuration of the same provider — a multi-region deployment with aws.primary and aws.replica, or a cross-account setup with aws.audit. When a child module needs to receive these aliased configurations from its caller, it declares them with configuration_aliases inside required_providers. That declaration changes how you write tests, because a terraform test run must supply every provider configuration the module expects, including the aliased ones.

If you only mock the default provider, the test fails with an error about a missing required provider configuration. This guide shows the full wiring: configuration_aliases in the module, and mock_provider "aws" { alias = ... } plus providers = { ... } in the test.

Declaring configuration_aliases in the Module

A child module that expects two aws configurations declares them like this. Note that configuration_aliases goes in the provider requirement, not in a provider block:

# versions.tf
terraform {
  required_providers {
    aws = {
      source                = "hashicorp/aws"
      version               = ">= 5.0"
      configuration_aliases = [aws.primary, aws.replica]
    }
  }
}

Resources then pick a configuration with the provider meta-argument:

resource "aws_s3_bucket" "primary" {
  provider = aws.primary
  bucket   = var.bucket_name
}

resource "aws_s3_bucket" "replica" {
  provider = aws.replica
  bucket   = "${var.bucket_name}-replica"
}

Because configuration_aliases is declared, this module has no default (unaliased) aws provider — every AWS resource must name aws.primary or aws.replica.

Mocking Aliased Providers in a Test

In the .tftest.hcl file, create one mock_provider block per alias and give each an alias argument. Then, in each run block, map the module’s expected configurations to your mocks with a providers block:

# multi-region.tftest.hcl
mock_provider "aws" {
  alias = "primary"
}

mock_provider "aws" {
  alias = "replica"
}

run "both_buckets_are_planned" {
  command = plan

  providers = {
    aws.primary = aws.primary
    aws.replica = aws.replica
  }

  variables {
    bucket_name = "example-data"
  }

  assert {
    condition     = aws_s3_bucket.replica.bucket == "example-data-replica"
    error_message = "Replica bucket name was not derived correctly"
  }
}

The providers map is the load-bearing part. On the left is the address the module expects (aws.primary); on the right is the mock you defined in the test file (aws.primary). Without this mapping, Terraform cannot satisfy the module’s configuration_aliases and the run errors out before any assertion runs.

Mixing a Default and Aliased Providers

If your module uses a default aws provider and an aliased one, declare all of them and map only the aliased ones (the default binds automatically):

mock_provider "aws" {}            # default

mock_provider "aws" {
  alias = "replica"
}

run "default_and_replica" {
  command = plan

  providers = {
    aws         = aws
    aws.replica = aws.replica
  }
}

You can also pin values per alias with override_resource/override_data inside the relevant mock_provider block, exactly as with a single provider — each mocked alias is independent.

Step-by-Step Resolution

1. In the module, declare every non-default configuration in configuration_aliases = [aws.primary, aws.replica] inside required_providers.
2. Confirm each resource sets provider = aws.<alias> so it binds to a declared configuration.
3. In the test file, add one mock_provider "aws" block per alias, each with a matching alias = "..." argument.
4. In every run block, add a providers = { ... } map linking the module’s expected addresses to your test mocks.
5. Add variables and assert blocks as usual; use command = plan for logic checks.
6. Run terraform test and verify the run passes rather than erroring on a missing provider configuration.

Gotchas

• The providers map is mandatory for aliases. Auto-binding only covers the default provider; every aliased configuration must be mapped explicitly in the run block, or the run fails with a missing-configuration error.
• configuration_aliases removes the default provider. If you declare only aliases, there is no unaliased aws, so a resource without a provider argument will error. Add a default mock only if the module actually uses one.
• Alias names must match on both sides. The alias in mock_provider and the address in the providers map have to line up with what the module declares, or Terraform reports an unconfigured alias.
• You can mix mock and real per alias. Use mock_provider "aws" { alias = "primary" } for one and a real provider "aws" { alias = "replica" region = "us-west-2" } for another when you want one live integration path.
• Provider blocks in tests go at file scope. Define mock_provider/provider at the top level of the .tftest.hcl file, not inside run blocks; only the providers mapping lives in run.

Generating the provider wiring by hand across many modules is tedious — the DevOps AI prompt library at /prompts/?stack=terraform can emit the configuration_aliases, mock_provider, and providers map from a short description of your regions.

Frequently Asked Questions

How do I mock an aliased provider in Terraform tests? Add a mock_provider "aws" block with a matching alias argument for each alias, then map them in each run block with a providers = { aws.primary = aws.primary } block.

Where do configuration_aliases go in a module? Inside required_providers, as configuration_aliases = [aws.primary, aws.replica] on the provider requirement — not in a separate provider block.

Why does terraform test error about a missing provider configuration? The module declares aliased configurations via configuration_aliases, and your run block did not map them. Add a providers block linking each expected alias to a mock.

Can I mix a mocked and a real provider across aliases? Yes. Define mock_provider for the aliases you want faked and a real provider block for the ones you want live; map each in the run block’s providers argument.

Does declaring configuration_aliases remove the default provider? Yes. If you only declare aliases, there is no default aws, so every resource must set provider = aws.<alias>. For more patterns, see the Terraform guides.