module

To test a module policy, add a mock module block to your test file. Use the meta attribute to set meta-attributes, including the module source and version. Use the attrs block to set values for any input variables defined by the module.

Note

This functionality is in beta. Do not use beta features in production environments.

Configuration model

The module block supports the following configuration:

module "<module_source>" "<test_label>" block
- attrs object | optional
  - <attr_name> any | repeatable
- expect_failure boolean | optional
- inputs block | optional
  - <input_name> any | repeatable
- meta object | optional
  - address string
  - source string
  - version string

Complete configuration example

The following example demonstrates a module block with all configuration options specified:

tests/example.policytest.hcl

module "app.terraform.io/my-org/vpc/aws" "all_options" {
  expect_failure = true

  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = "1.5.0"
    address = "module.vpc"
  }

  attrs = {
    name = "example-vpc"
    cidr = "10.0.0.0/16"
    azs  = ["us-east-1a", "us-east-1b"]
  }

  inputs {
    min_module_version = "2.0.0"
  }
}

Specification

A module block supports the following configuration.

Module source

Specifies a URI where Terraform policy retrieves the module from, for example"app.terraform.io/my-org/vpc/aws" or "./modules/networking".

Test label

A unique name for this test case within the test file.

`attrs`

Module input variables as defined by the module. Refer to the module documentation for available input variables.

Data type: Object
Default: None

`expect_failure`

Set to true to expect this mock to fail the matching policies.

Data type: Boolean
Default: false

`inputs`

Set policy input values specific to this test case.

Data type: Block
Default: None

`meta`

Meta-attributes for the module, including source, version, and address.

Data type: Object
Default: None

You can set the following meta values in the meta argument.

Attribute	Type	Description
`source`	String	The module source (For example: `"app.terraform.io/my-org/vpc/aws"`).
`version`	String	The module version (For example: `"2.0.0"`).
`address`	String	The logical address of the module within the configuration.

Examples

The following examples demonstrate common mock module configuration patterns for specific use cases.

Test module version requirements

In the following example, the mock module blocks test a policy that enforces minimum module versions. One of the blocks mocks the current version and the second block mocks an outdated version.

module "app.terraform.io/my-org/vpc/aws" "current_version" {
  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = "2.0.0"
  }

  attrs = {
    name = "production-vpc"
    cidr = "10.0.0.0/16"
  }
}

module "app.terraform.io/my-org/vpc/aws" "outdated_version" {
  expect_failure = true
  
  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = "1.0.0"
  }

  attrs = {
    name = "production-vpc"
    cidr = "10.0.0.0/16"
  }
}

Test approved module sources

In the following example, mock module blocks test a policy that validates module sources. One of the blocks mocks an approved source and the second block mocks an unapproved source.

module "git::github.com/org/terraform-aws-vpc" "approved_source" {
  meta = {
    source  = "git::github.com/org/terraform-aws-vpc"
    version = "2.0.0"
  }

  attrs = {
    vpc_name = "main"
    cidr     = "10.0.0.0/16"
  }
}

module "git::github.com/unknown/terraform-aws-vpc" "unapproved_source" {
  expect_failure = true
  
  meta = {
    source  = "git::github.com/unknown/terraform-aws-vpc"
    version = "2.0.0"
  }

  attrs = {
    vpc_name = "main"
    cidr     = "10.0.0.0/16"
  }
}

Test local modules

In the following example, the mock module block tests a policy for a locally-sourced module.

module "./modules/networking" "local_module" {
  meta = {
    source  = "./modules/networking"
    version = "1.0.0"
  }

  attrs = {
    environment = "production"
    vpc_cidr    = "10.0.0.0/16"
  }
}

Test with input variables

In the following example, mock module blocks test a policy that uses input variables, with one test case overriding the input value.

The policy file under test declares the input:

input "min_module_version" {
  type    = string
  default = "2.0.0"
}

The policy test file mocks two modules:

module "app.terraform.io/my-org/vpc/aws" "configurable" {
  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = input.min_module_version
  }

  attrs = {
    name = "vpc"
    cidr = "10.0.0.0/16"
  }
}

module "app.terraform.io/my-org/vpc/aws" "override_version" {
  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = "3.0.0"
  }

  attrs = {
    name = "vpc"
    cidr = "10.0.0.0/16"
  }
  
  inputs {
    min_module_version = "3.0.0"
  }
}

Test module with complex inputs

In the following example, the mock module block tests a VPC module with a comprehensive set of input attributes including subnets and feature flags.

module "app.terraform.io/my-org/vpc/aws" "full_config" {
  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = "2.0.0"
  }

  attrs = {
    name = "production-vpc"
    cidr = "10.0.0.0/16"

    azs             = ["us-east-1a", "us-east-1b", "us-east-1c"]
    private_subnets = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
    public_subnets  = ["10.0.101.0/24", "10.0.102.0/24", "10.0.103.0/24"]

    enable_nat_gateway = true
    enable_vpn_gateway = false

    tags = {
      Environment = "production"
      ManagedBy   = "terraform"
    }
  }
}

Test multiple module instances

In the following example, mock module blocks test the same VPC module used in multiple environments with different configurations.

module "app.terraform.io/my-org/vpc/aws" "production" {
  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = "2.0.0"
    address = "module.production_vpc"
  }

  attrs = {
    name = "production-vpc"
    cidr = "10.0.0.0/16"
  }
}

module "app.terraform.io/my-org/vpc/aws" "staging" {
  meta = {
    source  = "app.terraform.io/my-org/vpc/aws"
    version = "2.0.0"
    address = "module.staging_vpc"
  }

  attrs = {
    name = "staging-vpc"
    cidr = "10.1.0.0/16"
  }
}

Test version constraints

In the following example, mock module blocks test a policy that enforces version constraints across different module versions. Two of the mocks are designed to pass and a third is designed to fail.

module "app.terraform.io/my-org/security-group/aws" "v2_x" {
  meta = {
    source  = "app.terraform.io/my-org/security-group/aws"
    version = "2.5.0"
  }

  attrs = {
    name        = "web-sg"
    description = "Security group for web servers"
  }
}

module "app.terraform.io/my-org/security-group/aws" "v3_x" {
  meta = {
    source  = "app.terraform.io/my-org/security-group/aws"
    version = "3.0.0"
  }

  attrs = {
    name        = "web-sg"
    description = "Security group for web servers"
  }
}

module "app.terraform.io/my-org/security-group/aws" "too_old" {
  expect_failure = true
  
  meta = {
    source  = "app.terraform.io/my-org/security-group/aws"
    version = "1.9.0"
  }

  attrs = {
    name        = "web-sg"
    description = "Security group for web servers"
  }
}