Update should documentation (pester#990)

Update about_should
wsmelton · Feb 18, 2018 · 89e4b74 · 89e4b74
1 parent db887df
commit 89e4b74
Showing 1 changed file with 92 additions and 38 deletions.
diff --git 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