Getting started

To evaluate the code quality of a single script, simply use the Invoke-PSCodeHealth command.
Specify the relative or full path of the script file via the Path parameter and specify the location of the tests via the TestsPath parameter, like so :

C:\> Invoke-PSCodeHealth -Path '.\coveralls\Coveralls.ps1' -TestsPath '.\coveralls'

Files    Functions      LOC (Average)  Findings       Findings       Complexity    Test Coverage
                                       (Total)        (Average)      (Average)                  
-----    ---------      -------------  -------------- -------------- ------------- -------------
1        9              22.33          0              0              2             39.58 %      

To evaluate the code quality of all the PowerShell code in a directory, specify the relative or full path of the directory via the Path parameter, like so :

C:\> Invoke-PSCodeHealth -Path '.\coveralls' -TestsPath '.\coveralls'

Files    Functions      LOC (Average)  Findings       Findings       Complexity    Test Coverage
                                       (Total)        (Average)      (Average)                  
-----    ---------      -------------  -------------- -------------- ------------- -------------
3        9              22.33          0              0              2             38.78 %      

Viewing all the code metrics

The above provides a simple table to view the most important metrics at a glance, but this is just the default view.
To view all the metrics, you can pipe the output of Invoke-PSCodeHealth to Format-List, like so :

PS C:\> Invoke-PSCodeHealth -Path '.\coveralls' -TestsPath '.\coveralls' | Format-List


ReportTitle                   : coveralls
ReportDate                    : 2017-06-18 18:27:53Z
AnalyzedPath                  : C:\coveralls
Files                         : 3
Functions                     : 9
LinesOfCodeTotal              : 201
LinesOfCodeAverage            : 22.33
ScriptAnalyzerFindingsTotal   : 0
ScriptAnalyzerErrors          : 0
ScriptAnalyzerWarnings        : 0
ScriptAnalyzerInformation     : 0
ScriptAnalyzerFindingsAverage : 0
FunctionsWithoutHelp          : 9
NumberOfTests                 : 13
NumberOfFailedTests           : 2
FailedTestsDetails            : {@{File=Coveralls.Tests.ps1; Line=97; Describe=Get-CoverageArray; TestName=Should 
                                return 2 objects with the value 1; ErrorMessage=Expected: {2}
                                But was:  {0}}, @{File=Coveralls.Tests.ps1; Line=100; Describe=Get-CoverageArray; 
                                TestName=Should return 0 objects with the value 0; ErrorMessage=Expected: value to 
                                be empty but it was {1}}}
NumberOfPassedTests           : 11
TestsPassRate                 : 84.62
TestCoverage                  : 38.78
CommandsMissedTotal           : 60
ComplexityAverage             : 2
ComplexityHighest             : 5
NestingDepthAverage           : 1.11
NestingDepthHighest           : 3
FunctionHealthRecords         : {@{FunctionName=Add-CoverageInfo; FilePath=C:\coveralls\Coveralls.ps1; 
                                LinesOfCode=14; ScriptAnalyzerFindings=0; ScriptAnalyzerResultDetails=; 
                                ContainsHelp=False; TestCoverage=0; CommandsMissed=3; Complexity=1; 
                                MaximumNestingDepth=1}, @{FunctionName=Merge-CoverageResult; 
                                FilePath=C:\coveralls\Coveralls.ps1; LinesOfCode=21; ScriptAnalyzerFindings=0; 
                                ScriptAnalyzerResultDetails=; ContainsHelp=False; TestCoverage=0; CommandsMissed=6; 
                                Complexity=1; MaximumNestingDepth=0}, @{FunctionName=Get-CoverageArray; 
                                FilePath=C:\coveralls\Coveralls.ps1; LinesOfCode=30; ScriptAnalyzerFindings=0; 
                                ScriptAnalyzerResultDetails=; ContainsHelp=False; TestCoverage=94.44; 
                                CommandsMissed=1; Complexity=5; MaximumNestingDepth=3}, 
                                @{FunctionName=Format-FileCoverage; FilePath=C:\coveralls\Coveralls.ps1; 
                                LinesOfCode=24; ScriptAnalyzerFindings=0; ScriptAnalyzerResultDetails=; 
                                ContainsHelp=False; TestCoverage=100; CommandsMissed=0; Complexity=2; 
                                MaximumNestingDepth=1}...}

Viewing the per-function metrics

To view the per-function information, access the FunctionHealthRecords property of the output of Invoke-PSCodeHealth :

C:\> $HealthReport = Invoke-PSCodeHealth -Path '.\coveralls' -TestsPath '.\coveralls'
C:\> $HealthReport.FunctionHealthRecords

Function Name               Lines of Code   Complexity     Contains Help  Test Coverage  ScriptAnalyzer
                                                                                            Findings   
-------------               -------------   ----------     -------------  -------------  --------------
Add-CoverageInfo            14              1              False          0 %                  0       
Merge-CoverageResult        21              1              False          0 %                  0       
Get-CoverageArray           30              5              False          94.44 %              0       
Format-FileCoverage         24              2              False          100 %                0       
Get-CommandsForFile         16              1              False          100 %                0       
Get-GitInfo                 23              2              False          0 %                  0       
Format-Coverage             39              3              False          0 %                  0       
Publish-Coverage            18              1              False          0 %                  0       
Get-CoveragePercentage      16              2              False          100 %                0       

Excluding files from the code analysis

You may want to exclude some file(s) from the code analysis because they might not be relevant. You can do so with the Exclude parameter. The Exclude parameter can accept wildcards, for example :

C:\> Invoke-PSCodeHealth -Path '.\coveralls' -Exclude '*.psm1' -TestsPath '.\coveralls'

Files    Functions        LOC (Average)    Findings (Total) Findings         Complexity       Test Coverage  
                                                            (Average)        (Average)                       
-----    ---------        -------------    ---------------- ---------------- ---------------- -------------  
2        9                22.33            0                0                2                39.58 %        

Generating an HTML report

To output the PSCodeHealth report as an HTML file, use the HtmlReportPath parameter to specify the full path of the HTML file :

C:\> Invoke-PSCodeHealth -Path '.\coveralls' -TestsPath '.\coveralls' -HtmlReportPath "$env:USERPROFILE\Desktop\Report.html"

The above command will not output anything to the PowerShell pipeline, unless you add the PassThru parameter.