Skip to content

Commit

Permalink
Generate config docs (#1926)
Browse files Browse the repository at this point in the history 
* Generate config object documentation
  • Loading branch information
@nohwnd
nohwnd authored Apr 30, 2021
1 parent b793235 commit 8baf734
Show file tree
Hide file tree
Showing 3 changed files with 236 additions and 106 deletions.
160 changes: 120 additions & 40 deletions build.ps1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 '^(?<margin>\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
Expand Down Expand Up @@ -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) {
Expand Down
69 changes: 3 additions & 66 deletions src/Main.ps1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -379,72 +379,9 @@ function Invoke-Pester {
Invoke-Pester -Configuration <PesterConfiguration> [<CommonParameters>]
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.
Expand Down
113 changes: 113 additions & 0 deletions src/Pester.RSpec.ps1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 8baf734

Please sign in to comment.