WHEN

WHEN used to define the condition that you are searching for. It could be either a filtering condition or you might be looking for a specific property on a resource, or any property on any entity that has been transferred via GIVEN directive. WHEN must come after GIVEN directive.

WHEN steps does not fail any scenario. It sets the condition for the further steps.

WHEN can be used multiple times, either with using WHEN or AND

Few examples can be ;

When I count them
When its name is my-bucket
When it contains server_side_encryption

Using WHEN is optional. You might have some use cases that only a GIVEN and some THEN directives could be enough for you.

You can use AND with WHEN.

Depending on use a Scenario Outline instead of a Scenario, it can also be a variable like ;

When it contains <some_property>

In case a WHEN step fails to complete, then the step and further steps will be SKIPPED. Skipped steps won’t fail terraform-compliance. It means the definition criteria (not the testing criteria) defined in your Scenario does not met with the infrastructure plan.

Reference

When it contains something

will be deprecated soon

This step filters and drills down at the same time, unlike other WHEN steps. Please use When it has something followed by Then it must have something to achieve a similar functionality.

Possible sentences :

When it contain something

When it contains something

key Description Examples
something any property within Terraform resource/provider/etc access_key ingress "something with spaces"

When it has something

1.2.+

This is a filtering function where the resources from previous step will be filtered based on the “something” key exist in the resource properties.

Possible sentences :

When it has something

When they have something

key Description Examples
something any property within Terraform resource/provider/etc access_key ingress "something with spaces"

When it does not have something

1.2.+

This is a filtering function where the resources from previous step will be filtered based on the “something” key not existing in the resource properties.

Possible sentences :

When it does not contain something

When it doesnt contain something

When it does not have something

When it doesnt have something

When they do not have something

When they dont have something

key Description Examples
something any property within Terraform source/provider/etc access_key ingress "something with spaces"

When its property has something

This is a filtering function. Thus, found resources from previous step will be filtered based on these values.

Possible sentences :

When its property is something

When its property has something

When its property includes something

When its property contains something

When its property is “ some string with spaces

When its property has “ some string with spaces

When its property includes “ some string with spaces

When its property contains “ some string with spaces

When its dictionary includes an entry where “ key “ is “ value

key Description Examples
property any property that resources have. Using type will give the Terraform resource type; address is the name you have given it address name size
dictionary a dictionary property that resource has. tags
something any string or numeric value that the property has. s3_my_bucket my-bucket 50G "something with spaces"
some string with spaces any string (allows spaces). my dictionary key
key any dictionary key (allows spaces). my dictionary key
value any dictionary value (allows spaces). my dictionary value

When its property has “something” regex

This is a filtering function with regular expression support on values. Thus, found resources from previous step will be filtered based on these values.

Possible sentences :

When its property is “something” regex

When its property has “something” regex

When its property includes “something” regex

When its property contains “something” regex

When its dictionary includes an entry where “ key “ is is “value” regex

key Description Examples
property any property that resources have. Using type will give the Terraform resource type; address is the name you have given it address name size
dictionary a dictionary property that resource has. tags
something Any regular expression aws_s3_.*"
some string with spaces any string (allows spaces). my dictionary key
key any dictionary key (allows spaces). my dictionary key
value Any regular expression ^4\\..*

When its property has not something

This is a filtering function. Thus, found resources from previous step will be filtered based on these values.

Possible sentences :

When its property is not something

When its property has not something

When its property does not include something

When its property does not contain something

When its property is not “ some string with spaces

When its property has not “ some string with spaces

When its property does not include “ some string with spaces

When its property does not contain “ some string with spaces

When its dictionary does not include an entry where “ key “ is “ value

key Description Examples
property any property that resources have. Using type will give the Terraform resource type; address is the name you have given it address name size
dictionary a dictionary property that resource has. tags
something any string or numeric value that the property has. s3_my_bucket my-bucket 50G "something with spaces"
some string with spaces any string (allows spaces). my dictionary key
key any dictionary key (allows spaces). my dictionary key
value any dictionary value (allows spaces). my dictionary value

When its property has not “something” regex

This is a filtering function with regular expression support on values. Thus, found resources from previous step will be filtered based on these values.

Possible sentences :

When its property is not “something” regex

When its property has not “something” regex

When its property does not include “something” regex

When its property does not contain “something” regex

When its dictionary does not include an entry where “ key “ is is “value” regex

key Description Examples
property any property that resources have. Using type will give the Terraform resource type; address is the name you have given it address name size
dictionary a dictionary property that resource has. tags
something Any regular expression aws_s3_.*"
some string with spaces any string (allows spaces). my dictionary key
key any dictionary key (allows spaces). my dictionary key
value Any regular expression ^4\\..*

When its property metadata has something

This is a filtering function. Thus, found resources from previous step will be filtered based on these values.

This step checks if a property metadata has a specific value. Metadata are considered to be key, value pairs outside of values, which includes the properties of the resource.

