diff --git a/en-US/about_Should.help.txt b/en-US/about_Should.help.txt index c769d1cd0..efecdce67 100644 --- a/en-US/about_Should.help.txt +++ b/en-US/about_Should.help.txt @@ -15,7 +15,8 @@ LONG DESCRIPTION perform various comparisons of objects and will throw a PesterFailure when the objects do not evaluate to be comparable. - SHOULD MEMBERS +SHOULD MEMBERS + GENERAL Be Compares one object with another for equality and throws if the two objects are not the same. @@ -30,22 +31,40 @@ LONG DESCRIPTION $actual="Actual value" $actual | Should -BeExactly "Actual value" # Test will pass $actual | Should -BeExactly "actual value" # Test will fail + + BeNullOrEmpty + Checks values for null or empty (strings). The static [String]::IsNullOrEmpty() method is used to do the comparison. - BeGreaterThan - Asserts that a number is greater than an expected value. Uses PowerShell's -gt operator to compare the two values. + $null | Should -BeNullOrEmpty # Test will pass + $null | Should -Not -BeNullOrEmpty # Test will fail + @() | Should -BeNullOrEmpty # Test will pass + "" | Should -BeNullOrEmpty # Test will pass + BeTrue + Asserts that the value is true, or truthy. - $Error.Count | Should -BeGreaterThan 0 + $true | Should -BeTrue + 1 | Should -BeTrue + 1,2,3 | Should -BeTrue - BeIn - Asserts that a collection of values contain a specific value. Uses PowerShell's -contains operator to confirm. + BeFalse + Asserts that the value is false of falsy. - 1 | Should -BeIn @(1,2,3,'a','b','c') + $false | Should -BeFalse + 0 | Should -BeFalse + $null | Should -BeFalse - BeLessThan - Asserts that a number is less than an expected value. Uses PowerShell's -gt operator to compare the two values. + BeOfType, HaveType + Asserts that the actual value should be an object of a specified type (or a subclass of the specified type) using PowerShell's -is operator: + + $actual = Get-Item $env:SystemRoot + $actual | Should -BeOfType System.IO.DirectoryInfo # Test will pass; object is a DirectoryInfo + $actual | Should -BeOfType System.IO.FileSystemInfo # Test will pass; DirectoryInfo base class is FileSystemInfo + $actual | Should -HaveType System.IO.FileSystemInfo # Test will pass; DirectoryInfo base class is FileSystemInfo + + $actual | Should -BeOfType System.IO.FileInfo # Test will fail; FileInfo is not a base class of DirectoryInfo - $Error.Count | Should -BeLessThan 1 + TEXT BeLike Asserts that the actual value matches a wildcard pattern using PowerShell's -like operator. This comparison is not case-sensitive. @@ -61,22 +80,63 @@ LONG DESCRIPTION $actual | Should -BeLikeExactly "Actual *" # Test will pass $actual | Should -BeLikeExactly "actual *" # Test will fail - BeOfType - Asserts that the actual value should be an object of a specified type (or a subclass of the specified type) using PowerShell's -is operator: + Match + Uses a regular expression to compare two objects. This comparison is not case sensitive. - $actual = Get-Item $env:SystemRoot - $actual | Should -BeOfType System.IO.DirectoryInfo # Test will pass; object is a DirectoryInfo - $actual | Should -BeOfType System.IO.FileSystemInfo # Test will pass; DirectoryInfo base class is FileSystemInfo + "I am a value" | Should -Match "I Am" # Test will pass + "I am a value" | Should -Match "I am a bad person" # Test will fail - $actual | Should -BeOfType System.IO.FileInfo # Test will fail; FileInfo is not a base class of DirectoryInfo + Tip: Use [regex]::Escape("pattern") to match the exact text. - BeNullOrEmpty - Checks values for null or empty (strings). The static [String]::IsNullOrEmpty() method is used to do the comparison. + "Greg" | Should -Match ".reg" # Test will pass + "Greg" | Should -Match ([regex]::Escape(".reg")) # Test will fail - $null | Should -BeNullOrEmpty # Test will pass - $null | Should -Not -BeNullOrEmpty # Test will fail - @() | Should -BeNullOrEmpty # Test will pass - "" | Should -BeNullOrEmpty # Test will pass + MatchExactly + Uses a regular expression to compare two objects. This comparison is case sensitive. + + "I am a value" | Should -MatchExactly "I am" # Test will pass + "I am a value" | Should -MatchExactly "I Am" # Test will fail + + COMPARISON + BeGreaterThan + Asserts that a number (or other comparable value) is greater than an expected value. Uses PowerShell's -gt operator to compare the two values. + + 2 | Should -BeGreaterThan 0 + + BeGreaterThanOrEqual + Asserts that a number (or other comparable value) is greater than or equal to an expected value. Uses PowerShell's -ge operator to compare the two values. + + 2 | Should -BeGreaterOrEqual 0 + 2 | Should -BeGreaterOrEqual 2 + + BeLessThan + Asserts that a number (or other comparable value) is lower than an expected value. Uses PowerShell's -lt operator to compare the two values. + + 1 | Should -BeLessThan 10 + + BeLessThanOrEqual + Asserts that a number (or other comparable value) is lower than, or equal to an expected value. Uses PowerShell's -le operator to compare the two values. + + 1 | Should -BeLessOrEqual 10 + 10 | Should -BeLessOrEqual 10 + + COLLECTION + BeIn + Asserts that a collection of values contain a specific value. Uses PowerShell's -contains operator to confirm. + + 1 | Should -BeIn @(1,2,3,'a','b','c') + + Contain + Asserts that collection contains a specific value. Uses PowerShell's -contains operator to confirm. + + 1,2,3 | Should -Contain 1 + + HaveCount + Asserts that a collection has the expected amount of items. + + 1,2,3 | Should -HaveCount 3 + + FILE Exist Does not perform any comparison but checks if the object calling Exist is present in a PS Provider. The object must have valid path syntax. It @@ -108,23 +168,8 @@ LONG DESCRIPTION 'TestDrive:\file.txt' | Should -FileContentMatch 'I am' # Test will pass 'TestDrive:\file.txt' | Should -FileContentMatch 'I Am' # Test will fail - Match - Uses a regular expression to compare two objects. This comparison is not case sensitive. - - "I am a value" | Should -Match "I Am" # Test will pass - "I am a value" | Should -Match "I am a bad person" # Test will fail - - Tip: Use [regex]::Escape("pattern") to match the exact text. - - "Greg" | Should -Match ".reg" # Test will pass - "Greg" | Should -Match ([regex]::Escape(".reg")) # Test will fail - - MatchExactly - Uses a regular expression to compare two objects. This comparison is case sensitive. - - "I am a value" | Should -MatchExactly "I am" # Test will pass - "I am a value" | Should -MatchExactly "I Am" # Test will fail + EXCEPTIONS Throw Checks if an exception was thrown. Enclose input in a script block. @@ -159,6 +204,15 @@ LONG DESCRIPTION This test will fail since 3 will not be equal to the sum of 2 and 3. + BECAUSE + Every built in assertion allows you to specify -Because parameter, to give more meaning to your tests. + + function Get-Group { $null } + $groups = 1..10 | Get-Group -Size 3 + $groups | Should -HaveCount 4 -Because "because 10 items are split into three groups with 3 members and one extra group with 1 member" + + Which fails with: "Expected a collection with size {4}, because 10 items are split into three groups with 3 members and one extra group with 1 member, but got collection with size {1} []. + SEE ALSO Describe Context