Assert-That

Asserts that an object meets certain conditions and throws an exception when they aren't.

Syntax

Assert-That [-InputObject] <Object> -Contains <Object> [[-Message] <String>] [<CommonParameters>]
Assert-That [-InputObject] <Object> -DoesNotContain <Object> [[-Message] <String>] [<CommonParameters>]
Assert-That [-InputObject] <Object> -DoesNotThrowException [<CommonParameters>]
Assert-That [-InputObject] <Object> -Throws <Type> [-AndMessageMatches <String>] [[-Message] <String>] [<CommonParameters>]

Description

The Assert-That function checks that a given set of condiions are true and if they aren't, it throws a Blade.AssertionException.

Parameters

Name Type Description Required? Pipeline Input Default Value
InputObject Object

The object whose conditions you're checking.

true false
Contains Object

Asserts that InputObject contains a value. InputObject can be an array, list, hashtable, dictionary, collection or a single string. If InputObject is another type, it is first converted to a string before being searched.

If InputObject is an array or list, this function uses PowerShell's -contains operator to determine if it contains Contains, e.g. $InputObject -contains $Contains.

If InputObject is a dictionary, this function uses its Contains method to determine if it contains Contains, e.g. $InputObject.Contains($Contains).

If InputObject is a collection, this function enumerates through each item in the collection and uses PowerShell's -eq operator to determine if it matches/is equal to Contains e.g.

foreach( $item in $InputObject.GetEnumerator() )
{
    if( $item -eq $Contains )
    {
    }
}

In all other cases, InputObject and Contains are converted to strings and compared using the -like operator. Any wildcards in Contains are escaped and it is wrapped in the * wildcard, e.g. $InputObject -like ('*{0}*' -f [Management.Automation.WildcardPattern]::Escape($Contains)).

true false
DoesNotContain Object

Asserts that InputObject does not contain a value. InputObject can be an array, list, hashtable, dictionary, collection or a single string. If InputObject is another type, it is first converted to a string before being searched.

If InputObject is an array or list, this function uses PowerShell's -contains operator to determine if it contains Contains, e.g. $InputObject -contains $Contains.

If InputObject is a dictionary, this function uses its Contains method to determine if it contains Contains, e.g. $InputObject.Contains($Contains).

If InputObject is a collection, this function enumerates through each item in the collection and uses PowerShell's -eq operator to determine if it matches/is equal to Contains e.g.

foreach( $item in $InputObject.GetEnumerator() )
{
    if( $item -eq $Contains )
    {
    }
}

In all other cases, InputObject and Contains are converted to strings and compared using the -like operator. Any wildcards in Contains are escaped and it is wrapped in the * wildcard, e.g. $InputObject -like ('*{0}*' -f [Management.Automation.WildcardPattern]::Escape($Contains)).

true false
DoesNotThrowException SwitchParameter

Asserts that the script block given by InputObject does not throw an exception.

true false False
Throws Type

The type of the exception $InputObject should throw. When this parameter is provided, $INputObject should be a script block.

true false
AndMessageMatches String

Used with the Throws switch. Checks that the thrown exception message matches a regular rexpression.

false false
Message String

The message to show when the assertion fails.

false false

EXAMPLE 1

Assert-That { throw 'Fubar!' } -Throws [Management.Automation.RuntimeException]

Demonstrates how to check that a script block throws an exception.

EXAMPLE 2

Assert-That { } -DoesNotThrowException

Demonstrates how to check that a script block doesn't throw an exception.

EXAMPLE 3

Assert-That @( 1, 2, 3 ) -Contains 2

Demonstrates how to check if an array, list, or other collection contains an object.

EXAMPLE 4

Assert-That @{ 'fubar' = 'snafu' } -Contains 'fubar'

Demonstrates how to check if a hashtable/dictionary object contains a value.

EXAMPLE 5

Assert-That 'fubar' -Contains 'UBA'

Demonstrates how to check if a string contains a substring. The search is case-insensitive.