From 8baf7344828e331aca8b09f0a536080911b14ec4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jakub=20Jare=C5=A1?= Date: Fri, 30 Apr 2021 16:03:19 +0200 Subject: [PATCH] Generate config docs (#1926) * Generate config object documentation --- build.ps1 | 160 ++++++++++++++++++++++++++++++++----------- src/Main.ps1 | 69 +------------------ src/Pester.RSpec.ps1 | 113 ++++++++++++++++++++++++++++++ 3 files changed, 236 insertions(+), 106 deletions(-) diff --git a/build.ps1 b/build.ps1 index 99de3e367..575d2bb60 100644 --- a/build.ps1 +++ b/build.ps1 @@ -53,6 +53,126 @@ if ($Clean -and (Test-Path "$PSScriptRoot/bin")) { Remove-Item "$PSScriptRoot/bin" -Recurse -Force } +if ($Clean) { + # Import-LocalizedData (and ModuleVersion-property) used as workaround due to unknown error on PS3 build with Test-ModuleManifest + # and because Test-ModuleManifest needs the psd1 and psm1 to be complete, but we want to generate help for config from the type + # so we need to build up here, and not after the module build, so xml based solution is better than one that validates the manifest + $manifest = Import-LocalizedData -FileName "Pester.psd1" -BaseDirectory "$PSScriptRoot/src" + dotnet build "$PSScriptRoot/src/csharp/Pester.sln" --configuration Release -p:VersionPrefix="$($manifest.ModuleVersion)" -p:VersionSuffix="$($manifest.PrivateData.PSData.Prerelease)" + if (0 -ne $LASTEXITCODE) { + throw "build failed!" + } +} + +function Copy-Content ($Content) { + foreach ($c in $content) { + $source, $destination = $c + + $null = New-Item -Force $destination -ItemType Directory + + Get-ChildItem $source -File | Copy-Item -Destination $destination + } +} + +$content = @( + , ("$PSScriptRoot/src/en-US/*.txt", "$PSScriptRoot/bin/en-US/") + , ("$PSScriptRoot/src/nunit_schema_2.5.xsd", "$PSScriptRoot/bin/") + , ("$PSScriptRoot/src/junit_schema_4.xsd", "$PSScriptRoot/bin/") + , ("$PSScriptRoot/src/report.dtd", "$PSScriptRoot/bin/") + , ("$PSScriptRoot/src/Pester.ps1", "$PSScriptRoot/bin/") + , ("$PSScriptRoot/src/Pester.psd1", "$PSScriptRoot/bin/") +) + +if ($Clean) { + $content += @( + , ("$PSScriptRoot/src/csharp/Pester/bin/Release/net452/Pester.dll", "$PSScriptRoot/bin/bin/net452/") + , ("$PSScriptRoot/src/csharp/Pester/bin/Release/net452/Pester.pdb", "$PSScriptRoot/bin/bin/net452/") + , ("$PSScriptRoot/src/csharp/Pester/bin/Release/netstandard2.0/Pester.dll", "$PSScriptRoot/bin/bin/netstandard2.0/") + , ("$PSScriptRoot/src/csharp/Pester/bin/Release/netstandard2.0/Pester.pdb", "$PSScriptRoot/bin/bin/netstandard2.0/") + ) +} + +Copy-Content -Content $content + + +# update help for New-PesterConfiguration +if ($PSVersionTable.PSVersion.Major -gt 5) { + $null = [Reflection.Assembly]::LoadFrom("$PSScriptRoot/bin/bin/netstandard2.0/Pester.dll") +} +else { + $null = [Reflection.Assembly]::LoadFrom("$PSScriptRoot/bin/bin/net452/Pester.dll") +} + +function Format-NicelyMini ($value) { + if ($value -is [bool]) { + if ($value) { + '$true' + } + else { + '$false' + } + } + + if ($value -is [int] -or $value -is [decimal]) { + return $value + } + + if ($value -is [string]) { + if ([String]::IsNullOrEmpty($value)) { + return '$null' + } + else { + return "'$value'" + } + } + + if ($value -is [object[]]) { + if (0 -eq $value.Count) { + return '@()' + } + $v = foreach ($i in $value) { + Format-NicelyMini $i + } + return "@($($v -join ', '))" + } +} +# generate help for config object and insert it +$configuration = [PesterConfiguration]::Default +$generatedConfig = foreach ($p in $configuration.PSObject.Properties.Name) { + $section = $configuration.($p) + "${p}:" + foreach ($r in $section.PSObject.Properties.Name) { + $option = $section.$r + $default = Format-NicelyMini $option.Default + " ${r}: $($option.Description)`n Default value: $default`n" + } +} + +$p = "$PSScriptRoot/src/Pester.RSpec.ps1" +$f = Get-Content $p -Encoding utf8 +$sbf = [System.Text.StringBuilder]"" +$generated = $false +foreach ($l in $f) { + if ($l -match '^(?\s*)Sections and options:\s*$') { + $null = $sbf.AppendLine("$l`n") + $generated = $true + $margin = $matches.margin + + foreach ($l in ($generatedConfig -split "`n")) { + $m = if ($l) { $margin } else { $null } + $null = $sbf.AppendLine("$m$l") + } + } + elseif ($generated -and ($l -match "^\s*(.PARAMETER|.EXAMPLE).*")) { + $generated = $false + } + + if (-not $generated) { + $null = $sbf.AppendLine($l) + } +} +Set-Content -Encoding utf8 -Value $sbf.ToString().TrimEnd() -Path $p + if (-not $PSBoundParameters.ContainsKey("Inline")) { # Force inlining by env variable, build.ps1 is used in # multiple places and passing the $inline everywhere is @@ -139,46 +259,6 @@ foreach ($f in $files) { $sb.ToString() | Set-Content $PSScriptRoot/bin/Pester.psm1 -Encoding UTF8 -function Copy-Content ($Content) { - foreach ($c in $content) { - $source, $destination = $c - - $null = New-Item -Force $destination -ItemType Directory - - Get-ChildItem $source -File | Copy-Item -Destination $destination - } -} - -$content = @( - ,("$PSScriptRoot/src/en-US/*.txt","$PSScriptRoot/bin/en-US/") - ,("$PSScriptRoot/src/nunit_schema_2.5.xsd", "$PSScriptRoot/bin/") - ,("$PSScriptRoot/src/junit_schema_4.xsd", "$PSScriptRoot/bin/") - ,("$PSScriptRoot/src/report.dtd", "$PSScriptRoot/bin/") - ,("$PSScriptRoot/src/Pester.ps1", "$PSScriptRoot/bin/") - ,("$PSScriptRoot/src/Pester.psd1", "$PSScriptRoot/bin/") -) - -Copy-Content -Content $content - - -if ($Clean) { - # Import-LocalizedData (and ModuleVersion-property) used as workaround due to unknown error on PS3 build with Test-ModuleManifest - $manifest = Import-LocalizedData -FileName "Pester.psd1" -BaseDirectory "$PSScriptRoot/bin" - dotnet build "$PSScriptRoot/src/csharp/Pester.sln" --configuration Release -p:VersionPrefix="$($manifest.ModuleVersion)" -p:VersionSuffix="$($manifest.PrivateData.PSData.Prerelease)" - if (0 -ne $LASTEXITCODE) { - throw "build failed!" - } - - $builtDlls += @( - ,("$PSScriptRoot/src/csharp/Pester/bin/Release/net452/Pester.dll","$PSScriptRoot/bin/bin/net452/") - ,("$PSScriptRoot/src/csharp/Pester/bin/Release/net452/Pester.pdb","$PSScriptRoot/bin/bin/net452/") - ,("$PSScriptRoot/src/csharp/Pester/bin/Release/netstandard2.0/Pester.dll","$PSScriptRoot/bin/bin/netstandard2.0/") - ,("$PSScriptRoot/src/csharp/Pester/bin/Release/netstandard2.0/Pester.pdb","$PSScriptRoot/bin/bin/netstandard2.0/") - ) - - Copy-Content -Content $builtDlls -} - $powershell = Get-Process -id $PID | Select-Object -ExpandProperty Path if ($Load) { diff --git a/src/Main.ps1 b/src/Main.ps1 index 271670820..234a8aa43 100644 --- a/src/Main.ps1 +++ b/src/Main.ps1 @@ -379,72 +379,9 @@ function Invoke-Pester { Invoke-Pester -Configuration [] - Default is [PesterConfiguration]::Default - - ConfigurationProperties include following: - - [PesterConfiguration]::Default.Run - --- - Run.ExcludePath - Directories or files to be excluded from the run. - Run.Exit - Exit with non-zero exit code when the test run fails. - Default is: false - Run.PassThru - Return result object to the pipeline after finishing the test run. - Default is: false - Run.Path - Directories to be searched for tests, paths directly to test files, or combination of both. - Default is: . - Run.ScriptBlock - ScriptBlocks containing tests to be executed. - Run.Container - ContainerInfo objects containing tests to be executed. - Run.TestExtension - Filter used to identify test files. - Default is: *.Tests.ps1* - - [PesterConfiguration]::Default.Output - ------------ - Output.Verbosity - The verbosity of output, options are None, Normal, Detailed and Diagnostic. - Default is: Normal - - [PesterConfiguration]::Default.CodeCoverage - ------------ - CodeCoverage.Enabled - Enable CodeCoverage. - Default is: false - CodeCoverage.OutputFormat - Format to use for code coverage report. Possible values: JaCoCo - CodeCoverage.OutputPath - Path relative to the current directory where code coverage report is saved. - Default is: coverage.xml - CodeCoverage.OutputEncoding - Encoding of the output file. Currently UTF8 - CodeCoverage.Path - Directories or files to be used for codecoverage, by default the Path(s) from general settings are used, unless overridden here. - CodeCoverage.ExcludeTests - Exclude tests from code coverage. This uses the TestFilter from general configuration. - Default is: true - - [PesterConfiguration]::Default.TestResult - ---------- - TestResult.Enabled - Enable TestResult. - TestResult.OutputFormat - Format to use for test result report. Possible values: NUnitXml, JUnitXml - Default is: NUnitXml - TestResult.OutputPath - Path relative to the current directory where test result report is saved. - Default is: testResults.xml - TestResult.OutputEncoding - Encoding of the output file. Currently UTF8 - TestResult.TestSuiteName - Set the name assigned to the root 'test-suite' element. - Default is: Pester - - [PesterConfiguration]::Default.Filter - ------ - Filter.ExcludeTag - Exclude a tag, accepts wildcards - Filter.FullName - Full name of test with -like wildcards, joined by dot. Example: '*.describe Get-Item.test1' - Filter.Line - Filter by file and scriptblock start line, useful to run parsed tests programatically to avoid problems with expanded names. Example: 'C:\tests\file1.Tests.ps1:37' - Filter.Tag - Tags of Describe, Context or It to be run. - Should.ErrorAction - Controls if Should throws on error. Use 'Stop' to throw on error, or 'Continue' to fail at the end of the test. - - [PesterConfiguration]::Default.Should - ------------ - Should.ErrorAction - Controls if Should throws on error. Use 'Stop' to throw on error, or 'Continue' to fail at the end of the test. - Default is: Stop - - [PesterConfiguration]::Default.Debug - ----- - Debug.ShowFullErrors - Show full errors including Pester internal stack. - Debug.ShowNavigationMarkers - Write paths after every block and test, for easy navigation in VSCode. - Debug.WriteDebugMessages - Write Debug messages to screen. - Debug.WriteDebugMessagesFrom - Write Debug messages from a given source, WriteDebugMessages must be set to true for this to work. You can use like wildcards to get messages from multiple sources, as well as * to get everything. - Available options: "Discovery", "Skip", "Filter", "Mock", "CodeCoverage" + Default is New-PesterConfiguration. + + For help on each option see New-PesterConfiguration, or inspect the object it returns. .PARAMETER Container Specifies one or more ContainerInfo-objects that define containers with tests. diff --git a/src/Pester.RSpec.ps1 b/src/Pester.RSpec.ps1 index d9ad89e15..17dff53be 100644 --- a/src/Pester.RSpec.ps1 +++ b/src/Pester.RSpec.ps1 @@ -281,6 +281,119 @@ function New-PesterConfiguration { options. The returned [PesterConfiguration] object can be modified to suit your requirements. + Calling New-PesterConfiguration is equivalent to calling [PesterConfiguration]::Default which was used in early versions of Pester 5. + + Sections and options: + + Run: + Path: Directories to be searched for tests, paths directly to test files, or combination of both. + Default value: @('.') + + ExcludePath: Directories or files to be excluded from the run. + Default value: @() + + ScriptBlock: ScriptBlocks containing tests to be executed. + Default value: @() + + Container: ContainerInfo objects containing tests to be executed. + Default value: @() + + TestExtension: Filter used to identify test files. + Default value: '.Tests.ps1' + + Exit: Exit with non-zero exit code when the test run fails. When used together with Throw, throwing an exception is preferred. + Default value: $false + + Throw: Throw an exception when test run fails. When used together with Exit, throwing an exception is preferred. + Default value: $false + + PassThru: Return result object to the pipeline after finishing the test run. + Default value: $false + + SkipRun: Runs the discovery phase but skips run. Use it with PassThru to get object populated with all tests. + Default value: $false + + Filter: + Tag: Tags of Describe, Context or It to be run. + Default value: @() + + ExcludeTag: Tags of Describe, Context or It to be excluded from the run. + Default value: @() + + Line: Filter by file and scriptblock start line, useful to run parsed tests programatically to avoid problems with expanded names. Example: 'C:\tests\file1.Tests.ps1:37' + Default value: @() + + FullName: Full name of test with -like wildcards, joined by dot. Example: '*.describe Get-Item.test1' + Default value: @() + + CodeCoverage: + Enabled: Enable CodeCoverage. + Default value: $false + + OutputFormat: Format to use for code coverage report. Possible values: JaCoCo, CoverageGutters + Default value: 'JaCoCo' + + OutputPath: Path relative to the current directory where code coverage report is saved. + Default value: 'coverage.xml' + + OutputEncoding: Encoding of the output file. + Default value: 'UTF8' + + Path: Directories or files to be used for codecoverage, by default the Path(s) from general settings are used, unless overridden here. + Default value: @() + + ExcludeTests: Exclude tests from code coverage. This uses the TestFilter from general configuration. + Default value: $true + + RecursePaths: Will recurse through directories in the Path option. + Default value: $true + + CoveragePercentTarget: Target percent of code coverage that you want to achieve, default 75%. + Default value: 75 + + SingleHitBreakpoints: Remove breakpoint when it is hit. + Default value: $true + + TestResult: + Enabled: Enable TestResult. + Default value: $false + + OutputFormat: Format to use for test result report. Possible values: NUnitXml, NUnit2.5 or JUnitXml + Default value: 'NUnitXml' + + OutputPath: Path relative to the current directory where test result report is saved. + Default value: 'testResults.xml' + + OutputEncoding: Encoding of the output file. + Default value: 'UTF8' + + TestSuiteName: Set the name assigned to the root 'test-suite' element. + Default value: 'Pester' + + Should: + ErrorAction: Controls if Should throws on error. Use 'Stop' to throw on error, or 'Continue' to fail at the end of the test. + Default value: 'Stop' + + Debug: + ShowFullErrors: Show full errors including Pester internal stack. + Default value: $false + + WriteDebugMessages: Write Debug messages to screen. + Default value: $false + + WriteDebugMessagesFrom: Write Debug messages from a given source, WriteDebugMessages must be set to true for this to work. You can use like wildcards to get messages from multiple sources, as well as * to get everything. + Default value: @('Discovery', 'Skip', 'Filter', 'Mock', 'CodeCoverage') + + ShowNavigationMarkers: Write paths after every block and test, for easy navigation in VSCode. + Default value: $false + + ReturnRawResultObject: Returns unfiltered result object, this is for development only. Do not rely on this object for additional properties, non-public properties will be renamed without previous notice. + Default value: $false + + Output: + Verbosity: The verbosity of output, options are None, Normal, Detailed and Diagnostic. + Default value: 'Normal' + .PARAMETER Hashtable Override the default values for the options defined in the provided dictionary/hashtable. Inspect a default [PesterConfiguration] object to learn about the schema and