Mocking Providers in Tests

You want every pull request to prove that the module still wires itself correctly — variables flow, conditions pick the right branch, outputs reference the right resources — without handing every developer AWS credentials and without paying for a plan against a real account. The mock_provider block makes that possible inside the native test framework you met in The Native terraform test Framework.

# tests/wiring.tftest.hcl
mock_provider "aws" {
  mock_data "aws_caller_identity" {
    defaults = {
      account_id = "123456789012"
      arn        = "arn:aws:iam::123456789012:root"
    }
  }

  mock_resource "aws_s3_bucket" {
    defaults = {
      arn    = "arn:aws:s3:::mock-bucket"
      region = "us-east-1"
    }
  }
}

run "plan_without_credentials" {
  command = plan
}

Run it with terraform test. The mock provider intercepts every call to the aws provider type: data sources return the fabricated values you listed, and resources get plausible computed values for everything else — Terraform generates random strings for identifiers like id and arn unless you pin them, and derives values it can compute from the configuration itself. No AWS_ACCESS_KEY_ID in the environment, no network round-trips, no per-run cost. A CI job that runs this needs only a Terraform binary.

What the mocked plan still exercises is the part unit tests are for: the module's own logic. The resource graph is built, count and for_each expressions evaluate, locals compute, variable validation runs, and every reference between resources resolves. If someone changes a local that feeds the bucket name, the mocked plan reflects it. If someone deletes the output the downstream module depends on, the test fails. That is exactly the class of bug that used to require a real terraform plan against a sandbox account to catch.

The mechanics mirror real provider resolution. A mock_provider "aws" block acts as the default provider for every aws_-prefixed resource and data source in the configuration under test, so a module that declares no provider block needs no changes at all. Modules called by the root inherit the same standing-in, which is what makes whole-module test runs possible:

run "module_level_plan" {
  command = plan

  module {
    source = "../modules/sites"
  }

  variables {
    environment = "prod"
  }
}

The module argument points the run at a child module directly — you test the module's interface rather than the example that wraps it, which is the right granularity for a shared module whose callers you do not control.

Version support is the one operational prerequisite: mock_provider arrived in Terraform 1.7, and override_resource and the rest of the family in the same release, so a 1.6 CI image rejects the test file with an "Unsupported block type" error that has nothing to do with your configuration. Pin the test image accordingly.

Everything a mock generates stays schema-shaped: string attributes get plausible random strings, lists get empty lists, booleans get values, and every generated attribute is marked known so downstream expressions and assertions can evaluate. That known-ness is deliberate — it is what lets a mocked plan finish the whole graph where a real plan would stop at (known after apply).

One boundary to internalize before writing assertions: a mock verifies wiring, not the cloud. It has the provider's schema, so a typo in an attribute name still errors, but it enforces none of AWS's rules — bucket naming, policy syntax, AMI existence, IAM permissions. A mocked test passes for configuration that a real apply would reject. Keeping that line sharp is what lets you trust the fast suite and schedule the slow one, and the trade-off gets a full treatment in the last chapter of this topic.

Under a bare mock, computed attributes Terraform generates are random per run. That is fine for an id nobody reads, and disastrous for an assertion:

# flaky: the mocked arn is a random string that changes every run
assert {
  condition     = aws_s3_bucket.logs.arn == "arn:aws:s3:::acme-logs-prod"
  error_message = "bucket ARN does not follow the naming standard"
}

There are two sanctioned ways to make such values deterministic, and they differ in scope.

Defaults inside the mock block apply everywhere the mock is used in the test file. You saw them on mock_data and mock_resource in the previous chapter; they are the right tool when every run wants the same fabricated provider output — a fixed account ID, a fixed region.

Override blocks inside a run block target one resource or data source for that run only, and accept partial attribute sets:

run "policy_references_log_bucket" {
  command = plan

  override_data {
    target = data.aws_caller_identity.current
    values = { account_id = "123456789012" }
  }

  override_resource {
    target = aws_s3_bucket.logs
    values = { arn = "arn:aws:s3:::acme-logs-prod" }
  }

  assert {
    condition     = strcontains(aws_s3_bucket_policy.logs.policy, "arn:aws:s3:::acme-logs-prod/*")
    error_message = "bucket policy must scope object access to the log bucket"
  }
}

