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. - 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. - 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 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') } 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 or an array. When the field value is: - An integer, 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 or an array. When the field value is: - An integer, 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') } LESS The `Less` assertion method checks the field value is less than the specified value. The field value can either be an integer or an array. When the field value is: - An integer, 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 or an array. When the field value is: - An integer, 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) } 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. - `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() } The this example, the built-in reason is replaced with a custom reason, and immediately returned. Rule 'Assert.HasCustomValue' { $Assert. HasDefaultValue($TargetObject, 'value', 'test'). WithReason('Value is set to custom value', $True) } 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(<string> reason)` - Results a fail assertion result. NOTE An online version of this document is available at https://github.com/Microsoft/PSRule/blob/master/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 |