Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cleanup about_* help topics and extract PesterConfiguration docs to about_PesterConfiguration #2518

Merged
merged 12 commits into from
Jul 1, 2024
123 changes: 58 additions & 65 deletions build.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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) {
Expand Down Expand Up @@ -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')
Expand All @@ -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()
Expand All @@ -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 {
Expand All @@ -266,7 +260,6 @@ else {
$env:PESTER_BUILD_INLINE = [string][int][bool] $Inline
}


$null = New-Item "$PSScriptRoot/bin" -ItemType Directory -Force

$script = @(
Expand Down
5 changes: 1 addition & 4 deletions publish/release.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
14 changes: 3 additions & 11 deletions src/Main.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand Down
150 changes: 5 additions & 145 deletions src/Pester.RSpec.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -479,6 +336,9 @@ function New-PesterConfiguration {

.LINK
https://pester.dev/docs/commands/Invoke-Pester

.LINK
about_PesterConfiguration
#>
[CmdletBinding()]
param(
Expand Down
Loading