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: - 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. - JsonSchema - The object must validate successfully against a JSON schema. - NullOrEmpty - The object must not have the specified field or it must be empty. The `$Assert` variable can only be used within a rule definition block. 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') } 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`. 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. 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. Examples: Rule 'HasFieldValue' { $Assert.HasFieldValue($TargetObject, 'Name') $Assert.HasFieldValue($TargetObject, 'tag.Environment', 'production') } 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. Examples: Rule 'JsonSchema' { $Assert.JsonSchema($TargetObject, 'tests/PSRule.Tests/FromFile.Json.schema.json') } 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. Examples: Rule 'NullOrEmpty' { $Assert.NullOrEmpty($TargetObject, 'Name') $Assert.NullOrEmpty($TargetObject, 'tag.Environment') } 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 add 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. - `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. 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() } 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 - HasDefaultValue - HasField - HasFieldValue - JsonSchema - NullOrEmpty - Rule |