Assert-Expression

Assert-Expression

Tests a PowerShell expression against expected values and provides color-coded results.

Assert-Expression [[-actual] <Object>] [[-expected] <Object>] [[-label] <Object>] [<CommonParameters>]

Assert-Expression lets you validate assertions, taking advantage of PowerShell's capability to evaluate code dynamically. Supply an expression as a string along with an expected result. The string is evaluated with PowerShell's Invoke-Expression cmdlet and the result compared to your expected result.

Assert-Expression reports its results to the console. The expression is displayed along with a "pass" (green) or "fail" (red). If the test fails, the actual and expected values are both displayed. The actual result and the expected result may each be either a scalar or an array. If either is an array, the entire array is displayed and those values that mismatch are higlighted in red. Note that arrays are always considered ordered lists, not sets. Thus if you expect (1, 2) but you get (2, 1), both elements of the array are highlighted as mismatches.

Normally, Assert-Expression reports and returns but you can also make it throw an exception on a failure via the Set-AbortOnError function.

The failed results are aligned after the input expression on the same line. Use the Set-MaxExpressionDisplayLength to adjust how much of the input expression to display.

Use Get-AssertCounts at the end to get a count of passed and failed tests.

-actual <Object>

        Required?                    false

        Position?                    1

        Default value                

        Accept pipeline input?       false

        Accept wildcard characters?  false

-expected <Object>

        A scalar or array of values you expect the expression to return.

        Required?                    false

        Position?                    2

        Default value                

        Accept pipeline input?       false

        Accept wildcard characters?  false

-label <Object>

        Required?                    false

        Position?                    3

        Default value                

        Accept pipeline input?       false

        Accept wildcard characters?  false

<CommonParameters>

        This cmdlet supports the common parameters: Verbose, Debug,

        ErrorAction, ErrorVariable, WarningAction, WarningVariable,

        OutBuffer and OutVariable. For more information, see 

        about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216). 

None. You cannot pipe objects to Assert-Expression.

None. Assert-Expression does not generate any output.

        This function is part of the CleanCode toolbox

        from http://cleancode.sourceforge.net/.

        Since CleanCode 1.1.01.

-------------------------- EXAMPLE 1 --------------------------

PS>Assert-Expression '(2 + 5)' 7

* Result: PASS
* Reason: Sum of the two values is 7.

-------------------------- EXAMPLE 2 --------------------------

PS>Assert-Expression '[Math]::Min(-5,-9)' -9

* Result: PASS
* Reason: Minimum of the two values is -9.

-------------------------- EXAMPLE 3 --------------------------

PS>Assert-Expression '"xyz".substring(1,0)' ""

* Result: PASS
* Reason: Expression evaluates to an empty string.

-------------------------- EXAMPLE 4 --------------------------

PS>Assert-Expression '"[abc]","[def]","[ghi]"' "[abc]","[def]","[ghi]"

* Result: PASS
* Reason: Expression evaluation matches the expected result item for item.

-------------------------- EXAMPLE 5 --------------------------

PS>Assert-Expression '"[abc]"' "[abc]","[def]","[ghi]"

* Result: FAIL
* Reason: Expression evaluation returns [abc] while expecting a 3-item array. The second and third items are highlighted as erroneous.

-------------------------- EXAMPLE 6 --------------------------

PS>Assert-Expression '"[ghi]"' "[abc]","[def]","[ghi]"

* Result: FAIL
* Reason: Expression evaluation returns [ghi] while expecting a 3-item array. All three items are highlighted as erroneous because none of them match positionally. That is, the first item is supposed to be [abc], not [ghi], so that is a mismatch. There are no more items returned from the expression, so the leftover items mismatch.

-------------------------- EXAMPLE 7 --------------------------

PS>Assert-Expression '"[abc]","[def]","[ghi]"' "[abc]"

* Result: FAIL
* Reason: Expression evaluation returns three items while expecting just one. The second and third items are highlighted as erroneous.

-------------------------- EXAMPLE 8 --------------------------

PS>New-Module -scriptblock {function Double($count) { $count * 2}} | Out-Null; Assert-Expression 'Double(25)' 50; $global:myNum = 99; Assert-Expression 'Double($myNum)' 198

* Result: PASS
* Reason: This example shows how to handle functions that may be in a library. As the first Assert-Expression shows, constant arguments work just fine. But in order to pass a variable from the current script as in the second part of the example, you must give that variable global scope, otherwise it will generate a runtime error flagging $myNum as undefined.