en-US/about_PSRule_Assert.help.txt
|
TOPIC
about_psrule_assert SHORT DESCRIPTION Describes the assertion helper that can be used within PSRule rule definitions. LONG DESCRIPTION PSRule includes an assertion helper exposed as a built-in variable `$Assert`. The `$Assert` object provides a consistent set of methods to evaluate objects. Each `$Assert` method returns an `AssertResult` object that contains the result of the assertion. The following built-in assertion methods are provided: - Contains - The field value must contain at least one of the strings. - EndsWith - The field value must match at least one suffix. - Greater - The field value must be greater. - GreaterOrEqual - The field value must be greater or equal to. - HasDefaultValue - The object should not have the field or the field value is set to the default value. - HasField - The object must have the specified field. - HasFieldValue - The object must have the specified field and that field is not empty. - HasJsonSchema - The object must reference a JSON schema with the `$schema` field. - In - The field value must be included in the set. - JsonSchema - The object must validate successfully against a JSON schema. - Less - The field value must be less. - LessOrEqual - The field value must be less or equal to. - Match - The field value matches a regular expression pattern. - NotIn - The field value must not be included in the set. - NotMatch - The field value does not match a regular expression pattern. - NullOrEmpty - The object must not have the specified field or it must be empty. - StartsWith - The field value must match at least one prefix. - Version - The field value must be a semantic version string. The `$Assert` variable can only be used within a rule definition block or script pre-conditions. USING ASSERTION METHODS An assertion method can be used like other methods in PowerShell. i.e. `$Assert.methodName(parameters)`. Assertion methods use the following standard pattern: - The first parameter is always the input object of type `PSObject`, additional parameters can be included based on the functionality required by the method. - In many cases the input object will be `$TargetObject`, however assertion methods must not assume that `$TargetObject` will be used. - Assertion methods must accept a `$Null` input object. - Assertion methods return the `AssertResult` object that is interpreted by the rule pipeline. Some assertion methods may overlap or provide similar functionality to built-in keywords. Where you have the choice, use built-in keywords. Use assertion methods for advanced cases or increased flexibility. In the following example, `Assert.HasFieldValue` asserts that `$TargetObject` should have a field named `Type` with a non-empty value. Rule 'Assert.HasTypeField' { $Assert.HasFieldValue($TargetObject, 'Type') } To find perform multiple assertions use. Rule 'Assert.HasRequiredFields' { $Assert.HasFieldValue($TargetObject, 'Name') $Assert.HasFieldValue($TargetObject, 'Type') $Assert.HasFieldValue($TargetObject, 'Value') } FIELD NAMES Many of the built-in assertion methods accept a field name. The field name is an expression that traverses object properties, keys or indexes of the input object . The field name can contain: - Property names for PSObjects or .NET objects. - Keys for hash table or dictionaries. - Indexes for arrays or collections. For example: - `.` refers to input object itself. - `Name` or `.Name` refers to the name property/ key of the input object . - `Properties.enabled` refers to the enabled property under the Properties property. - `Tags.env` refers to the env key under a hash table property of the input object . - `Properties.securityRules[0].name` references to the name property of the first security rule. CONTAINS The `Contains` assertion method checks the field value contains with the specified string. Optionally a case-sensitive compare can be used, however case is ignored by default. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `text` - One or more strings to compare the field value with. Only one string must match. - `caseSensitive` (optional) - Use a case sensitive compare of the field value. Case is ignored by default. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The field value '{0}' is not a string. - The field '{0}' does not contain '{1}'. Examples: Rule 'Contains' { $Assert.Contains($TargetObject, 'ResourceGroupName', 'prod') $Assert.Contains($TargetObject, 'Name', @('prod', 'test'), $True) } ENDSWITH The `EndsWith` assertion method checks the field value ends with the specified suffix. Optionally a case-sensitive compare can be used, however case is ignored by default. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `suffix` - One or more suffixes to compare the field value with. Only one suffix must match. - `caseSensitive` (optional) - Use a case sensitive compare of the field value. Case is ignored by default. - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The field value '{0}' is not a string. - The field '{0}' does not end with '{1}'. Examples: Rule 'EndsWith' { $Assert.EndsWith($TargetObject, 'ResourceGroupName', 'eus') $Assert.EndsWith($TargetObject, 'Name', @('db', 'web'), $True) } GREATER The `Greater` assertion method checks the field value is greater than the specified value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `value` - A integer to compare the field value against. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The value '{0}' was not > '{1}'. - The field value '{0}' can not be compared with '{1}'. Examples: Rule 'Greater' { $Assert.Greater($TargetObject, 'value', 3) } GREATEROREQUAL The `GreaterOrEqual` assertion method checks the field value is greater or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `value` - A integer to compare the field value against. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The value '{0}' was not >= '{1}'. - The field value '{0}' can not be compared with '{1}'. Examples: Rule 'GreaterOrEqual' { $Assert.GreaterOrEqual($TargetObject, 'value', 3) } HASDEFAULTVALUE The `HasDefaultValue` assertion method check that the field does not exist or the field value is set to the default value. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `defaultValue` - The expected value if the field exists. This assertion will pass if: - The field does not exist. - The field value is set to `defaultValue`. This assertion will fail if: - The field value is set to a value different from `defaultValue`. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' is set to '{1}'. Examples: Rule 'HasDefaultValue' { $Assert.HasDefaultValue($TargetObject, 'Properties.osProfile.linuxConfiguration.provisionVMAgent', $True) } HASFIELD The `HasField` assertion method checks the object has the specified field. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. By default, a case insensitive compare is used. - `caseSensitive` (optional) - Use a case sensitive compare of the field name. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. Examples: Rule 'HasField' { $Assert.HasField($TargetObject, 'Name') $Assert.HasField($TargetObject, 'tag.Environment', $True) } HASFIELDVALUE The `HasFieldValue` assertion method checks the field value of the object is not empty. A field value is empty if any of the following are true: - The field does not exist. - The field value is `$Null`. - The field value is an empty array or collection. - The field value is an empty string `''`. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `expectedValue` (optional) - Check that the field value is set to a specific value. To check `$Null` use `NullOrEmpty` instead. If `expectedValue` is `$Null` the field value will not be compared. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The value of '{0}' is null or empty. - The field '{0}' is set to '{1}'. Examples: Rule 'HasFieldValue' { $Assert.HasFieldValue($TargetObject, 'Name') $Assert.HasFieldValue($TargetObject, 'tag.Environment', 'production') } HASJSONSCHEMA The `HasJsonSchema` assertion method determines if the input object has a `$schema` property defined. If the `$schema` property is defined, it must match one of the supplied schemas. The following parameters are accepted: - `inputObject` - The object being compared. - `uri` - Optional. When specified, the object being compared must have a `$schema` property set to one of the specified schemas. Reasons include: - The parameter 'inputObject' is null. - The field '$schema' does not exist. - The field value '$schema' is not a string. - None of the specified schemas match '{0}'. Examples: Rule 'HasFieldValue' { $Assert.HasJsonSchema($TargetObject) $Assert.HasJsonSchema($TargetObject, "http://json-schema.org/draft-07/schema`#") } JSONSCHEMA The `JsonSchema` assertion method compares the input object against a defined JSON schema. The following parameters are accepted: - `inputObject` - The object being compared against the JSON schema. - `uri` - A URL or file path to a JSON schema file formatted as UTF-8. Either a file path or URL can be used to specify the location of the schema file. Reasons include: - The parameter 'inputObject' is null. - The parameter 'uri' is null or empty. - The JSON schema '{0}' could not be found. - Failed schema validation on {0}. {1} Examples: Rule 'JsonSchema' { $Assert.JsonSchema($TargetObject, 'tests/PSRule.Tests/FromFile.Json.schema.json') } IN The `In` assertion method checks the field value is included in a set of values. The field value can either be an integer, float, array, or string. When the field value is an array, only one item must be included in the set. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `values` - An array of one or more values that the field value is compared against. - `caseSensitive` (optional) - Use a case sensitive compare of the field value. Case is ignored by default. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The field value '{0}' was not included in the set. Examples: Rule 'In' { $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard')) $Assert.In($TargetObject, 'Sku.tier', @('PremiumV2', 'Premium', 'Standard'), $True) } LESS The `Less` assertion method checks the field value is less than the specified value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `value` - A integer to compare the field value against. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The value '{0}' was not < '{1}'. - The field value '{0}' can not be compared with '{1}'. Examples: Rule 'Less' { $Assert.Less($TargetObject, 'value', 3) } LESSOREQUAL The `LessOrEqual` assertion method checks the field value is less or equal to the specified value. The field value can either be an integer, float, array, or string. When the field value is: - An integer or float, a numerical comparison is used. - An array, the number of elements is compared. - A string, the length of the string is compared. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `value` - A integer to compare the field value against. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The value '{0}' was not <= '{1}'. - The field value '{0}' can not be compared with '{1}'. Examples: Rule 'LessOrEqual' { $Assert.LessOrEqual($TargetObject, 'value', 3) } MATCH The `Match` assertion method checks the field value matches a regular expression pattern. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `pattern` - A regular expression pattern to match. - `caseSensitive` (optional) - Use a case sensitive compare of the field value. Case is ignored by default. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The field value '{0}' is not a string. - The field value '{0}' does not match the pattern '{1}'. Examples: Rule 'Match' { $Assert.Match($TargetObject, 'value', '^[a-z]*$') $Assert.Match($TargetObject, 'value', '^[a-z]*$', $True) } NOTIN The `NotIn` assertion method checks the field value is not in a set of values. The field value can either be an integer, array, float, or string. When the field value is an array, none of the items must be included in the set. If the field does not exist at all, it is not in the set and passes. To check the field exists combine this assertion method with `HasFieldValue`. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `values` - An array of one or more values that the field value is compared against. - `caseSensitive` (optional) - Use a case sensitive compare of the field value. Case is ignored by default. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field value '{0}' was in the set. Examples: Rule 'In' { $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic')) $Assert.NotIn($TargetObject, 'Sku.tier', @('Free', 'Shared', 'Basic'), $True) } NOTMATCH The `NotMatch` assertion method checks the field value does not match a regular expression pattern. If the field does not exist at all, it does not match and passes. To check the field exists combine this assertion method with `HasFieldValue`. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `pattern` - A regular expression pattern to match. - `caseSensitive` (optional) - Use a case sensitive compare of the field value. Case is ignored by default. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field value '{0}' is not a string. - The field value '{0}' matches the pattern '{1}'. Examples: Rule 'NotMatch' { $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$') $Assert.NotMatch($TargetObject, 'value', '^[a-z]*$', $True) } NULLOREMPTY The `NullOrEmpty` assertion method checks the field value of the object is null or empty. A field value is null or empty if any of the following are true: - The field does not exist. - The field value is `$Null`. - The field value is an empty array or collection. - The field value is an empty string `''`. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' is not empty. Examples: Rule 'NullOrEmpty' { $Assert.NullOrEmpty($TargetObject, 'Name') $Assert.NullOrEmpty($TargetObject, 'tag.Environment') } STARTSWITH The `StartsWith` assertion method checks the field value starts with the specified prefix. Optionally a case-sensitive compare can be used, however case is ignored by default. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `prefix` - One or more prefixes to compare the field value with. Only one prefix must match. - `caseSensitive` (optional) - Use a case sensitive compare of the field value. Case is ignored by default. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The field value '{0}' is not a string. - The field '{0}' does not start with '{1}'. Examples: Rule 'StartsWith' { $Assert.StartsWith($TargetObject, 'ResourceGroupName', 'rg-') $Assert.StartsWith($TargetObject, 'Name', @('st', 'diag'), $True) } VERSION The `Version` assertion method checks the field value is a valid semantic version. A constraint can optionally be provided to require the semantic version to be within a range. The following parameters are accepted: - `inputObject` - The object being checked for the specified field. - `field` - The name of the field to check. This is a case insensitive compare. - `constraint` (optional) - A version constraint, see below for details of version constrain format. The following are supported constraints: - `version` - Must match version exactly. This also accepts the following prefixes; `=`, `v`, `V`. - e.g. `1.2.3`, `=1.2.3` - `>version` - Must be greater than version. - e.g. `>1.2.3` - `>=version` - Must be greater than or equal to version. - e.g. `>=1.2.3` - `<version` - Must be less than version. - e.g. `<1.2.3` - `<=version` - Must be less than or equal to version. - e.g. `<=1.2.3` - `^version` - Compatible with version. - e.g. `^1.2.3` - >=1.2.3, <2.0.0 - `~version` - Approximately equivalent to version - e.g. `~1.2.3` - >=1.2.3, <1.3.0 An empty, null or `*` version constraint matches all valid semantic versions. Reasons include: - The parameter 'inputObject' is null. - The parameter 'field' is null or empty. - The field '{0}' does not exist. - The field value '{0}' is not a version string. - The version '{0}' does not match the constraint '{1}'. Examples: Rule 'ValidVersion' { $Assert.Version($TargetObject, 'version') } Rule 'MinimumVersion' { $Assert.Version($TargetObject, 'version', '>=1.2.3') } ADVANCED USAGE The `AssertResult` object returned from assertion methods: - Handles pass/ fail conditions and collection of reason information. - Allows rules to implement their own handling or forward it up the stack to affect the rule outcome. The following properties are available: - `Result` - Either `$True` (Pass) or `$False` (Fail). The following methods are available: - `AddReason(<string> text)` - Can be used to append additional reasons to the result. A reason can only be set if the assertion failed. Reason text should be localized before calling this method. Localization can be done using the `$LocalizedData` automatic variable. - `WithReason(<string> text, <bool> replace)` - Can be used to append or replace reasons on the result. In addition, `WithReason` can be chained. - `Reason(<string> text, params <object[]> args)` - Replaces the reason on the results with a formatted string. This method can be chained. For usage see examples below. - `GetReason()` - Gets any reasons currently associated with the failed result. - `Complete()` - Returns `$True` (Pass) or `$False` (Fail) to the rule record. If the assertion failed, any reasons are automatically added to the rule record. To read the result without adding reason to the rule record use the `Result` property. - `Ignore()` - Ignores the result. Nothing future is returned and any reasons are cleared. Use this method when implementing custom handling. Use of `Complete` is optional, uncompleted results are automatically completed after the rule has executed. Uncompleted results may return reasons out of sequence. Using these advanced methods is not supported in rule script pre-conditions. In this example, `Complete` is used to find the first field with an empty value. Rule 'Assert.HasFieldValue' { $Assert.HasFieldValue($TargetObject, 'Name').Complete() -and $Assert.HasFieldValue($TargetObject, 'Type').Complete() -and $Assert.HasFieldValue($TargetObject, 'Value').Complete() } In this example, the built-in reason is replaced with a custom reason, and immediately returned. The reason text is automatically formatted with any parameters provided. Rule 'Assert.HasCustomValue' { $Assert. HasDefaultValue($TargetObject, 'value', 'test'). Reason('The field {0} is using a non-default value: {1}', 'value', $TargetObject.value) # With localized string $Assert. HasDefaultValue($TargetObject, 'value', 'test'). Reason($LocalizedData.NonDefaultValue, 'value', $TargetObject.value) } AUTHORING ASSERTION METHODS The following built-in helper methods are provided for working with `$Assert` when authoring new assertion methods: - `Create(<bool> condition, <string> reason)` - Returns a result either pass or fail assertion result. - `Pass()` - Returns a pass assertion result. - `Fail()` - Results a fail assertion result. - `Fail(<string> reason, params <object[]> args)` - Results a fail assertion result with a custom reason. Additional arguments can be provided to format the custom reason string. NOTE An online version of this document is available at https://github.com/Microsoft/PSRule/blob/main/docs/concepts/PSRule/en-US/about_PSRule_Assert.md. SEE ALSO - about_PSRule_Variables KEYWORDS - Assert - Contains - EndsWith - Greater - GreaterOrEqual - HasDefaultValue - HasField - HasFieldValue - JsonSchema - Less - LessOrEqual - NullOrEmpty - StartsWith - Version - Rule |