Following is how an aws_instance example is represented in stash.

{'address': 'aws_instance.example',
 'mode': 'managed',
 'type': 'aws_instance',
 'name': 'example',
 'provider_name': 'registry.terraform.io/hashicorp/aws',
 'values': {
  'ami': 'ami-034bf895b736be04a',
  'arn': 'arn:aws:ec2:us-west-1:704778554736:instance/i-0d6a689453a806e50',
  'tags': {'Name': 'HelloWorldChange'},
  ...
  },
 'actions': ['update']
}

actions, provider_name, or address are considered to be metadata. However ami, arn, and tags are considered to be otherwise, as they are in values. The debugger could be used to see the metadata present at a given step.

Possible sentences :

When its property metadata is something

When its property metadata has something

When its property metadata includes something

When its property metadata contains something

key Description Examples
property any metadata that resources have. Using actions will give the Terraform’s actions on the resource on an apply; address is the name you have given it address name actions
something any string or numeric value that the property has. s3_my_bucket my-bucket create "something with spaces"

When its property metadata has “something” regex

This step has the same functionality with When its property metadata has something step. Additionaly this step supports regular expressions for matching values.

Possible sentences :

When its property metadata is “ something” regex

When its property metadata has “ something” regex

When its property metadata includes “ something” regex

When its property metadata contains “” something” regex

key Description Examples
property any metadata that resources have. Using actions will give the Terraform’s actions on the resource on an apply; address is the name you have given it address name actions
regex any regular expression with special characters escaped "module.project1.*"

When its property metadata has not something

This is a filtering function. Thus, found resources from previous step will be filtered based on these values.

This step filters a resource out if it has property metadata that has something value. Metadata are considered to be key, value pairs outside of values, which includes the properties of the resource.

Following is how an aws_instance example is represented in stash.

{'address': 'aws_instance.example',
 'mode': 'managed',
 'type': 'aws_instance',
 'name': 'example',
 'provider_name': 'registry.terraform.io/hashicorp/aws',
 'values': {
  'ami': 'ami-034bf895b736be04a',
  'arn': 'arn:aws:ec2:us-west-1:704778554736:instance/i-0d6a689453a806e50',
  'tags': {'Name': 'HelloWorldChange'},
  ...
  },
 'actions': ['update']
}

actions, provider_name, or address are considered to be metadata. However ami, arn, and tags are considered to be otherwise, as they are in values. The debugger could be used to see the metadata present at a given step.

Possible sentences :

When its property metadata is not something

When its property metadata has not something

When its property metadata does not have something

When its property metadata does not include something

When its property metadata does not contain something

key Description Examples
property any metadata that resources have. Using actions will give the Terraform’s actions on the resource on an apply; address is the name you have given it address name actions
something any string or numeric value that the property has. s3_my_bucket my-bucket create "something with spaces"

When its property metadata has not “something” regex

This step has the same functionality with When its property metadata has not something step. Additionaly this step supports regular expressions for matching values.

Possible sentences :

When its property metadata is not “ something” regex

When its property metadata has not “ something” regex

When its property metadata does not have “ something” regex

When its property metadata does not include “ something” regex

When its property metadata does not contain “ something” regex

key Description Examples
property any metadata that resources have. Using actions will give the Terraform’s actions on the resource on an apply; address is the name you have given it address name actions
regular expression any regular expression with special characters escaped "module.project1.*"

When its property reference has something

This is a filtering function, specific for resource referencing. The resource references will be checked based on the property property defined within the step.

Possible sentences :

When its property reference is something

When its property reference has something

When its property reference includes something

When its property reference contains something

When its property reference is “ some string with spaces

When its property reference has “ some string with spaces

When its property reference includes “ some string with spaces

When its property reference contains “ some string with spaces

key Description Examples
property any property that is used for referencing another resource. security_group_id aws_instance "something with spaces"
something any string or numeric value that the property has. s3_my_bucket my-bucket 50G "something with spaces"
some string with spaces any string (allows spaces). my dictionary key

When its property reference has not something

This is a filtering function, specific for resource referencing. The resource references will be checked based on the property property defined within the step. This is the negative version (ref. not usage within the step) of the filtering step.

Possible sentences :

When its property reference is not something

When its property reference has not something

When its property reference does not include something

When its property reference does not contain something

When its property reference is not “ some string with spaces

When its property reference has not “ some string with spaces

When its property reference does not include “ some string with spaces

When its property reference does not contain “ some string with spaces

key Description Examples
property any property that is used for referencing another resource. security_group_id aws_instance "something with spaces"
something any string or numeric value that the property has. s3_my_bucket my-bucket 50G "something with spaces"
some string with spaces any string (allows spaces). my dictionary key

When I action them

This step is for mathematical operations. Currently it is only supported for count

Possible sentences :

When I action them

When I action it

When I action the value

key Description Examples
action mathematical operation currently only supports for count

terraform-compliance made with . Distributed by an MIT license.