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
- 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"

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"

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"

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

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\\..*

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

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\\..*

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"

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.*"

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']
}

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"

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.*"

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

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

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