Now the assertion reads a value the test itself declared, so the test fails only when the policy wiring changes, never because a random generator rolled differently. Note the constraint that trips people: override_resource's target must be a whole resource or data source address, not an individual instance of a count or for_each resource, and every key in values must be a real attribute of that type — a misspelled attribute is an immediate error, which is the schema check you get for free.

Overrides also solve the data-source trap. Reading an account ID through data.aws_caller_identity normally needs credentials; overridden, the data source returns your fabricated account during the plan and the module's real lookup code still runs against it. That combination — real module code, fabricated provider answers — is the definition of a stub: the test controls the boundary, the configuration under test does not know.

Discipline keeps mocks honest:

The finished pattern — plan-only, mocked, pinned, asserted — is what belongs in the pull-request gate. It runs in seconds, needs no secrets, and answers one question honestly: did the configuration still compile itself into the infrastructure we described? The next chapter turns those asserts into a systematic vocabulary, and Plan Assertions and Expectations extends the same run blocks with expect_failures for guardrail tests.

Precedence is the last mechanical detail: when a run-level override_resource and a file-level mock_resource default both set the same attribute, the run's override wins — per-scenario data beats ambient context. That gives a clean layering: stable world facts (account ID, region) live in the mock block, scenario-specific values (the ARN an assertion names) live in the run. And when a values map contains an attribute the provider schema does not have, Terraform fails immediately with a message naming the real attributes, so typos in tests are caught by the same schema validation that protects configuration.

A mocked suite goes green while the real apply dies, and the first time should sting — that pain is the lesson. Walk through what a mock is structurally incapable of detecting, and the test pyramid writes itself.

Provider API rules are invisible. The mock knows the schema — attribute names and types — but none of AWS's acceptance rules. These all pass a mocked plan and fail a real apply:

aws_s3_bucket_name "logs": bucket "Acme_Logs" is invalid;
  bucket names must not contain uppercase letters
aws_iam_role_policy "app": MalformedPolicyDocument: invalid JSON
  in the assume-role policy
aws_instance "web": InvalidAMIID.NotFound: ami-0deadbeef is gone

A mocked suite also cannot notice that an AMI was deregistered last week, that an instance type is unavailable in the chosen zone, or that the execution role lacks s3:CreateBucket. Those are cloud facts, and mocks by design never talk to the cloud.

Apply-time behavior does not exist in plan-only runs. Even with a real provider, command = plan never calls Create, so hangs, eventual-consistency failures, and quota errors stay hidden. Mocking compounds this: your command = apply run against a mock_provider fabricates the post-create state too, so it validates your assertions, not reality.

Random generated values can mask regressions. Because unmocked computed attributes are random per run, an assertion you meant to write against a pinned value may pass against noise for weeks. Audit occasionally: every assert should read either a configuration-derived value or something the test pinned explicitly.

So where does that leave the real cloud? Not abandoned — scheduled. The standard layering:

The middle row surprises people: without any mock_provider block, the very same .tftest.hcl file runs against the real provider, so one file can serve both lanes with different credentials. The bottom row — Go-based tests that apply, probe the live system, and destroy — is Terratest Harness in Go, where retry loops handle the eventual consistency that plan-only runs never see.

In an interview, the strong answer to "how do you test Terraform?" is not "Terratest" or "mocks" — it is the pairing: mocked plan tests as the fast feedback loop, real apply tests as the slow truth check, each owning what the other structurally cannot see. Candidates who name the failure modes above — invalid bucket names, missing AMIs, stale data — demonstrate they have watched a green suite fail in production and built the system that keeps it honest.

One more fidelity detail deserves a name: mocks are frozen against the provider version their schema came from. When AWS adds a required attribute or changes a computed one, a mocked suite can keep passing on the old schema while the real provider rejects the configuration — so the mocked lane's green checkmarks need the scheduled real lane beside them as a drift alarm, not merely a backstop. Teams that learn this the hard way usually discover it as a merge-day surprise: three weeks of green mocked plans, then a nightly run fails on a deprecation the mock never modeled.