This gist is the latest version of the code that validates examples against all functions in a module. It can only validate simple examples. Any example with a pipeline in it or an example where the first code line doesn't include the name of the function that we are testing, is skipped. Green = OK test. Yellow = Skipped (advanced stuff - unable…

Test-Examples.ps1

#Based on: https://mcpmag.com/articles/2019/04/18/pester-test-report-in-html.aspx

<#
Invoke-Pester -Path "C:\GIT\GITHUB\dbatools.Workspace\Test-Examples.ps1" -OutputFile 'C:\Temp\dbatools_pester_results.xml' -OutputFormat NUnitXml
C:\GIT\GITHUB\dbatools.Workspace\ReportUnit.exe "C:\Temp\dbatools_pester_results.xml" "C:\Temp\PesterReport.html"
Start-Process "C:\Temp\PesterReport.html"
#>

Import-Module "C:\GIT\GITHUB\dbatools.Workspace\dbatools" -Force

$excludeCommands = @(
    "Import-ModuleFile"    
    , "Get-DeepClone"
    , "Start-DbaPfDataCollectorSet"
)

$commandsRaw = Get-Command -Module dbatools

if ($excludeCommands.Count -gt 0) {
    $commands = $commandsRaw | Select-String -Pattern $excludeCommands -SimpleMatch -NotMatch

} else {
    $commands = $commandsRaw
}

$commands = @('Copy-DbaLogin')

cls
foreach ( $commandName in $commands) {
    # command to be tested
    #$commandName = 'New-D365Bacpac'
    #$commandName = 'Get-D365PackageLabelFile'
    # get all examples from the help
    $examples = Get-Help $commandName -Examples

    # make a describe block that will contain tests for this
    Describe "Examples from $commandName" {
        $examples.Examples.Example | foreach {
            # examples have different format,
            # at least the ones I used that MS provided
            # so you need to either standardize them,
            # or provide some hints about what to do
            # such as putting the code first
            # followed by
            #   #output: the desired output

            # here I am simply taking the first line and removing 'PS C:\>'
            # which makes some of the tests fail
            $example = $_.Code -replace "`n.*" -replace "PS C:\\>"

            if ( ($example -like "*|*" ) -or (-not ($example -match $commandName)) -or ($example -like "*).*")) {
                It "Example - $example" -Skip { $true }
            } elseif ($example -match '(?<=^(([^"|^'']\*(?<!\\)"[^"|^'']\*(?<!\\)"[^"|^'']\*)\*|[^"|^'']*))=') {
                $varAssignment = ($example -split "=")[0]

                # for every example we want a single It block
                It "Example - $example" {
                    # mock the tested command so we don't actually do anything
                    # because it can be unsafe and we don't have the environment setup
                    # (so the only thing we are testing is that the code is semantically
                    # correct and provides all the needed params)
                    Mock $commandName {
                        # I am returning true here,
                        # but some of the examples drill down to the returned object
                        # so in strict mode we would fail
                        $true
                    }

                    $exampleExtended = "$example;$varAssignment"
                    
                    # here simply invoke the example
                    $result = Invoke-Expression $exampleExtended
                    # and check that we got result from the mock
                    $result | Should -BeTrue
                }
            } else {
                # for every example we want a single It block
                It "Example - $example" {
                    # mock the tested command so we don't actually do anything
                    # because it can be unsafe and we don't have the environment setup
                    # (so the only thing we are testing is that the code is semantically
                    # correct and provides all the needed params)
                    Mock $commandName {
                        # I am returning true here,
                        # but some of the examples drill down to the returned object
                        # so in strict mode we would fail
                        $true
                    }

                    # here simply invoke the example
                    $result = Invoke-Expression $example
                    # and check that we got result from the mock
                    $result | Should -BeTrue
                }
            }
        }
    }
}

Green = OK
Yellow = Skipped - Unable to test because of either pipeline or commandname not found in the first line of example code
Red = Broken stuff