Cleanup about_* help topics and extract PesterConfiguration docs to a…

…bout_PesterConfiguration (#2518) * Remove outdated docs * Include option types in PesterConfiguration docs * Add draft for about_PesterConfiguration help topic * Move PesterConfiguration options reference to help topic * Minor text updates * wip * Update Invoke-Pester help for Configuration * Update build script * Update help for Invoke-Pester -Configuration * Fix build script * Update about_Pester.help.txt * Update release script
pester · Jul 1, 2024 · 6754b26 · 6754b26
1 parent 718ba6d
commit 6754b26
Show file tree

Hide file tree

Showing 10 changed files with 316 additions and 1,085 deletions.
diff --git a/build.ps1 b/build.ps1
@@ -76,9 +76,8 @@ if ($Clean -and (Test-Path "$PSScriptRoot/bin")) {
 }
 
 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
+    # Using Import-LocalizedData over Test-ModuleManifest because the latter requires psm1 and
+    # PesterConfiguration.Format.xml to exists which are both generated later in build script
     $manifest = Import-LocalizedData -FileName 'Pester.psd1' -BaseDirectory "$PSScriptRoot/src"
     if (-not $LockedRestore) {
         dotnet restore "$PSScriptRoot/src/csharp/Pester.sln"
@@ -92,43 +91,13 @@ if ($Clean) {
     }
 }
 
-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/Pester.ps1", "$PSScriptRoot/bin/")
-    , ("$PSScriptRoot/src/Pester.psd1", "$PSScriptRoot/bin/")
-    , ("$PSScriptRoot/src/Pester.Format.ps1xml", "$PSScriptRoot/bin/")
-)
-
 if ($Clean) {
-    $content += @(
-        , ("$PSScriptRoot/src/schemas/JUnit4/*.xsd", "$PSScriptRoot/bin/schemas/JUnit4/")
-        , ("$PSScriptRoot/src/schemas/NUnit25/*.xsd", "$PSScriptRoot/bin/schemas/NUnit25/")
-        , ("$PSScriptRoot/src/schemas/NUnit3/*.xsd", "$PSScriptRoot/bin/schemas/NUnit3/")
-        , ("$PSScriptRoot/src/schemas/JaCoCo/*.dtd", "$PSScriptRoot/bin/schemas/JaCoCo/")
-        , ("$PSScriptRoot/src/csharp/Pester/bin/$Configuration/net462/Pester.dll", "$PSScriptRoot/bin/bin/net462/")
-        , ("$PSScriptRoot/src/csharp/Pester/bin/$Configuration/net6.0/Pester.dll", "$PSScriptRoot/bin/bin/net6.0/")
-    )
-}
-
-Copy-Content -Content $content
-
-if ($Clean) {
-    # update help for New-PesterConfiguration
-    if ($PSVersionTable.PSVersion.Major -gt 5) {
-        $null = [Reflection.Assembly]::LoadFrom("$PSScriptRoot/bin/bin/net6.0/Pester.dll")
+    # Update PesterConfiguration help in about_PesterConfiguration
+    if ($PSVersionTable.PSVersion.Major -ge 6) {
+        $null = [Reflection.Assembly]::LoadFrom("$PSScriptRoot/src/csharp/Pester/bin/$Configuration/net6.0/Pester.dll")
     }
     else {
-        $null = [Reflection.Assembly]::LoadFrom("$PSScriptRoot/bin/bin/net462/Pester.dll")
+        $null = [Reflection.Assembly]::LoadFrom("$PSScriptRoot/src/csharp/Pester/bin/$Configuration/net462/Pester.dll")
     }
 
     function Format-NicelyMini ($value) {
@@ -175,49 +144,74 @@ if ($Clean) {
         foreach ($r in $section.PSObject.Properties.Name) {
             $option = $section.$r
             $default = Format-NicelyMini $option.Default
-            "  ${r}: $($option.Description)$eol  Default value: ${default}$eol"
+            $type = $option.Default.GetType() -as [string]
+            "    ${r}: $($option.Description)$eol    Type: ${type}$eol    Default value: ${default}$eol"
         }
     }
 
-    $p = "$PSScriptRoot/src/Pester.RSpec.ps1"
+    $helpPath = "$PSScriptRoot/src/en-US/about_PesterConfiguration.help.txt"
     # in older versions utf8 means with BOM
-    $e = if ($PSVersionTable.PSVersion.Major -ge 7) { 'utf8BOM' } else { 'utf8' }
-    $f = Get-Content $p -Encoding $e
+    $enc = if ($PSVersionTable.PSVersion.Major -ge 7) { 'utf8BOM' } else { 'utf8' }
+    $helpContent = Get-Content $helpPath -Encoding $enc
+
+    # Get section margin from the topic name on line 2
+    $margin = if ($helpContent[1] -match '^(?<margin>\s*)about_') { $matches.margin } else { '' }
     $sbf = [System.Text.StringBuilder]''
     $generated = $false
-    foreach ($l in $f) {
-        if ($l -match '^(?<margin>\s*)Sections and options:\s*$') {
-            $null = $sbf.AppendLine("$l$eol")
+    foreach ($line in $helpContent) {
+        if (-not $generated -and $line -match '^SECTIONS AND OPTIONS\s*$') {
             $generated = $true
-            $margin = $matches.margin
-            $null = $sbf.AppendLine("$margin``````")
+            $null = $sbf.AppendLine("$line$eol")
 
-            $generatedLines = @($generatedConfig -split $eol)
-            for ($i = 0; $i -lt $generatedLines.Count; $i++) {
-                $l = $generatedLines[$i]
+            foreach ($l in @($generatedConfig -split $eol)) {
                 $m = if ($l) { $margin } else { $null }
-
-                if ($i -eq $generatedLines.Count - 1) {
-                    #last line should be blank - replace with codeblock end
-                    $null = $sbf.AppendLine("$margin``````$eol")
-                }
-                else {
-                    $null = $sbf.AppendLine("$m$l")
-                }
+                $null = $sbf.AppendLine("$m$l")
             }
         }
-        elseif ($generated -and ($l -match '^\s*(.PARAMETER|.EXAMPLE).*')) {
+        elseif ($generated -and ($line -cmatch '^SEE ALSO\s*$')) {
             $generated = $false
         }
 
         if (-not $generated) {
-            $null = $sbf.AppendLine($l)
+            $null = $sbf.AppendLine($line)
         }
     }
 
-    Set-Content -Encoding $e -Value $sbf.ToString().TrimEnd() -Path $p
+    Set-Content -Encoding $enc -Value $sbf.ToString().TrimEnd() -Path $helpPath
+}
 
-    # generate PesterConfiguration.Format.ps1xml to ensure list view for all sections
+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/Pester.ps1", "$PSScriptRoot/bin/")
+    , ("$PSScriptRoot/src/Pester.psd1", "$PSScriptRoot/bin/")
+    , ("$PSScriptRoot/src/Pester.Format.ps1xml", "$PSScriptRoot/bin/")
+)
+
+if ($Clean) {
+    $content += @(
+        , ("$PSScriptRoot/src/schemas/JUnit4/*.xsd", "$PSScriptRoot/bin/schemas/JUnit4/")
+        , ("$PSScriptRoot/src/schemas/NUnit25/*.xsd", "$PSScriptRoot/bin/schemas/NUnit25/")
+        , ("$PSScriptRoot/src/schemas/NUnit3/*.xsd", "$PSScriptRoot/bin/schemas/NUnit3/")
+        , ("$PSScriptRoot/src/schemas/JaCoCo/*.dtd", "$PSScriptRoot/bin/schemas/JaCoCo/")
+        , ("$PSScriptRoot/src/csharp/Pester/bin/$Configuration/net462/Pester.dll", "$PSScriptRoot/bin/bin/net462/")
+        , ("$PSScriptRoot/src/csharp/Pester/bin/$Configuration/net6.0/Pester.dll", "$PSScriptRoot/bin/bin/net6.0/")
+    )
+}
+
+Copy-Content -Content $content
+
+if ($Clean) {
+    # Generate PesterConfiguration.Format.ps1xml to ensure list view for all sections
     $configSections = $configObject.GetType().Assembly.GetExportedTypes() | Where-Object { $_.BaseType -eq [Pester.ConfigurationSection] }
     # Get internal ctor as public ctor always returns instanceId = zero guid prior to PS v7.1.0
     $formatViewCtor = [System.Management.Automation.FormatViewDefinition].GetConstructors('Instance,NonPublic')
@@ -235,7 +229,7 @@ if ($Clean) {
 
     # Create view for Option to ensure Table and hide IsModified
     $builder = [System.Management.Automation.TableControl]::Create().StartRowDefinition()
-    [Pester.Option[bool]].GetProperties() | Where-Object Name -notin 'IsModified' | ForEach-Object {
+    [Pester.Option[bool]].GetProperties() | Where-Object Name -NotIn 'IsModified' | ForEach-Object {
         $builder.AddPropertyColumn($_.Name, [System.Management.Automation.Alignment]::Undefined, $null) > $null
     }
     $tableControl = $builder.EndRowDefinition().EndTable()
@@ -247,12 +241,12 @@ if ($Clean) {
     Export-FormatData -InputObject $typeDefs -Path "$PSScriptRoot/bin/PesterConfiguration.Format.ps1xml"
 }
 
-if (-not $PSBoundParameters.ContainsKey("Inline")) {
+if (-not $PSBoundParameters.ContainsKey('Inline')) {
     # Force inlining by env variable, build.ps1 is used in
     # multiple places and passing the $inline everywhere is
     # difficult.
     # Only read this option here. Don't write it.
-    if ($env:PESTER_BUILD_INLINE -eq "1") {
+    if ($env:PESTER_BUILD_INLINE -eq '1') {
         $Inline = $true
     }
     else {
@@ -266,7 +260,6 @@ else {
     $env:PESTER_BUILD_INLINE = [string][int][bool] $Inline
 }
 
-
 $null = New-Item "$PSScriptRoot/bin" -ItemType Directory -Force
 
 $script = @(

diff --git a/publish/release.ps1 b/publish/release.ps1
@@ -62,11 +62,8 @@ $files = @(
     'PesterConfiguration.Format.ps1xml'
     'bin/net462/Pester.dll'
     'bin/net6.0/Pester.dll'
-    'en-US/about_BeforeEach_AfterEach.help.txt'
-    'en-US/about_Mocking.help.txt'
     'en-US/about_Pester.help.txt'
-    'en-US/about_Should.help.txt'
-    'en-US/about_TestDrive.help.txt'
+    'en-US/about_PesterConfiguration.help.txt'
     'schemas/JaCoCo/report.dtd'
     'schemas/JUnit4/junit_schema_4.xsd'
     'schemas/NUnit25/nunit_schema_2.5.xsd'

diff --git a/src/Main.ps1 b/src/Main.ps1
@@ -400,16 +400,8 @@ function Invoke-Pester {
     https://github.com/danielpalme/ReportGenerator
 
     .PARAMETER Configuration
-    (Introduced v5)
-    [PesterConfiguration] object for Advanced Configuration
-
-    Pester supports Simple and Advanced Configuration.
-
-    Invoke-Pester -Configuration <PesterConfiguration> [<CommonParameters>]
-
-    Default is New-PesterConfiguration.
-
-    For help on each option see New-PesterConfiguration, or inspect the object it returns.
+    [PesterConfiguration] object for Advanced Configuration created using `New-PesterConfiguration`.
+    For help on each option see about_PesterConfiguration or inspect the object.
 
     .PARAMETER Container
     Specifies one or more ContainerInfo-objects that define containers with tests.
@@ -552,7 +544,7 @@ function Invoke-Pester {
     even if the first fails.
 
     .EXAMPLE
-    $config = [PesterConfiguration]::Default
+    $config = New-PesterConfiguration
     $config.TestResult.Enabled = $true
     Invoke-Pester -Configuration $config
 

diff --git a/src/Pester.RSpec.ps1 b/src/Pester.RSpec.ps1
@@ -288,154 +288,11 @@ function New-PesterConfiguration {
 
     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. Exit code is always set to `$LASTEXITCODE` even when this option is `$false`. 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
-
-      SkipRemainingOnFailure: Skips remaining tests after failure for selected scope, options are None, Run, Container and Block.
-      Default value: 'None'
-
-    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 programmatically to avoid problems with expanded names. Explicit filter that overrides -Skip. Example: 'C:\tests\file1.Tests.ps1:37'
-      Default value: @()
-
-      ExcludeLine: Exclude by file and scriptblock start line, takes precedence over Line.
-      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 code coverage, 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
-
-      UseBreakpoints: When false, use Profiler based tracer to do CodeCoverage instead of using breakpoints.
-      Default value: $false
-
-      SingleHitBreakpoints: Remove breakpoint when it is hit. This increases performance of breakpoint based CodeCoverage.
-      Default value: $true
-
-    TestResult:
-      Enabled: Enable TestResult.
-      Default value: $false
-
-      OutputFormat: Format to use for test result report. Possible values: NUnitXml, NUnit2.5, NUnit3 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'
-
-      DisableV5: Disables usage of Should -Be assertions, that are replaced by Should-Be in version 6.
-      Default value: $false
-
-    Debug:
-      ShowFullErrors: Show full errors including Pester internal stack. This property is deprecated, and if set to true it will override Output.StackTraceVerbosity to 'Full'.
-      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', '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'
-
-      StackTraceVerbosity: The verbosity of stacktrace output, options are None, FirstLine, Filtered and Full.
-      Default value: 'Filtered'
-
-      CIFormat: The CI format of error output in build logs, options are None, Auto, AzureDevops and GithubActions.
-      Default value: 'Auto'
-
-      CILogLevel: The CI log level in build logs, options are Error and Warning.
-      Default value: 'Error'
-
-      RenderMode: The mode used to render console output, options are Auto, Ansi, ConsoleColor and Plaintext.
-      Default value: 'Auto'
-
-    TestDrive:
-      Enabled: Enable TestDrive.
-      Default value: $true
-
-    TestRegistry:
-      Enabled: Enable TestRegistry.
-      Default value: $true
-    ```
+    For a complete list of options, see `Get-Help about_PesterConfiguration` or https://pester.dev/docs/usage/configuration
 
     .PARAMETER Hashtable
     Override the default values for the options defined in the provided dictionary/hashtable.
-    See Description in this help or inspect a PesterConfiguration-object to learn about the schema and
+    See about_PesterConfiguration help topic or inspect a PesterConfiguration-object to learn about the schema and
     available options.
 
     .EXAMPLE
@@ -479,6 +336,9 @@ function New-PesterConfiguration {
 
     .LINK
     https://pester.dev/docs/commands/Invoke-Pester
+
+    .LINK
+    about_PesterConfiguration
     #>
     [CmdletBinding()]
     param(