PowerShell · SteveL-MSFT · Nov 3, 2016 · Nov 3, 2016 · Nov 3, 2016 · Nov 3, 2016
@@ -627,6 +627,87 @@ function Publish-PSTestTools {
 
 }
 
+function Format-PSPesterFailure {
+    [CmdletBinding(DefaultParameterSetName="file")]
+    param(
+        [Parameter(ParameterSetName="file")]
+        [string]$NUnitLog = "pester-tests.xml",
+
+        [Parameter(ParameterSetName="object",ValueFromPipeline=$true)]
+        [PSCustomObject]$PesterFailure  
+    )
+
+    begin
+    {
+        if ($PSBoundParameters.Count -eq 0 -or $PSBoundParameters.ContainsKey("NUnitLog"))
+        {
+            $PesterFailure = Get-PSPesterFailure -NUnitLog $NUnitLog
+        }
+        [int]$totalFailures = 0
+        [string]$currentSuiteName = [String]::Empty
+    }
+
+    process
+    {
+        foreach ($Failure in $PesterFailure)
+        {
+            if (!$Failure.PSTypeNames.Contains("Pester.Failure"))
+            {
+                throw "Only [Pester.Failure] objects supported"
+            }
+
+            if ($Failure.SuiteName -ne $currentSuiteName)
+            {
+                $currentSuiteName = $Failure.SuiteName
+                Write-Host $currentSuiteName -ForegroundColor Magenta
+            }
+            Write-Host "$($Failure.TestDescription)" -ForegroundColor Green
+            Write-Host "$($Failure.FailMessage)" -ForegroundColor Red
+            Write-Host "$($Failure.Failstack)" -ForegroundColor Gray
+            $totalFailures++
+        }
+    }
+
+    end
+    {
+        Write-Host "Failures: $totalFailures" -ForegroundColor Yellow
+    }
+}
+
+function Get-PSPesterFailure {
+    param(
+        [string]$NUnitLog = "pester-tests.xml"
+    )
+
+    function SelectNodes ($xml, [string] $xpath)
+    {
+        if ($psversiontable.PSEdition -eq 'Desktop')
+        {
+            $xml.SelectNodes($xpath)
+        }
+        else 
+        {
+            [System.Xml.XmlDocumentXPathExtensions]::SelectNodes($xml, $xpath)
+        }
+    }
+
+    $outputxml = [xml](get-content $NUnitLog)
+    $failureSuites = SelectNodes -xml $outputxml -xpath "/test-results/test-suite/results/test-suite[@result='Failure']" 
+
+    foreach ($failureSuite in $failureSuites)
+    {
+        $failureTests = SelectNodes -xml $failureSuite -xpath "results/test-case[@result='Failure']"
+        foreach ($failureTest in $failureTests)
+        {
+            $totalFailures++
+            $failure = New-Object -TypeName PSCustomObject -Property @{SuiteName=$failureSuite.Name;TestDescription=$failureTest.Description;
+                FailMessage=$failureTest.failure.message;FailStack=$failuretest.failure.'stack-trace'}
+            $failure.PSTypeNames.Insert(0,"Pester.Failure")
+            $failure
+        }
+    }
+}
+
 function Start-PSPester {
     [CmdletBinding()]
     param(

diff --git a/docs/testing-guidelines/testing-guidelines.md b/docs/testing-guidelines/testing-guidelines.md
@@ -84,18 +84,34 @@ When running tests in this way, be sure that you have started PowerShell with `-
 environment is not the default or has any customization.
 
 For example, to run all the Pester tests for CI (assuming you are at the root of the PowerShell repo):
-```
+```PowerShell
 Import-Module ./build.psm1
 Start-PSPester
 ```
 If you wish to run specific tests, that is possible as well:
-```
+```PowerShell
 Start-PSPester -Directory test/powershell/engine/Api
 ```
 Or a specific Pester test file:
-```
+```PowerShell
 Start-PSPester -Directory test/powershell/engine/Api -Test XmlAdapter.Tests.Api
 ```
+If you added a `Feature` test and not a `CI` test, then you would specify the tag:
+```PowerShell
+Start-PSPester -Path ./myTest.ps1 -Tag Feature
+```
+
+### How to deal with failures?
+As part of your PR, you must ensure all existing tests pass.
+If you see any failures from `Start-PSPester` (summary reported at end), then you must investigate them and fix your PR so those tests pass or fix the test if the test case is wrong.
+Two helper functions are part of the build.psm1 module to help with that:
+* `Get-PSPesterFailure` will parse the NUnit test result log and return PowerShell objects for each failure so you can do additional filtering, sorting, grouping, etc...
+* `Format-PSPesterFailure` will call `Get-PSPesterFailure` if no parameters are provided and show just the failures at the console similar to what Pester displays
+
+```PowerShell
+Start-PSPester    # summary shows failures
+Format-PSPesterFailure
+```
 
 ### What happens after your PR?
 When your PR has successfully passed the CI test gates, your changes will be used to create PowerShell binaries which can be run