From 9832a0a3cad3050a50bada8f170bcd0ce0403325 Mon Sep 17 00:00:00 2001 From: nohwnd Date: Mon, 29 Jun 2026 23:40:09 +0200 Subject: [PATCH 1/3] Fix docs generation flow for Pester 6 and regenerate 6.0.0-rc2 docs Pester 6 ships a .NET 8 assembly and requires PowerShell 7.4+, but the workflow downgraded to 7.3 (to dodge platyPS #663). On 7.3 the net8.0 Pester.dll fails to load, so [PesterConfiguration] is unavailable and the "Update Pester Docs" workflow broke. Run on the runner's default 7.4+ and strip the spurious ProgressAction parameter from the generated MDX instead. - generate-pester-docs.yml: drop the PowerShell 7.3 downgrade step - generate-command-reference.ps1: strip ProgressAction (platyPS #663) post-gen - generate-pesterconfiguration-docs.ps1: null-safe default/type handling and replace the machine-specific Run.RepoRoot default with an illustrative C:\MyProject placeholder - Regenerate command reference and Configuration page for 6.0.0-rc2 (adds Should-BeHashtable and the new rc2 config options) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/generate-pester-docs.yml | 16 +- docs/commands/Add-ShouldOperator.mdx | 2 +- docs/commands/AfterAll.mdx | 2 +- docs/commands/AfterEach.mdx | 2 +- docs/commands/BeforeAll.mdx | 2 +- docs/commands/BeforeDiscovery.mdx | 2 +- docs/commands/BeforeEach.mdx | 2 +- docs/commands/Context.mdx | 2 +- docs/commands/ConvertTo-JUnitReport.mdx | 2 +- docs/commands/ConvertTo-NUnitReport.mdx | 5 +- docs/commands/ConvertTo-Pester4Result.mdx | 2 +- docs/commands/Describe.mdx | 2 +- docs/commands/Export-JUnitReport.mdx | 2 +- docs/commands/Export-NUnitReport.mdx | 5 +- docs/commands/Get-ShouldOperator.mdx | 2 +- docs/commands/InModuleScope.mdx | 14 +- docs/commands/Invoke-Pester.mdx | 382 ++---------------- docs/commands/It.mdx | 2 +- docs/commands/Mock.mdx | 5 +- docs/commands/New-Fixture.mdx | 2 +- docs/commands/New-MockObject.mdx | 18 +- docs/commands/New-PesterConfiguration.mdx | 2 +- docs/commands/New-PesterContainer.mdx | 8 +- docs/commands/Set-ItResult.mdx | 6 +- docs/commands/Should-All.mdx | 8 +- docs/commands/Should-Any.mdx | 8 +- docs/commands/Should-Be.mdx | 8 +- docs/commands/Should-BeAfter.mdx | 57 ++- docs/commands/Should-BeBefore.mdx | 62 ++- docs/commands/Should-BeCollection.mdx | 11 +- docs/commands/Should-BeEmptyString.mdx | 8 +- docs/commands/Should-BeEquivalent.mdx | 53 +-- docs/commands/Should-BeFalse.mdx | 8 +- docs/commands/Should-BeFalsy.mdx | 8 +- docs/commands/Should-BeFasterThan.mdx | 24 +- docs/commands/Should-BeGreaterThan.mdx | 7 +- docs/commands/Should-BeGreaterThanOrEqual.mdx | 7 +- docs/commands/Should-BeHashtable.mdx | 196 +++++++++ docs/commands/Should-BeLessThan.mdx | 7 +- docs/commands/Should-BeLessThanOrEqual.mdx | 7 +- docs/commands/Should-BeLikeString.mdx | 2 +- docs/commands/Should-BeNull.mdx | 8 +- docs/commands/Should-BeSame.mdx | 8 +- docs/commands/Should-BeSlowerThan.mdx | 24 +- docs/commands/Should-BeString.mdx | 2 +- docs/commands/Should-BeTrue.mdx | 8 +- docs/commands/Should-BeTruthy.mdx | 8 +- docs/commands/Should-ContainCollection.mdx | 8 +- docs/commands/Should-HaveParameter.mdx | 46 +-- docs/commands/Should-HaveType.mdx | 8 +- docs/commands/Should-Invoke.mdx | 94 +++-- docs/commands/Should-MatchString.mdx | 18 +- docs/commands/Should-NotBe.mdx | 8 +- docs/commands/Should-NotBeEmptyString.mdx | 8 +- docs/commands/Should-NotBeLikeString.mdx | 2 +- docs/commands/Should-NotBeNull.mdx | 8 +- docs/commands/Should-NotBeSame.mdx | 13 +- docs/commands/Should-NotBeString.mdx | 12 +- .../commands/Should-NotBeWhiteSpaceString.mdx | 8 +- docs/commands/Should-NotContainCollection.mdx | 8 +- docs/commands/Should-NotHaveParameter.mdx | 23 +- docs/commands/Should-NotHaveType.mdx | 8 +- docs/commands/Should-NotInvoke.mdx | 102 +++-- docs/commands/Should-NotMatchString.mdx | 18 +- docs/commands/Should-Throw.mdx | 8 +- docs/commands/Should.mdx | 122 +++--- docs/commands/docusaurus.sidebar.js | 3 +- docs/usage/configuration.mdx | 16 +- generate-command-reference.ps1 | 20 + generate-pesterconfiguration-docs.ps1 | 40 +- 70 files changed, 869 insertions(+), 760 deletions(-) create mode 100644 docs/commands/Should-BeHashtable.mdx diff --git a/.github/workflows/generate-pester-docs.yml b/.github/workflows/generate-pester-docs.yml index ecf81d3..44d73a0 100644 --- a/.github/workflows/generate-pester-docs.yml +++ b/.github/workflows/generate-pester-docs.yml @@ -37,18 +37,10 @@ jobs: - name: Checkout code uses: actions/checkout@v4 - # TEMP workaround for https://github.com/PowerShell/platyPS/issues/663 affection PS 7.4+ used in runner images - - name: Downgrade to PowerShell 7.3 - shell: pwsh - run: | - sudo apt-get remove powershell - curl https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -o packages-microsoft-prod.deb - sudo dpkg -i packages-microsoft-prod.deb - sudo apt-get update - sudo apt-get install -y powershell=7.3.11-1.deb - rm packages-microsoft-prod.deb - pwsh --version - + # Pester 6 ships a .NET 8 assembly and requires PowerShell 7.4+, so we use the + # runner's default PowerShell. The spurious ProgressAction parameter that PlatyPS + # emits on 7.4+ (https://github.com/PowerShell/platyPS/issues/663) is stripped from + # the generated MDX in generate-command-reference.ps1. # This step will also install and import modules incl. selected Pester-version - name: Update Command Reference id: commands diff --git a/docs/commands/Add-ShouldOperator.mdx b/docs/commands/Add-ShouldOperator.mdx index 7d44512..ca3538f 100644 --- a/docs/commands/Add-ShouldOperator.mdx +++ b/docs/commands/Add-ShouldOperator.mdx @@ -166,4 +166,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/AfterAll.mdx b/docs/commands/AfterAll.mdx index 9bc9d41..a36e950 100644 --- a/docs/commands/AfterAll.mdx +++ b/docs/commands/AfterAll.mdx @@ -107,4 +107,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/AfterEach.mdx b/docs/commands/AfterEach.mdx index 6527e16..403608f 100644 --- a/docs/commands/AfterEach.mdx +++ b/docs/commands/AfterEach.mdx @@ -104,4 +104,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/BeforeAll.mdx b/docs/commands/BeforeAll.mdx index 8e4c06b..19a8bc1 100644 --- a/docs/commands/BeforeAll.mdx +++ b/docs/commands/BeforeAll.mdx @@ -116,4 +116,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/BeforeDiscovery.mdx b/docs/commands/BeforeDiscovery.mdx index 15d214a..83137cf 100644 --- a/docs/commands/BeforeDiscovery.mdx +++ b/docs/commands/BeforeDiscovery.mdx @@ -94,4 +94,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/BeforeEach.mdx b/docs/commands/BeforeEach.mdx index a6e1c38..c9fa5c7 100644 --- a/docs/commands/BeforeEach.mdx +++ b/docs/commands/BeforeEach.mdx @@ -101,4 +101,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Context.mdx b/docs/commands/Context.mdx index 6701dac..51f79ef 100644 --- a/docs/commands/Context.mdx +++ b/docs/commands/Context.mdx @@ -200,4 +200,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/ConvertTo-JUnitReport.mdx b/docs/commands/ConvertTo-JUnitReport.mdx index dd129e7..0fbe3e3 100644 --- a/docs/commands/ConvertTo-JUnitReport.mdx +++ b/docs/commands/ConvertTo-JUnitReport.mdx @@ -121,4 +121,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/ConvertTo-NUnitReport.mdx b/docs/commands/ConvertTo-NUnitReport.mdx index 18137d1..ddfeba3 100644 --- a/docs/commands/ConvertTo-NUnitReport.mdx +++ b/docs/commands/ConvertTo-NUnitReport.mdx @@ -23,7 +23,8 @@ Converts a Pester result-object to an NUnit 2.5 or 3-compatible XML-report ## SYNTAX ```powershell -ConvertTo-NUnitReport [-Result] [-AsString] [[-Format] ] [] +ConvertTo-NUnitReport [-Result] [-AsString] [[-Format] ] + [] ``` ## DESCRIPTION @@ -148,4 +149,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/ConvertTo-Pester4Result.mdx b/docs/commands/ConvertTo-Pester4Result.mdx index 6b9a962..2e15c8d 100644 --- a/docs/commands/ConvertTo-Pester4Result.mdx +++ b/docs/commands/ConvertTo-Pester4Result.mdx @@ -86,4 +86,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Describe.mdx b/docs/commands/Describe.mdx index e669f66..d95ef64 100644 --- a/docs/commands/Describe.mdx +++ b/docs/commands/Describe.mdx @@ -210,4 +210,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Export-JUnitReport.mdx b/docs/commands/Export-JUnitReport.mdx index 2978fa9..ad89aa4 100644 --- a/docs/commands/Export-JUnitReport.mdx +++ b/docs/commands/Export-JUnitReport.mdx @@ -105,4 +105,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Export-NUnitReport.mdx b/docs/commands/Export-NUnitReport.mdx index c336176..c24a7c1 100644 --- a/docs/commands/Export-NUnitReport.mdx +++ b/docs/commands/Export-NUnitReport.mdx @@ -23,7 +23,8 @@ Exports a Pester result-object to an NUnit-compatible XML-report ## SYNTAX ```powershell -Export-NUnitReport [-Result] [-Path] [[-Format] ] [] +Export-NUnitReport [-Result] [-Path] [[-Format] ] + [] ``` ## DESCRIPTION @@ -121,4 +122,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Get-ShouldOperator.mdx b/docs/commands/Get-ShouldOperator.mdx index 1fe7163..3bf83ab 100644 --- a/docs/commands/Get-ShouldOperator.mdx +++ b/docs/commands/Get-ShouldOperator.mdx @@ -94,4 +94,4 @@ standard PowerShell discovery patterns (like `Get-Help Should -Parameter *`). ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/InModuleScope.mdx b/docs/commands/InModuleScope.mdx index 4622fed..1a9c162 100644 --- a/docs/commands/InModuleScope.mdx +++ b/docs/commands/InModuleScope.mdx @@ -56,11 +56,13 @@ Export-ModuleMember -Function PublicFunction # The test script: -Import-Module MyModule +BeforeAll { + Import-Module MyModule +} -InModuleScope MyModule { - Describe 'Testing MyModule' { - It 'Tests the Private function' { +Describe 'Testing MyModule' { + It 'Tests the Private function' { + InModuleScope MyModule { PrivateFunction | Should -Be $true } } @@ -69,7 +71,7 @@ InModuleScope MyModule { Normally you would not be able to access "PrivateFunction" from the PowerShell session, because the module only exported -"PublicFunction". +"PublicFunction". Using InModuleScope allowed this call to "PrivateFunction" to work successfully. @@ -204,4 +206,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Invoke-Pester.mdx b/docs/commands/Invoke-Pester.mdx index d35c465..3263c02 100644 --- a/docs/commands/Invoke-Pester.mdx +++ b/docs/commands/Invoke-Pester.mdx @@ -30,16 +30,6 @@ Invoke-Pester [[-Path] ] [-ExcludePath ] [-TagFilter ] [] ``` -### Legacy - -```powershell -Invoke-Pester [[-Path] ] [-TagFilter ] [-ExcludeTagFilter ] - [-FullNameFilter ] [-PassThru] [-EnableExit] [-CodeCoverage ] - [-CodeCoverageOutputFile ] [-CodeCoverageOutputFileEncoding ] - [-CodeCoverageOutputFileFormat ] [-Strict] [-OutputFile ] [-OutputFormat ] [-Quiet] - [-PesterOption ] [-Show ] [] -``` - ### Advanced ```powershell @@ -52,35 +42,28 @@ The Invoke-Pester function runs Pester tests, including *.Tests.ps1 files and Pester tests in PowerShell scripts. You can run scripts that include Pester tests just as you would any other -Windows PowerShell script, including typing the full path at the command line +PowerShell script, including typing the full path at the command line and running in a script editing program. Typically, you use Invoke-Pester to run all Pester tests in a directory, or to use its many helpful parameters, -including parameters that generate custom objects or XML files. +including parameters that generate custom objects or test result files. By default, Invoke-Pester runs all *.Tests.ps1 files in the current directory and all subdirectories recursively. You can use its parameters to select tests by file name, test name, or tag. -To run Pester tests in scripts that take parameter values, use the Script -parameter with a hash table value. - -Also, by default, Pester tests write test results to the console host, much like -Write-Host does, but you can use the Show parameter set to None to suppress the host -messages, use the PassThru parameter to generate a custom object -(PSCustomObject) that contains the test results, use the OutputXml and -OutputFormat parameters to write the test results to an XML file, and use the -EnableExit parameter to return an exit code that contains the number of failed -tests. +To run parameterized tests, or to mix files and script blocks, use +New-PesterContainer or the Configuration parameter. -You can also use the Strict parameter to fail all skipped tests. -This feature is ideal for build systems and other processes that require success -on every test. +By default, Pester tests write test results to the console host, much like +Write-Host does, but you can use the Output parameter with value None to suppress +host messages, use the PassThru parameter to generate a [Pester.Run] object that +contains the test results, or use the Configuration parameter to write test results +or code coverage output to files. -To help with test design, Invoke-Pester includes a CodeCoverage parameter that -lists commands, classes, functions, and lines of code that did not run during test -execution and returns the code that ran as a percentage of all tested code. +For build systems, use the CI parameter to enable test result output and fail the +process when tests fail. Invoke-Pester, and the Pester module that exports it, are products of an open-source project hosted on GitHub. @@ -140,7 +123,6 @@ to see other testresult options like output path and format and their default v ### -Path -Aliases Script Specifies one or more paths to files containing tests. The value is a path\file name or name pattern. @@ -148,8 +130,8 @@ Wildcards are permitted. ```yaml Type: String[] -Parameter Sets: Simple, Legacy -Aliases: Script +Parameter Sets: Simple +Aliases: Required: False Position: 1 @@ -160,8 +142,8 @@ Accept wildcard characters: False ### -ExcludePath -(Deprecated v4) -Replace with ConfigurationProperty Run.ExcludePath +Specifies one or more paths to exclude from the test run. +Equivalent to ConfigurationProperty Run.ExcludePath. ```yaml Type: String[] @@ -177,14 +159,14 @@ Accept wildcard characters: False ### -TagFilter -(Deprecated v4) -Aliases Tag, Tags -Replace with ConfigurationProperty Filter.Tag +Specifies tags to include in the test run. +Only tests with matching tags will run. +Equivalent to ConfigurationProperty Filter.Tag. ```yaml Type: String[] -Parameter Sets: Simple, Legacy -Aliases: Tags, Tag +Parameter Sets: Simple +Aliases: Required: False Position: Named @@ -195,12 +177,12 @@ Accept wildcard characters: False ### -ExcludeTagFilter -(Deprecated v4) -Replace with ConfigurationProperty Filter.ExcludeTag +Specifies tags to exclude from the test run. +Equivalent to ConfigurationProperty Filter.ExcludeTag. ```yaml Type: String[] -Parameter Sets: Simple, Legacy +Parameter Sets: Simple Aliases: Required: False @@ -212,13 +194,13 @@ Accept wildcard characters: False ### -FullNameFilter -(Deprecated v4) -Replace with ConfigurationProperty Filter.FullName +Specifies test full names (including Describe/Context/It path) to run. +Equivalent to ConfigurationProperty Filter.FullName. ```yaml Type: String[] -Parameter Sets: Simple, Legacy -Aliases: Name +Parameter Sets: Simple +Aliases: Required: False Position: Named @@ -229,14 +211,12 @@ Accept wildcard characters: False ### -CI -(Introduced v5) Enable Test Results and Exit after Run. -Replace with ConfigurationProperty +Equivalent to setting: TestResult.Enabled = $true Run.Exit = $true -Since 5.2.0, this option no longer enables CodeCoverage. To also enable CodeCoverage use this configuration option: CodeCoverage.Enabled = $true @@ -254,9 +234,9 @@ Accept wildcard characters: False ### -Output -(Deprecated v4) -Replace with ConfigurationProperty Output.Verbosity -Supports Diagnostic, Detailed, Normal, Minimal, None +Specifies the verbosity of the test output. +Supports Diagnostic, Detailed, Normal, Minimal, None. +Equivalent to ConfigurationProperty Output.Verbosity. Default value is: Normal @@ -274,16 +254,16 @@ Accept wildcard characters: False ### -PassThru -Replace with ConfigurationProperty Run.PassThru -Returns a custom object (PSCustomObject) that contains the test results. +Returns a [Pester.Run] object that contains the test results. By default, Invoke-Pester writes to the host program, not to the output stream (stdout). If you try to save the result in a variable, the variable is empty unless you use the PassThru parameter. -To suppress the host output, use the Show parameter set to None. +Equivalent to ConfigurationProperty Run.PassThru. +To suppress the host output, use the Output parameter with value None. ```yaml Type: SwitchParameter -Parameter Sets: Simple, Legacy +Parameter Sets: Simple Aliases: Required: False @@ -330,296 +310,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -EnableExit - -(Deprecated v4) -Replace with ConfigurationProperty Run.Exit -Will cause Invoke-Pester to exit with a exit code equal to the number of failed -tests once all tests have been run. -Use this to "fail" a build when any tests fail. - -```yaml -Type: SwitchParameter -Parameter Sets: Legacy -Aliases: - -Required: False -Position: 3 -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -CodeCoverage - -(Deprecated v4) -Replace with ConfigurationProperty CodeCoverage.Enabled = $true -Adds a code coverage report to the Pester tests. -Takes strings or hash table values. -A code coverage report lists the lines of code that did and did not run during -a Pester test. -This report does not tell whether code was tested; only whether -the code ran during the test. -By default, the code coverage report is written to the host program -(like Write-Host). -When you use the PassThru parameter, the custom object -that Invoke-Pester returns has an additional CodeCoverage property that contains -a custom object with detailed results of the code coverage test, including lines -hit, lines missed, and helpful statistics. -However, NUnitXml and JUnitXml output (OutputXML, OutputFormat) do not include -any code coverage information, because it's not supported by the schema. -Enter the path to the files of code under test (not the test file). -Wildcard characters are supported. -If you omit the path, the default is local -directory, not the directory specified by the Script parameter. -Pester test files -are by default excluded from code coverage when a directory is provided. -When you -provide a test file directly using string, code coverage will be measured. -To include -tests in code coverage of a directory, use the dictionary syntax and provide -IncludeTests = $true option, as shown below. -To run a code coverage test only on selected classes, functions or lines in a script, -enter a hash table value with the following keys: --- Path (P)(mandatory) <string>: Enter one path to the files. -Wildcard characters -are supported, but only one string is permitted. --- IncludeTests <bool>: Includes code coverage for Pester test files (*.tests.ps1). -Default is false. -One of the following: Class/Function or StartLine/EndLine --- Class (C) <string>: Enter the class name. -Wildcard characters are -supported, but only one string is permitted. -Default is *. --- Function (F) <string>: Enter the function name. -Wildcard characters are -supported, but only one string is permitted. -Default is *. --or- --- StartLine (S): Performs code coverage analysis beginning with the specified -line. -Default is line 1. --- EndLine (E): Performs code coverage analysis ending with the specified line. -Default is the last line of the script. - -```yaml -Type: Object[] -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: @() -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -CodeCoverageOutputFile - -(Deprecated v4) -Replace with ConfigurationProperty CodeCoverage.OutputPath -The path where Invoke-Pester will save formatted code coverage results file. -The path must include the location and name of the folder and file name with -a required extension (usually the xml). -If this path is not provided, no file will be generated. - -```yaml -Type: String -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -CodeCoverageOutputFileEncoding - -(Deprecated v4) -Replace with ConfigurationProperty CodeCoverage.OutputEncoding -Sets the output encoding of CodeCoverageOutputFileFormat -Default is utf8 - -```yaml -Type: String -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: Utf8 -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -CodeCoverageOutputFileFormat - -(Deprecated v4) -Replace with ConfigurationProperty CodeCoverage.OutputFormat -The name of a code coverage report file format. -Default value is: JaCoCo. -Currently supported formats are: -- JaCoCo - this XML file format is compatible with Azure Devops, VSTS/TFS - -The ReportGenerator tool can be used to consolidate multiple reports and provide code coverage reporting. -https://github.com/danielpalme/ReportGenerator - -```yaml -Type: String -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: JaCoCo -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Strict - -(Deprecated v4) -Makes Skipped tests to Failed tests. -Useful for continuous -integration where you need to make sure all tests passed. - -```yaml -Type: SwitchParameter -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -OutputFile - -(Deprecated v4) -Replace with ConfigurationProperty TestResult.OutputPath -The path where Invoke-Pester will save formatted test results log file. -The path must include the location and name of the folder and file name with -the xml extension. -If this path is not provided, no log will be generated. - -```yaml -Type: String -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -OutputFormat - -(Deprecated v4) -Replace with ConfigurationProperty TestResult.OutputFormat -The format of output. -Currently NUnitXml and JUnitXml is supported. - -```yaml -Type: String -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: NUnitXml -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Quiet - -(Deprecated v4) -The parameter Quiet is deprecated since Pester v4.0 and will be deleted -in the next major version of Pester. -Please use the parameter Show -with value 'None' instead. -The parameter Quiet suppresses the output that Pester writes to the host program, -including the result summary and CodeCoverage output. -This parameter does not affect the PassThru custom object or the XML output that -is written when you use the Output parameters. - -```yaml -Type: SwitchParameter -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -PesterOption - -(Deprecated v4) -This parameter is ignored in v5, and is only present for backwards compatibility -when migrating from v4. - -```yaml -Type: Object -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -Show - -(Deprecated v4) -Replace with ConfigurationProperty Output.Verbosity -Customizes the output Pester writes to the screen. -Available options are None, Default, -Passed, Failed, Skipped, Inconclusive, Describe, Context, Summary, Header, All, Fails. -The options can be combined to define presets. -ConfigurationProperty Output.Verbosity supports the following values: -None -Minimal -Normal -Detailed -Diagnostic - -Show parameter supports the following parameter values: -None - (None) to write no output to the screen. -All - (Detailed) to write all available information (this is default option). -Default - (Detailed) -Detailed - (Detailed) -Fails - (Normal) to write everything except Passed (but including Describes etc.). -Diagnostic - (Diagnostic) -Normal - (Normal) -Minimal - (Minimal) - -A common setting is also Failed, Summary, to write only failed tests and test summary. -This parameter does not affect the PassThru custom object or the XML output that -is written when you use the Output parameters. - -```yaml -Type: String -Parameter Sets: Legacy -Aliases: - -Required: False -Position: Named -Default value: All -Accept pipeline input: False -Accept wildcard characters: False -``` - ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -640,4 +330,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/It.mdx b/docs/commands/It.mdx index 0d8b1f7..31ffe3b 100644 --- a/docs/commands/It.mdx +++ b/docs/commands/It.mdx @@ -253,4 +253,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Mock.mdx b/docs/commands/Mock.mdx index 25ab037..1d23790 100644 --- a/docs/commands/Mock.mdx +++ b/docs/commands/Mock.mdx @@ -40,8 +40,7 @@ Optionally, you may create a Parameter Filter which will examine the parameters passed to the mocked command and will invoke the mocked behavior only if the values of the parameter values pass the filter. If -they do not, the original command implementation will be invoked instead -of a mock. +they do not, and there is no default mock, the call will throw. You may create multiple mocks for the same command, each using a different ParameterFilter. @@ -339,4 +338,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/New-Fixture.mdx b/docs/commands/New-Fixture.mdx index 444e9e3..9e66d56 100644 --- a/docs/commands/New-Fixture.mdx +++ b/docs/commands/New-Fixture.mdx @@ -144,4 +144,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/New-MockObject.mdx b/docs/commands/New-MockObject.mdx index 5eda8ca..1688d47 100644 --- a/docs/commands/New-MockObject.mdx +++ b/docs/commands/New-MockObject.mdx @@ -48,6 +48,10 @@ An .NET assembly for the particular type must be available in the system and loa ```powershell $obj = New-MockObject -Type 'System.Diagnostics.Process' +$obj.GetType().FullName + System.Diagnostics.Process + +$obj = New-MockObject -Type ([System.Diagnostics.Process]) $obj.GetType().FullName System.Diagnostics.Process ``` @@ -83,6 +87,18 @@ Create a mock of a process-object and mocks the object's `Kill()`-method. The mocked method will keep a history of any call and the associated arguments in a property named `_Kill` +### EXAMPLE 4 + +```powershell +$someObj = Get-ObjectFromModule +$mock = New-MockObject -Type $someObj.GetType() +$mock.GetType().FullName + .MyInternalClass +``` + +Create a mock by providing a TypeInfo, e.g. +to mock output using an internal module class. + ## PARAMETERS ### -Type @@ -194,4 +210,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/New-PesterConfiguration.mdx b/docs/commands/New-PesterConfiguration.mdx index c472a4c..117a982 100644 --- a/docs/commands/New-PesterConfiguration.mdx +++ b/docs/commands/New-PesterConfiguration.mdx @@ -121,4 +121,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/New-PesterContainer.mdx b/docs/commands/New-PesterContainer.mdx index ce3f040..ad31710 100644 --- a/docs/commands/New-PesterContainer.mdx +++ b/docs/commands/New-PesterContainer.mdx @@ -25,13 +25,15 @@ Generates ContainerInfo-objects used as for Invoke-Pester -Container ### Path (Default) ```powershell -New-PesterContainer -Path [-Data ] [] +New-PesterContainer -Path [-Data ] + [] ``` ### ScriptBlock ```powershell -New-PesterContainer -ScriptBlock [-Data ] [] +New-PesterContainer -ScriptBlock [-Data ] + [] ``` ## DESCRIPTION @@ -154,4 +156,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Set-ItResult.mdx b/docs/commands/Set-ItResult.mdx index 7b53738..f4fea73 100644 --- a/docs/commands/Set-ItResult.mdx +++ b/docs/commands/Set-ItResult.mdx @@ -60,8 +60,8 @@ the output should be ``` Describing Example - [?] Inconclusive test is inconclusive, because we want it to be inconclusive 35ms (32ms|3ms) - [!] Skipped test is skipped, because we want it to be skipped 3ms (2ms|1ms) + [?] Inconclusive test is inconclusive, because we want it to be inconclusive 35ms + [!] Skipped test is skipped, because we want it to be skipped 3ms Tests completed in 78ms Tests Passed: 0, Failed: 0, Skipped: 1, Inconclusive: 1, NotRun: 0 ``` @@ -136,4 +136,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-All.mdx b/docs/commands/Should-All.mdx index a63c1b1..9148437 100644 --- a/docs/commands/Should-All.mdx +++ b/docs/commands/Should-All.mdx @@ -24,12 +24,14 @@ If the filter returns true, or does not throw for all the items in the collectio ## SYNTAX ```powershell -Should-All [[-Actual] ] [-FilterScript] [-Because ] [] +Should-All [[-Actual] ] [-FilterScript] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion runs the filter script against every item in the collection. +Nested Should-* failures are treated as filter failures and included in the reported reasons. ## EXAMPLES @@ -120,4 +122,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-Any.mdx b/docs/commands/Should-Any.mdx index e9a9be0..b71ab0f 100644 --- a/docs/commands/Should-Any.mdx +++ b/docs/commands/Should-Any.mdx @@ -24,12 +24,14 @@ If the filter returns true, or does not throw for any of the items in the collec ## SYNTAX ```powershell -Should-Any [[-Actual] ] [-FilterScript] [-Because ] [] +Should-Any [[-Actual] ] [-FilterScript] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion runs the filter script against each item until one passes. +Nested Should-* failures are treated as filter failures and included in the reported reasons when nothing matches. ## EXAMPLES @@ -121,4 +123,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-Be.mdx b/docs/commands/Should-Be.mdx index 91a2d57..b267bfd 100644 --- a/docs/commands/Should-Be.mdx +++ b/docs/commands/Should-Be.mdx @@ -23,12 +23,14 @@ Compares the expected value to actual value, to see if they are equal. ## SYNTAX ```powershell -Should-Be [[-Actual] ] [-Expected] [-Because ] [] +Should-Be [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion compares values using PowerShell equality semantics. +Use the collection-specific assertions when you need to compare arrays or other collections. ## EXAMPLES @@ -109,4 +111,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeAfter.mdx b/docs/commands/Should-BeAfter.mdx index 5ef75d9..a715436 100644 --- a/docs/commands/Should-BeAfter.mdx +++ b/docs/commands/Should-BeAfter.mdx @@ -25,24 +25,35 @@ Asserts that the provided [datetime] is after the expected [datetime]. ### Now (Default) ```powershell -Should-BeAfter [[-Actual] ] [-Now] [] +Should-BeAfter [[-Actual] ] [-Now] [-Because ] + [] ``` -### Fluent +### FluentFromNow ```powershell -Should-BeAfter [[-Actual] ] [[-Time] ] [-Ago] [-FromNow] [] +Should-BeAfter [[-Actual] ] [[-Time] ] [-FromNow] [-Because ] + [] +``` + +### FluentAgo + +```powershell +Should-BeAfter [[-Actual] ] [[-Time] ] [-Ago] [-Because ] + [] ``` ### Expected ```powershell -Should-BeAfter [[-Actual] ] [[-Expected] ] [] +Should-BeAfter [[-Actual] ] [[-Expected] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion accepts either an expected `[datetime]` or a fluent relative time expression. +Use `-Now`, `-Ago`, or `-FromNow` to compare against the current local time. ## EXAMPLES @@ -106,7 +117,7 @@ Parameter Sets: Now Aliases: Required: False -Position: 1 +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -119,8 +130,8 @@ This parameter uses fluent time syntax e.g. 1minute. ```yaml -Type: Object -Parameter Sets: Fluent +Type: String +Parameter Sets: FluentFromNow, FluentAgo Aliases: Required: False @@ -136,11 +147,11 @@ Indicates that the -Time should be subtracted from the current time. ```yaml Type: SwitchParameter -Parameter Sets: Fluent +Parameter Sets: FluentAgo Aliases: -Required: False -Position: 2 +Required: True +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -152,11 +163,11 @@ Indicates that the -Time should be added to the current time. ```yaml Type: SwitchParameter -Parameter Sets: Fluent +Parameter Sets: FluentFromNow Aliases: -Required: False -Position: 2 +Required: True +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -178,6 +189,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Because + +The reason why the actual value should be after the expected value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -198,4 +225,4 @@ The `Should-BeAfter` assertion is the opposite of the `Should-BeBefore` assertio ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeBefore.mdx b/docs/commands/Should-BeBefore.mdx index 21f40d1..f7ae42a 100644 --- a/docs/commands/Should-BeBefore.mdx +++ b/docs/commands/Should-BeBefore.mdx @@ -25,24 +25,35 @@ Asserts that the provided [datetime] is before the expected [datetime]. ### Now (Default) ```powershell -Should-BeBefore [[-Actual] ] [-Now] [] +Should-BeBefore [[-Actual] ] [-Now] [-Because ] + [] ``` -### Fluent +### FluentFromNow ```powershell -Should-BeBefore [[-Actual] ] [[-Time] ] [-Ago] [-FromNow] [] +Should-BeBefore [[-Actual] ] [[-Time] ] [-FromNow] [-Because ] + [] +``` + +### FluentAgo + +```powershell +Should-BeBefore [[-Actual] ] [[-Time] ] [-Ago] [-Because ] + [] ``` ### Expected ```powershell -Should-BeBefore [[-Actual] ] [[-Expected] ] [] +Should-BeBefore [[-Actual] ] [[-Expected] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion accepts either an expected `[datetime]` or a fluent relative time expression. +Use `-Now`, `-Ago`, or `-FromNow` to compare against the current local time. ## EXAMPLES @@ -56,13 +67,12 @@ This assertion will pass, because the actual value is before the expected value. ### EXAMPLE 2 -``` ```powershell (Get-Date).AddDays(1) | Should-BeBefore (Get-Date) -```powershell -This assertion will fail, because the actual value is not before the expected value. ``` +This assertion will fail, because the actual value is not before the expected value. + ### EXAMPLE 3 ```powershell @@ -107,7 +117,7 @@ Parameter Sets: Now Aliases: Required: False -Position: 1 +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -120,8 +130,8 @@ This parameter uses fluent time syntax e.g. 1minute. ```yaml -Type: Object -Parameter Sets: Fluent +Type: String +Parameter Sets: FluentFromNow, FluentAgo Aliases: Required: False @@ -137,11 +147,11 @@ Indicates that the -Time should be subtracted from the current time. ```yaml Type: SwitchParameter -Parameter Sets: Fluent +Parameter Sets: FluentAgo Aliases: -Required: False -Position: 2 +Required: True +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -153,11 +163,11 @@ Indicates that the -Time should be added to the current time. ```yaml Type: SwitchParameter -Parameter Sets: Fluent +Parameter Sets: FluentFromNow Aliases: -Required: False -Position: 2 +Required: True +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -179,6 +189,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Because + +The reason why the actual value should be before the expected value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -199,4 +225,4 @@ The `Should-BeBefore` assertion is the opposite of the `Should-BeAfter` assertio ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeCollection.mdx b/docs/commands/Should-BeCollection.mdx index 986777e..4c0cab5 100644 --- a/docs/commands/Should-BeCollection.mdx +++ b/docs/commands/Should-BeCollection.mdx @@ -26,18 +26,21 @@ It does not compare the types of the input collections. ### Expected ```powershell -Should-BeCollection [[-Actual] ] [-Expected] [-Because ] [] +Should-BeCollection [[-Actual] ] [-Expected] [-Because ] + [] ``` ### Count ```powershell -Should-BeCollection [[-Actual] ] [-Because ] [-Count ] [] +Should-BeCollection [[-Actual] ] [-Because ] [-Count ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion verifies that both values are collections and compares their contents rather than their collection types. +When you use `-Count`, it only checks the number of items. ## EXAMPLES @@ -146,4 +149,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeEmptyString.mdx b/docs/commands/Should-BeEmptyString.mdx index 3d6a03f..b4c7327 100644 --- a/docs/commands/Should-BeEmptyString.mdx +++ b/docs/commands/Should-BeEmptyString.mdx @@ -23,12 +23,14 @@ Ensures that input is an empty string. ## SYNTAX ```powershell -Should-BeEmptyString [[-Actual] ] [-Because ] [] +Should-BeEmptyString [[-Actual] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion requires the actual value to be a string and uses `[string]::IsNullOrEmpty()` for the check. +`$null` and non-string values still fail the assertion. ## EXAMPLES @@ -113,4 +115,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeEquivalent.mdx b/docs/commands/Should-BeEquivalent.mdx index abb0a0a..4b874c5 100644 --- a/docs/commands/Should-BeEquivalent.mdx +++ b/docs/commands/Should-BeEquivalent.mdx @@ -29,57 +29,58 @@ Should-BeEquivalent [[-Actual] ] [-Expected] [-Because ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion performs a deep comparison of the actual and expected objects, recursing through nested properties and collections. +Use `-ExcludePath`, `-ExcludePathsNotOnExpected`, or `-Comparator Equality` to narrow what counts as equivalent. ## EXAMPLES ### EXAMPLE 1 -``` -```powershell - Should-BeEquivalent ... -ExcludePath 'Id', 'Timestamp' -Comparator 'Equality' ```powershell -This example generates an equivalency option object that excludes the 'Id' and 'Timestamp' properties from the comparison and uses a simple equality comparison strategy. +Should-BeEquivalent ... -ExcludePath 'Id', 'Timestamp' -Comparator 'Equality' ``` +This example generates an equivalency option object that excludes the 'Id' and 'Timestamp' properties from the comparison and uses a simple equality comparison strategy. + ### EXAMPLE 2 ``` ```powereshell - Should-BeEquivalent ... -ExcludePathsNotOnExpected +Should-BeEquivalent ... -ExcludePathsNotOnExpected +``` ```powershell + This example generates an equivalency option object that excludes any paths not present on the expected object from the comparison, using the default deep comparison strategy. -``` ### EXAMPLE 3 -```powershell - $expected = [PSCustomObject] @{ - Name = "Thomas" - } +``` +$expected = [PSCustomObject] @{ + Name = "Thomas" +} - $actual = [PSCustomObject] @{ - Name = "Jakub" - Age = 30 - } +$actual = [PSCustomObject] @{ + Name = "Jakub" + Age = 30 +} - $actual | Should-BeEquivalent $expected -``` +$actual | Should-BeEquivalent $expected +```powershell This will throw an error because the actual object has an additional property Age and the Name values are not equivalent. ### EXAMPLE 4 -```powershell - $expected = [PSCustomObject] @{ - Name = "Thomas" - } +``` +$expected = [PSCustomObject] @{ + Name = "Thomas" +} - $actual = [PSCustomObject] @{ - Name = "Thomas" - } +$actual = [PSCustomObject] @{ + Name = "Thomas" +} - $actual | Should-BeEquivalent $expected +$actual | Should-BeEquivalent $expected ``` This will pass because the actual object has the same properties as the expected object and the Name values are equivalent. @@ -205,4 +206,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeFalse.mdx b/docs/commands/Should-BeFalse.mdx index 927ada6..96f532f 100644 --- a/docs/commands/Should-BeFalse.mdx +++ b/docs/commands/Should-BeFalse.mdx @@ -24,12 +24,14 @@ It does not convert input values to boolean, and will fail for any value that is ## SYNTAX ```powershell -Should-BeFalse [[-Actual] ] [[-Because] ] [] +Should-BeFalse [[-Actual] ] [[-Because] ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion only passes for the Boolean value `$false. +It does not coerce input, so `$null, 0, or other falsy values still fail. ## EXAMPLES @@ -108,4 +110,4 @@ The `Should-BeFalse` assertion is the opposite of the `Should-BeTrue` assertion. ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeFalsy.mdx b/docs/commands/Should-BeFalsy.mdx index 313b415..0725684 100644 --- a/docs/commands/Should-BeFalsy.mdx +++ b/docs/commands/Should-BeFalsy.mdx @@ -24,12 +24,14 @@ It converts the input value to a boolean. ## SYNTAX ```powershell -Should-BeFalsy [[-Actual] ] [[-Because] ] [] +Should-BeFalsy [[-Actual] ] [[-Because] ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion evaluates the input using PowerShell truthiness rules. +It passes for values such as `$false, 0, `""`, `$null, and empty collections. ## EXAMPLES @@ -108,4 +110,4 @@ The `Should-BeFalsy` assertion is the opposite of the `Should-BeTruthy` assertio ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeFasterThan.mdx b/docs/commands/Should-BeFasterThan.mdx index be2e3cc..c43d51c 100644 --- a/docs/commands/Should-BeFasterThan.mdx +++ b/docs/commands/Should-BeFasterThan.mdx @@ -23,12 +23,14 @@ Asserts that the provided [timespan] or [scriptblock] is faster than the expecte ## SYNTAX ```powershell -Should-BeFasterThan [[-Actual] ] [[-Expected] ] [] +Should-BeFasterThan [[-Actual] ] [[-Expected] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion accepts either a `[timespan]` or a script block to measure. +Fluent time values such as `1s` are converted to a `[timespan]` before the comparison. ## EXAMPLES @@ -82,6 +84,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Because + +The reason why the actual value should be faster than the expected value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -102,4 +120,4 @@ The `Should-BeFasterThan` assertion is the opposite of the `Should-BeSlowerThan` ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeGreaterThan.mdx b/docs/commands/Should-BeGreaterThan.mdx index 459a5d9..07be753 100644 --- a/docs/commands/Should-BeGreaterThan.mdx +++ b/docs/commands/Should-BeGreaterThan.mdx @@ -23,12 +23,13 @@ Compares the expected value to actual value, to see if the actual value is great ## SYNTAX ```powershell -Should-BeGreaterThan [[-Actual] ] [-Expected] [-Because ] [] +Should-BeGreaterThan [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses PowerShell comparison semantics and passes only when the actual value is strictly greater than the expected value. ## EXAMPLES @@ -109,4 +110,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeGreaterThanOrEqual.mdx b/docs/commands/Should-BeGreaterThanOrEqual.mdx index 1c165a8..486e845 100644 --- a/docs/commands/Should-BeGreaterThanOrEqual.mdx +++ b/docs/commands/Should-BeGreaterThanOrEqual.mdx @@ -23,12 +23,13 @@ Compares the expected value to actual value, to see if the actual value is great ## SYNTAX ```powershell -Should-BeGreaterThanOrEqual [[-Actual] ] [-Expected] [-Because ] [] +Should-BeGreaterThanOrEqual [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses PowerShell comparison semantics and passes when the actual value is greater than or equal to the expected value. ## EXAMPLES @@ -109,4 +110,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeHashtable.mdx b/docs/commands/Should-BeHashtable.mdx new file mode 100644 index 0000000..74fde48 --- /dev/null +++ b/docs/commands/Should-BeHashtable.mdx @@ -0,0 +1,196 @@ +--- +id: Should-BeHashtable +title: Should-BeHashtable +description: Help page for the PowerShell Pester "Should-BeHashtable" command +keywords: + - PowerShell + - Pester + - Help + - Documentation +hide_title: false +hide_table_of_contents: false +custom_edit_url: null +--- + +:::info This page was generated +Contributions are welcome in [Pester-repo](https://github.com/pester/pester). +::: + +## SYNOPSIS + +Asserts that the input is a hashtable or dictionary, and optionally checks the number of +entries, whether it is ordered, and that it contains specific keys. + +## SYNTAX + +```powershell +Should-BeHashtable [[-Actual] ] [-Count ] [-Key ] [-Ordered] [-Because ] + [] +``` + +## DESCRIPTION + +`Should-BeHashtable` is a shape assertion. +It verifies that `$Actual` is a hashtable or +dictionary (anything implementing `System.Collections.IDictionary`, such as `@\{\}`, +`[ordered]@\{\}` or a generic `Dictionary[,]`). + +It does not compare the contents of the dictionary. +Use the optional parameters to assert on +the shape of the dictionary: + +- `-Count` checks the number of entries. +- `-Ordered` checks that the value is an ordered dictionary (`[ordered]@\{\}`). +- `-Key` checks that the given keys are present, ignoring their values. +When combined with + `-Ordered`, the keys must also appear in the given relative order. + +To compare the keys *and values* of a dictionary against an expected dictionary use +`Should-BeEquivalent` instead, which performs a deep, order-insensitive comparison. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +@{ Name = 'Jakub'; Age = 30 } | Should-BeHashtable +[ordered]@{ a = 1; b = 2 } | Should-BeHashtable +``` + +These assertions pass, because the actual value is a hashtable or dictionary. + +### EXAMPLE 2 + +```powershell +@{ Name = 'Jakub'; Age = 30 } | Should-BeHashtable -Count 2 +@{ Name = 'Jakub'; Age = 30 } | Should-BeHashtable -Key Name, Age +[ordered]@{ a = 1; b = 2 } | Should-BeHashtable -Ordered -Key a, b +``` + +These assertions pass. +The dictionary has two entries, it contains the keys `Name` and `Age`, +and the ordered dictionary contains the keys `a` and `b` in that order. + +### EXAMPLE 3 + +```powershell +@{ Name = 'Jakub' } | Should-BeHashtable -Ordered +@(1, 2, 3) | Should-BeHashtable +``` + +These assertions fail. +The first value is a plain (unordered) hashtable, and the second value +is a collection, not a hashtable. + +## PARAMETERS + +### -Actual + +The value to test. +It is expected to be a hashtable or dictionary. + +```yaml +Type: Object +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Count + +Checks that the dictionary has the expected number of entries. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Key + +Checks that the dictionary contains the given keys. +Only the presence of the keys is checked, +not their values. +When `-Ordered` is also specified, the keys must appear in the dictionary in +the same relative order as they are listed here. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Ordered + +Checks that the dictionary is an ordered dictionary (`System.Collections.Specialized.OrderedDictionary`), +as produced by `[ordered]@\{\}`. +A plain `[hashtable]` is unordered and fails this check. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Because + +The reason why the input should be a hashtable with the expected shape. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +`Should-BeHashtable` only asserts on the shape of the dictionary. +To compare its keys and +values against an expected dictionary, use `Should-BeEquivalent`. + +## RELATED LINKS + +[https://pester.dev/docs/commands/Should-BeHashtable](https://pester.dev/docs/commands/Should-BeHashtable) + +[https://pester.dev/docs/assertions](https://pester.dev/docs/assertions) + +## VERSION + +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeLessThan.mdx b/docs/commands/Should-BeLessThan.mdx index b544396..0aac85c 100644 --- a/docs/commands/Should-BeLessThan.mdx +++ b/docs/commands/Should-BeLessThan.mdx @@ -23,12 +23,13 @@ Compares the expected value to actual value, to see if the actual value is less ## SYNTAX ```powershell -Should-BeLessThan [[-Actual] ] [-Expected] [-Because ] [] +Should-BeLessThan [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses PowerShell comparison semantics and passes only when the actual value is strictly less than the expected value. ## EXAMPLES @@ -109,4 +110,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeLessThanOrEqual.mdx b/docs/commands/Should-BeLessThanOrEqual.mdx index 0019404..2b0f471 100644 --- a/docs/commands/Should-BeLessThanOrEqual.mdx +++ b/docs/commands/Should-BeLessThanOrEqual.mdx @@ -23,12 +23,13 @@ Compares the expected value to actual value, to see if the actual value is less ## SYNTAX ```powershell -Should-BeLessThanOrEqual [[-Actual] ] [-Expected] [-Because ] [] +Should-BeLessThanOrEqual [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses PowerShell comparison semantics and passes when the actual value is less than or equal to the expected value. ## EXAMPLES @@ -119,4 +120,4 @@ The `Should-BeLessThanOrEqual` assertion is the opposite of the `Should-BeGreate ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeLikeString.mdx b/docs/commands/Should-BeLikeString.mdx index 4cfa023..22a1abf 100644 --- a/docs/commands/Should-BeLikeString.mdx +++ b/docs/commands/Should-BeLikeString.mdx @@ -136,4 +136,4 @@ The `Should-BeLikeString` assertion is the opposite of the `Should-NotBeLikeStri ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeNull.mdx b/docs/commands/Should-BeNull.mdx index 53ca3d2..7a83c86 100644 --- a/docs/commands/Should-BeNull.mdx +++ b/docs/commands/Should-BeNull.mdx @@ -23,12 +23,14 @@ Asserts that the input is `$null`. ## SYNTAX ```powershell -Should-BeNull [[-Actual] ] [-Because ] [] +Should-BeNull [[-Actual] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion passes only when the actual value is exactly `$null. +Empty strings, empty collections, and other falsy values do not count as null. ## EXAMPLES @@ -92,4 +94,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeSame.mdx b/docs/commands/Should-BeSame.mdx index deb7ba0..8ede092 100644 --- a/docs/commands/Should-BeSame.mdx +++ b/docs/commands/Should-BeSame.mdx @@ -23,12 +23,14 @@ Compares the expected value to actual value, to see if they are the same instanc ## SYNTAX ```powershell -Should-BeSame [[-Actual] ] [-Expected] [-Because ] [] +Should-BeSame [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion checks reference equality rather than value equality. +Use it with reference types when you need to verify that both variables point to the same instance. ## EXAMPLES @@ -121,4 +123,4 @@ The `Should-BeSame` assertion is the opposite of the `Should-NotBeSame` assertio ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeSlowerThan.mdx b/docs/commands/Should-BeSlowerThan.mdx index 798b8a0..2e447fb 100644 --- a/docs/commands/Should-BeSlowerThan.mdx +++ b/docs/commands/Should-BeSlowerThan.mdx @@ -23,12 +23,14 @@ Asserts that the provided [timespan] is slower than the expected [timespan]. ## SYNTAX ```powershell -Should-BeSlowerThan [[-Actual] ] [[-Expected] ] [] +Should-BeSlowerThan [[-Actual] ] [[-Expected] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion accepts either a `[timespan]` or a script block to measure. +Fluent time values such as `1s` are converted to a `[timespan]` before the comparison. ## EXAMPLES @@ -90,6 +92,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Because + +The reason why the actual value should be slower than the expected value. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### CommonParameters This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). @@ -110,4 +128,4 @@ The `Should-BeSlowerThan` assertion is the opposite of the `Should-BeFasterThan` ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeString.mdx b/docs/commands/Should-BeString.mdx index 8a6fcbe..fa1b3f0 100644 --- a/docs/commands/Should-BeString.mdx +++ b/docs/commands/Should-BeString.mdx @@ -168,4 +168,4 @@ The `Should-BeString` assertion is the opposite of the `Should-NotBeString` asse ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeTrue.mdx b/docs/commands/Should-BeTrue.mdx index 6bcd589..7f35dba 100644 --- a/docs/commands/Should-BeTrue.mdx +++ b/docs/commands/Should-BeTrue.mdx @@ -24,12 +24,14 @@ It does not convert input values to boolean, and will fail for any value is not ## SYNTAX ```powershell -Should-BeTrue [[-Actual] ] [[-Because] ] [] +Should-BeTrue [[-Actual] ] [[-Because] ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion only passes for the Boolean value `$true. +It does not coerce input, so truthy non-Boolean values still fail. ## EXAMPLES @@ -108,4 +110,4 @@ The `Should-BeTrue` assertion is the opposite of the `Should-BeFalse` assertion. ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-BeTruthy.mdx b/docs/commands/Should-BeTruthy.mdx index 88e8237..5ac6218 100644 --- a/docs/commands/Should-BeTruthy.mdx +++ b/docs/commands/Should-BeTruthy.mdx @@ -24,12 +24,14 @@ It converts input values to boolean, and will fail for any value is not $true, o ## SYNTAX ```powershell -Should-BeTruthy [[-Actual] ] [[-Because] ] [] +Should-BeTruthy [[-Actual] ] [[-Because] ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion evaluates the input using PowerShell truthiness rules. +It passes for values that PowerShell treats as true, not just the Boolean `$true. ## EXAMPLES @@ -109,4 +111,4 @@ The `Should-BeTruthy` assertion is the opposite of the `Should-BeFalsy` assertio ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-ContainCollection.mdx b/docs/commands/Should-ContainCollection.mdx index 3049eca..b51af6b 100644 --- a/docs/commands/Should-ContainCollection.mdx +++ b/docs/commands/Should-ContainCollection.mdx @@ -24,12 +24,14 @@ It does not compare the types of the input collections. ## SYNTAX ```powershell -Should-ContainCollection [[-Actual] ] [-Expected] [-Because ] [] +Should-ContainCollection [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses PowerShell containment to check whether the actual collection contains the expected value. +The comparison uses the contained value's own equality semantics. ## EXAMPLES @@ -120,4 +122,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-HaveParameter.mdx b/docs/commands/Should-HaveParameter.mdx index 16f614b..df78d35 100644 --- a/docs/commands/Should-HaveParameter.mdx +++ b/docs/commands/Should-HaveParameter.mdx @@ -37,49 +37,11 @@ This assertion inspects command metadata and can also verify parameter details s ### EXAMPLE 1 ```powershell -Get-Command Invoke-WebRequest | Should-HaveParameter Uri -Type ([uri]) -Mandatory +Get-Command "Invoke-WebRequest" | Should -HaveParameter Uri -Mandatory ``` -This assertion passes, because `Invoke-WebRequest` has a mandatory `-Uri` parameter of type `[uri]`. - -### EXAMPLE 2 - -```powershell -function Get-Cat { - [CmdletBinding(DefaultParameterSetName = 'ByName')] - param( - [Parameter(ParameterSetName = 'ByName', Mandatory)] - [Alias('Id')] - [string] $Name, - - [Parameter(ParameterSetName = 'ByIndex', Mandatory)] - [int] $Index, - - [ValidateSet('Json', 'Xml')] - [string] $Format = 'Json' - ) -} - -Describe 'Get-Cat public contract' { - It 'requires a Name' { - Get-Command Get-Cat | Should-HaveParameter Name -Type ([string]) -Mandatory -Alias 'Id' - } - - It 'defaults Format to Json' { - Get-Command Get-Cat | Should-HaveParameter Format -Type ([string]) -DefaultValue 'Json' - } -} -``` - -A typical real-life use is locking down the public API of your own command. These assertions pass, because `-Name` is a mandatory `[string]` with the alias `Id`, and `-Format` is an optional `[string]` that defaults to `Json`. - -### EXAMPLE 3 - -```powershell -Get-Command Get-Cat | Should-HaveParameter Index -InParameterSet 'ByIndex' -``` - -This assertion passes, because the `-Index` parameter (from the `Get-Cat` function above) belongs to the `ByIndex` parameter set. +This test passes, because it expected the parameter URI to exist and to +be mandatory. ## PARAMETERS @@ -258,4 +220,4 @@ if the attribute does not exist. ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-HaveType.mdx b/docs/commands/Should-HaveType.mdx index 458b94d..35d73f0 100644 --- a/docs/commands/Should-HaveType.mdx +++ b/docs/commands/Should-HaveType.mdx @@ -23,12 +23,14 @@ Asserts that the input is of the expected type. ## SYNTAX ```powershell -Should-HaveType [[-Actual] ] [-Expected] [-Because ] [] +Should-HaveType [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses `-is` to verify that the actual value is assignable to the expected type. +Derived types and implemented interfaces also satisfy the check. ## EXAMPLES @@ -109,4 +111,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-Invoke.mdx b/docs/commands/Should-Invoke.mdx index 6a9c1dc..5e7dce6 100644 --- a/docs/commands/Should-Invoke.mdx +++ b/docs/commands/Should-Invoke.mdx @@ -55,94 +55,100 @@ passed to Should-Invoke, Should-Invoke will throw an exception. ### EXAMPLE 1 ```powershell -function Save-Report ($Path, $Content) { - Set-Content -Path $Path -Value $Content -} - -Describe 'Save-Report' { - It 'writes the report to disk' { - Mock Set-Content +Mock Set-Content {} - Save-Report -Path 'report.txt' -Content 'All systems green' +{... +Some Code ...} - Should-Invoke Set-Content -Times 1 -Exactly - } -} +Should-Invoke Set-Content ``` -Asserts that `Save-Report` wrote to disk by calling the mocked `Set-Content` exactly once. The test fails if `Set-Content` was not called, or was called more than once. +This will throw an exception and cause the test to fail if Set-Content is not called in Some Code. ### EXAMPLE 2 ```powershell -Mock Set-Content +Mock Set-Content -parameterFilter {$path.StartsWith("$env:temp\")} -Save-Report -Path 'report.txt' -Content 'All systems green' +{... +Some Code ...} -Should-Invoke Set-Content -ParameterFilter { $Path -eq 'report.txt' } +Should-Invoke Set-Content 2 { $path -eq "$env:temp\test.txt" } ``` -Only the calls where `-Path` was `report.txt` are counted. The assertion passes, because `Save-Report` wrote to that path. +This will throw an exception if some code calls Set-Content on $path=$env:temp\test.txt less than 2 times ### EXAMPLE 3 ```powershell -function Get-Weather ($City) { - Invoke-RestMethod -Uri "https://api.example.com/weather?city=$City" -} +Mock Set-Content {} -Mock Invoke-RestMethod +{... +Some Code ...} -Get-Weather -City 'Oslo' - -Should-Invoke Invoke-RestMethod -Times 1 -Exactly -ParameterFilter { $Uri -match 'city=Oslo' } +Should-Invoke Set-Content 0 ``` -Asserts that the weather API was queried exactly once, and that the request was made for the city of Oslo. +This will throw an exception if some code calls Set-Content at all ### EXAMPLE 4 ```powershell -Describe 'Save-Report' { - BeforeAll { Mock Set-Content } +Mock Set-Content {} +``` - It 'writes exactly once per call' { - Save-Report -Path 'a.txt' -Content 'x' +\{... +Some Code ...\} - Should-Invoke Set-Content -Times 1 -Exactly -Scope It - } -} -``` +Should-Invoke Set-Content -Exactly 2 -`-Scope It` counts only the calls made in the current `It` block, even though the mock is shared by the whole `Describe`. +This will throw an exception if some code does not call Set-Content Exactly two times. ### EXAMPLE 5 ```powershell -Describe 'Publish-Thing' { - It 'writes from inside the module' { - Mock -ModuleName Toolbox Set-Content +Describe 'Should-Invoke Scope behavior' { + Mock Set-Content { } - Publish-Thing + It 'Calls Set-Content at least once in the It block' { + {... +Some Code ...} - Should-Invoke -ModuleName Toolbox Set-Content -Times 1 -Exactly + Should-Invoke Set-Content -Exactly 0 -Scope It } } ``` -When the command under test lives in a module, both `Mock` and `Should-Invoke` must use the same `-ModuleName` so the recorded call is found. +Checks for calls only within the current It block. ### EXAMPLE 6 ```powershell -Mock Remove-Item +Describe 'Describe' { + Mock -ModuleName SomeModule Set-Content { } + +{... +Some Code ...} + + It 'Calls Set-Content at least once in the Describe block' { + Should-Invoke -ModuleName SomeModule Set-Content + } +} +``` -Remove-TempFile -Path "$env:TEMP/old.log" +Checks for calls to the mock within the SomeModule module. +Note that both the Mock +and Should-Invoke commands use the same module name. -Should-Invoke Remove-Item -ExclusiveFilter { $Path -like "$env:TEMP*" } +### EXAMPLE 7 + +```powershell +Should-Invoke Get-ChildItem -ExclusiveFilter { $Path -eq 'C:\' } ``` -`-ExclusiveFilter` passes only if *every* recorded call matches the filter. Here it asserts that `Remove-Item` was called at least once, and only ever for paths inside the temp folder. It is a shorthand for pairing a `Should-Invoke` and a `Should-NotInvoke`. +Checks to make sure that Get-ChildItem was called at least one time with +the -Path parameter set to 'C:\', and that it was not called at all with +the -Path parameter set to any other value. ## PARAMETERS @@ -357,4 +363,4 @@ to the original. ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-MatchString.mdx b/docs/commands/Should-MatchString.mdx index 487a92d..b5ae273 100644 --- a/docs/commands/Should-MatchString.mdx +++ b/docs/commands/Should-MatchString.mdx @@ -37,26 +37,18 @@ The `-match` operator is case-insensitive by default, but you can make it case-s ### EXAMPLE 1 ```powershell -(New-Guid).Guid | Should-MatchString '^[0-9a-f-]{36}$' +"hello" | Should-MatchString "h.*o" ``` -This assertion passes, because a GUID is made up of 36 lowercase hexadecimal and dash characters. +This assertion will pass, because the actual value matches the regular expression pattern. ### EXAMPLE 2 ```powershell -'user-4f2a' | Should-MatchString '^user-[0-9a-f]{4}$' +"hello" | Should-MatchString "H.*O" -CaseSensitive ``` -This assertion passes, because the generated id matches the expected `user-` prefix followed by four hexadecimal characters. This is handy for checking that a function returns ids, tokens or file names in the format you expect. - -### EXAMPLE 3 - -```powershell -'Pester 6.0.0' | Should-MatchString 'pester \d+\.\d+\.\d+' -CaseSensitive -``` - -This assertion fails, because with `-CaseSensitive` the lowercase `pester` in the pattern does not match the capitalized `Pester` in the actual value. +This assertion will fail, because the actual value does not case-sensitively match the regular expression pattern. ## PARAMETERS @@ -142,4 +134,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotBe.mdx b/docs/commands/Should-NotBe.mdx index 3f26413..4a4dcee 100644 --- a/docs/commands/Should-NotBe.mdx +++ b/docs/commands/Should-NotBe.mdx @@ -23,12 +23,14 @@ Compares the expected value to actual value, to see if they are not equal. ## SYNTAX ```powershell -Should-NotBe [[-Actual] ] [-Expected] [-Because ] [] +Should-NotBe [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion compares values using PowerShell equality semantics and passes only when they are different. +Use the collection-specific assertions when you need to compare arrays or other collections. ## EXAMPLES @@ -109,4 +111,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotBeEmptyString.mdx b/docs/commands/Should-NotBeEmptyString.mdx index dc40db2..d186245 100644 --- a/docs/commands/Should-NotBeEmptyString.mdx +++ b/docs/commands/Should-NotBeEmptyString.mdx @@ -23,12 +23,14 @@ Ensures that the input is a string, and that the input is not $null or empty str ## SYNTAX ```powershell -Should-NotBeEmptyString [[-Actual] ] [-Because ] [] +Should-NotBeEmptyString [[-Actual] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion requires the actual value to be a string and fails for `$null, `""`, and non-string values. +Use it when empty should not be accepted as a valid string value. ## EXAMPLES @@ -113,4 +115,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotBeLikeString.mdx b/docs/commands/Should-NotBeLikeString.mdx index 22f40ec..7097da0 100644 --- a/docs/commands/Should-NotBeLikeString.mdx +++ b/docs/commands/Should-NotBeLikeString.mdx @@ -136,4 +136,4 @@ The `Should-NotBeLikeString` assertion is the opposite of the `Should-BeLikeStri ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotBeNull.mdx b/docs/commands/Should-NotBeNull.mdx index 693b6c8..c632cb2 100644 --- a/docs/commands/Should-NotBeNull.mdx +++ b/docs/commands/Should-NotBeNull.mdx @@ -23,12 +23,14 @@ Asserts that the input is not `$null`. ## SYNTAX ```powershell -Should-NotBeNull [[-Actual] ] [-Because ] [] +Should-NotBeNull [[-Actual] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion passes for any value other than exactly `$null. +Empty strings, empty collections, and other falsy values are not treated as null. ## EXAMPLES @@ -93,4 +95,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotBeSame.mdx b/docs/commands/Should-NotBeSame.mdx index 7f358f8..7a6c568 100644 --- a/docs/commands/Should-NotBeSame.mdx +++ b/docs/commands/Should-NotBeSame.mdx @@ -23,25 +23,26 @@ Compares the expected value to actual value, to see if the actual value is not t ## SYNTAX ```powershell -Should-NotBeSame [[-Actual] ] [-Expected] [-Because ] [] +Should-NotBeSame [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion checks reference inequality rather than value inequality. +It passes when the two values are different instances, even if their contents are equal. ## EXAMPLES ### EXAMPLE 1 -``` ```powershell $object = New-Object -TypeName PSObject $object | Should-NotBeSame $object -```powershell -This assertion will pass, because the actual value is not the same instance as the expected value. ``` +This assertion will pass, because the actual value is not the same instance as the expected value. + ### EXAMPLE 2 ```powershell @@ -121,4 +122,4 @@ The `Should-NotBeSame` assertion is the opposite of the `Should-BeSame` assertio ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotBeString.mdx b/docs/commands/Should-NotBeString.mdx index 5a8bfa5..162820f 100644 --- a/docs/commands/Should-NotBeString.mdx +++ b/docs/commands/Should-NotBeString.mdx @@ -36,22 +36,20 @@ The `-ne` operator is case-insensitive by default, but you can make it case-sens ### EXAMPLE 1 -``` ```powershell "hello" | Should-NotBeString "HELLO" -```powershell -This assertion will pass, because the actual value is not equal to the expected value. ``` +This assertion will pass, because the actual value is not equal to the expected value. + ### EXAMPLE 2 -``` ```powershell "hello" | Should-NotBeString "hello" -CaseSensitive -```powershell -This assertion will fail, because the actual value is equal to the expected value. ``` +This assertion will fail, because the actual value is equal to the expected value. + ## PARAMETERS ### -Actual @@ -154,4 +152,4 @@ The `Should-NotBeString` assertion is the opposite of the `Should-BeString` asse ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotBeWhiteSpaceString.mdx b/docs/commands/Should-NotBeWhiteSpaceString.mdx index 7b0f89e..fffd203 100644 --- a/docs/commands/Should-NotBeWhiteSpaceString.mdx +++ b/docs/commands/Should-NotBeWhiteSpaceString.mdx @@ -23,12 +23,14 @@ Ensures that the input is a string, and that the input is not $null, empty, or w ## SYNTAX ```powershell -Should-NotBeWhiteSpaceString [[-Actual] ] [-Because ] [] +Should-NotBeWhiteSpaceString [[-Actual] ] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion requires a string that contains at least one non-whitespace character. +It fails for `$null, `""`, whitespace-only strings, and non-string values. ## EXAMPLES @@ -114,4 +116,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotContainCollection.mdx b/docs/commands/Should-NotContainCollection.mdx index 5821eff..f9ab4ce 100644 --- a/docs/commands/Should-NotContainCollection.mdx +++ b/docs/commands/Should-NotContainCollection.mdx @@ -24,12 +24,14 @@ It does not compare the types of the input collections. ## SYNTAX ```powershell -Should-NotContainCollection [[-Actual] ] [-Expected] [-Because ] [] +Should-NotContainCollection [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses PowerShell containment to check that the actual collection does not contain the expected value. +The comparison uses the contained value's own equality semantics. ## EXAMPLES @@ -120,4 +122,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotHaveParameter.mdx b/docs/commands/Should-NotHaveParameter.mdx index d487e23..8c9883a 100644 --- a/docs/commands/Should-NotHaveParameter.mdx +++ b/docs/commands/Should-NotHaveParameter.mdx @@ -37,22 +37,10 @@ It only checks the parameter name, unlike `Should-HaveParameter`, which can also ### EXAMPLE 1 ```powershell -Get-Command Get-Date | Should-NotHaveParameter Uri +Get-Command "Invoke-WebRequest" | Should -NotHaveParameter Uri ``` -This assertion passes, because `Get-Date` has no `-Uri` parameter. - -### EXAMPLE 2 - -```powershell -function Get-PublicReport { - param([string] $Name) -} - -Get-Command Get-PublicReport | Should-NotHaveParameter Credential -``` - -This assertion passes, because `Get-PublicReport` does not expose a `-Credential` parameter. This is useful for guarding against accidentally adding parameters you want to keep off a command's public surface. +This test fails, because it expected the parameter URI to not exist. ## PARAMETERS @@ -118,6 +106,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES +The attribute [ArgumentCompleter] was added with PSv5. +Previously this +assertion will not be able to use the -HasArgumentCompleter parameter +if the attribute does not exist. + ## RELATED LINKS [https://pester.dev/docs/commands/Should-NotHaveParameter](https://pester.dev/docs/commands/Should-NotHaveParameter) @@ -126,4 +119,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotHaveType.mdx b/docs/commands/Should-NotHaveType.mdx index f04a7fc..631fa34 100644 --- a/docs/commands/Should-NotHaveType.mdx +++ b/docs/commands/Should-NotHaveType.mdx @@ -23,12 +23,14 @@ Asserts that the input is not of the expected type. ## SYNTAX ```powershell -Should-NotHaveType [[-Actual] ] [-Expected] [-Because ] [] +Should-NotHaveType [[-Actual] ] [-Expected] [-Because ] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion uses `-is` to verify that the actual value is not assignable to the expected type. +Derived types and implemented interfaces still count as the expected type. ## EXAMPLES @@ -111,4 +113,4 @@ This assertion is the opposite of `Should-HaveType`. ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotInvoke.mdx b/docs/commands/Should-NotInvoke.mdx index d1e8f59..ed5bb57 100644 --- a/docs/commands/Should-NotInvoke.mdx +++ b/docs/commands/Should-NotInvoke.mdx @@ -54,50 +54,100 @@ passed to Should-NotInvoke, Should-NotInvoke will throw an exception. ### EXAMPLE 1 ```powershell -function Remove-TempFile ($Path, [switch] $WhatIf) { - if (-not $WhatIf) { Remove-Item -Path $Path } -} +Mock Set-Content {} +``` + +\{... +Some Code ...\} -Describe 'Remove-TempFile' { - It 'does not delete anything in -WhatIf mode' { - Mock Remove-Item +Should-NotInvoke Set-Content - Remove-TempFile -Path 'temp.txt' -WhatIf +This will throw an exception and cause the test to fail if Set-Content is not called in Some Code. + +### EXAMPLE 2 - Should-NotInvoke Remove-Item - } -} +```powershell +Mock Set-Content -parameterFilter {$path.StartsWith("$env:temp\")} ``` -Because `-WhatIf` was passed, `Remove-TempFile` must not delete anything. The assertion passes when the mocked `Remove-Item` was never called, and throws (failing the test) if it was called. +\{... +Some Code ...\} -### EXAMPLE 2 +Should-NotInvoke Set-Content 2 \{ $path -eq "$env:temp\test.txt" \} + +This will throw an exception if some code calls Set-Content on $path=$env:temp\test.txt less than 2 times + +### EXAMPLE 3 ```powershell -Mock Remove-Item +Mock Set-Content {} +``` + +\{... +Some Code ...\} + +Should-NotInvoke Set-Content 0 -Remove-TempFile -Path "$env:TEMP/old.log" +This will throw an exception if some code calls Set-Content at all -Should-NotInvoke Remove-Item -ParameterFilter { $Path -notlike "$env:TEMP*" } +### EXAMPLE 4 + +```powershell +Mock Set-Content {} ``` -Only the calls whose `-Path` is outside the temp folder are counted. The assertion passes, because `Remove-TempFile` only ever deletes inside `$env:TEMP`. +\{... +Some Code ...\} -### EXAMPLE 3 +Should-NotInvoke Set-Content -Exactly 2 + +This will throw an exception if some code does not call Set-Content Exactly two times. + +### EXAMPLE 5 + +```powershell +Describe 'Should-NotInvoke Scope behavior' { + Mock Set-Content { } +``` + + It 'Calls Set-Content at least once in the It block' \{ + \{... +Some Code ...\} + + Should-NotInvoke Set-Content -Exactly 0 -Scope It + \} +\} + +Checks for calls only within the current It block. + +### EXAMPLE 6 ```powershell -Describe 'Remove-TempFile' { - BeforeAll { Mock Remove-Item } +Describe 'Describe' { + Mock -ModuleName SomeModule Set-Content { } +``` + +\{... +Some Code ...\} - It 'is a no-op in -WhatIf mode' { - Remove-TempFile -Path 'temp.txt' -WhatIf + It 'Calls Set-Content at least once in the Describe block' \{ + Should-NotInvoke -ModuleName SomeModule Set-Content + \} +\} - Should-NotInvoke Remove-Item -Scope It - } -} +Checks for calls to the mock within the SomeModule module. +Note that both the Mock +and Should-NotInvoke commands use the same module name. + +### EXAMPLE 7 + +```powershell +Should-NotInvoke Get-ChildItem -ExclusiveFilter { $Path -eq 'C:\' } ``` -`-Scope It` limits the check to calls made in the current `It` block, even when the mock is shared across the whole `Describe`. +Checks to make sure that Get-ChildItem was called at least one time with +the -Path parameter set to 'C:\', and that it was not called at all with +the -Path parameter set to any other value. ## PARAMETERS @@ -312,4 +362,4 @@ to the original. ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-NotMatchString.mdx b/docs/commands/Should-NotMatchString.mdx index 18b8d4e..2982d2f 100644 --- a/docs/commands/Should-NotMatchString.mdx +++ b/docs/commands/Should-NotMatchString.mdx @@ -37,26 +37,18 @@ The `-notmatch` operator is case-insensitive by default, but you can make it cas ### EXAMPLE 1 ```powershell -'Hello Jakub, your order #4821 shipped.' | Should-NotMatchString '\{\{.*?\}\}' +"hello" | Should-NotMatchString "^world$" ``` -This assertion passes, because the rendered text contains no leftover `{{ ... }}` template placeholders. This is a common check after expanding a template to make sure every token was replaced. +This assertion will pass, because the actual value does not match the regular expression pattern. ### EXAMPLE 2 ```powershell -'level=info msg="started"' | Should-NotMatchString 'password=' +"hello" | Should-NotMatchString "h.*o" -CaseSensitive ``` -This assertion passes, because the log line does not leak a `password=` value. - -### EXAMPLE 3 - -```powershell -'Build failed' | Should-NotMatchString 'failed' -CaseSensitive -``` - -This assertion fails, because the actual value case-sensitively contains `failed`. +This assertion will fail, because the actual value case-sensitively matches the regular expression pattern. ## PARAMETERS @@ -142,4 +134,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should-Throw.mdx b/docs/commands/Should-Throw.mdx index 0a6f8b7..e557852 100644 --- a/docs/commands/Should-Throw.mdx +++ b/docs/commands/Should-Throw.mdx @@ -24,12 +24,14 @@ Asserts that a script block throws an exception. ```powershell Should-Throw -ScriptBlock [[-ExceptionMessage] ] [[-FullyQualifiedErrorId] ] - [[-ExceptionType] ] [[-Because] ] [-AllowNonTerminatingError] [] + [[-ExceptionType] ] [[-Because] ] [-AllowNonTerminatingError] + [] ``` ## DESCRIPTION -\{\{ Fill in the Description \}\} +This assertion executes the script block and expects it to throw. +Optional filters let you match the exception type, message, or FullyQualifiedErrorId, and `-AllowNonTerminatingError` accepts non-terminating errors. ## EXAMPLES @@ -174,4 +176,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/Should.mdx b/docs/commands/Should.mdx index 45a9011..c400b12 100644 --- a/docs/commands/Should.mdx +++ b/docs/commands/Should.mdx @@ -25,180 +25,185 @@ Should is a keyword that is used to define an assertion inside an It block. ### Be ```powershell -Should [[-ActualValue] ] [-Be] [-Not] [-ExpectedValue ] [-Because ] - [] +Should [[-ActualValue] ] [-Be] [-Not] [-ExpectedValue ] + [-Because ] [] ``` ### BeExactly ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeExactly] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeExactly] [] ``` ### BeGreaterThan ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeGreaterThan] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeGreaterThan] [] ``` ### BeLessOrEqual ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeLessOrEqual] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeLessOrEqual] [] ``` ### BeIn ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeIn] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeIn] [] ``` ### BeLessThan ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeLessThan] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeLessThan] [] ``` ### BeGreaterOrEqual ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeGreaterOrEqual] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeGreaterOrEqual] [] ``` ### BeLike ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeLike] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeLike] [] ``` ### BeLikeExactly ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-BeLikeExactly] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-BeLikeExactly] [] ``` ### BeNullOrEmpty ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-BeNullOrEmpty] [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-BeNullOrEmpty] [] ``` ### BeOfType ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-BeOfType] [-ExpectedType ] - [] +Should [[-ActualValue] ] [-Not] [-Because ] [-BeOfType] + [-ExpectedType ] [] ``` ### BeTrue ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-BeTrue] [] +Should [[-ActualValue] ] [-Not] [-Because ] [-BeTrue] + [] ``` ### BeFalse ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-BeFalse] [] +Should [[-ActualValue] ] [-Not] [-Because ] [-BeFalse] + [] ``` ### Contain ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-Contain] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-Contain] [] ``` ### Exist ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-Exist] [] +Should [[-ActualValue] ] [-Not] [-Because ] [-Exist] + [-LiteralPath] [] ``` ### FileContentMatch ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-FileContentMatch] [-ExpectedContent ] - [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-FileContentMatch] [-ExpectedContent ] [] ``` ### FileContentMatchExactly ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-ExpectedContent ] - [-FileContentMatchExactly] [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-ExpectedContent ] [-FileContentMatchExactly] [] ``` ### FileContentMatchMultiline ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-ExpectedContent ] - [-FileContentMatchMultiline] [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-ExpectedContent ] [-FileContentMatchMultiline] [] ``` ### FileContentMatchMultilineExactly ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-ExpectedContent ] - [-FileContentMatchMultilineExactly] [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-ExpectedContent ] [-FileContentMatchMultilineExactly] [] ``` ### HaveCount ```powershell -Should [[-ActualValue] ] [-Not] [-ExpectedValue ] [-Because ] [-HaveCount] - [] +Should [[-ActualValue] ] [-Not] [-ExpectedValue ] + [-Because ] [-HaveCount] [] ``` ### HaveParameter ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-HaveParameter] [-ParameterName ] - [-Type ] [-DefaultValue ] [-Mandatory] [-InParameterSet ] [-HasArgumentCompleter] - [-Alias ] [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-HaveParameter] [-ParameterName ] [-Type ] [-DefaultValue ] [-Mandatory] + [-InParameterSet ] [-HasArgumentCompleter] [-Alias ] [] ``` ### Match ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-Match] [-RegularExpression ] - [] +Should [[-ActualValue] ] [-Not] [-Because ] [-Match] + [-RegularExpression ] [] ``` ### MatchExactly ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-RegularExpression ] [-MatchExactly] - [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-RegularExpression ] [-MatchExactly] [] ``` ### Throw ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-Throw] [-ExpectedMessage ] - [-ErrorId ] [-ExceptionType ] [-PassThru] [] +Should [[-ActualValue] ] [-Not] [-Because ] [-Throw] + [-ExpectedMessage ] [-ErrorId ] [-ExceptionType ] [-PassThru] [] ``` ### InvokeVerifiable ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-InvokeVerifiable] [] +Should [[-ActualValue] ] [-Not] [-Because ] + [-InvokeVerifiable] [] ``` ### Invoke ```powershell -Should [[-ActualValue] ] [-Not] [-Because ] [-Invoke] [-CommandName ] [-Times ] - [-ParameterFilter ] [-ExclusiveFilter ] [-ModuleName ] [-Scope ] [-Exactly] - [-CallerSessionState ] [] +Should [[-ActualValue] ] [-Not] [-Because ] [-Invoke] + [-CommandName ] [-Times ] [-ParameterFilter ] [-ExclusiveFilter ] + [-ModuleName ] [-Scope ] [-Exactly] [-CallerSessionState ] [] ``` ## DESCRIPTION @@ -943,6 +948,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -LiteralPath + +Depends on operator being used. +See `Get-ShouldOperator -Name ` or https://pester.dev/docs/assertions/ for help. + +```yaml +Type: SwitchParameter +Parameter Sets: Exist +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -Mandatory Depends on operator being used. @@ -1181,4 +1203,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## VERSION -*This page was generated using comment-based help in [Pester 6.0.0-alpha5](https://github.com/pester/pester).* +*This page was generated using comment-based help in [Pester 6.0.0-rc2](https://github.com/pester/pester).* diff --git a/docs/commands/docusaurus.sidebar.js b/docs/commands/docusaurus.sidebar.js index 7add25a..58ff74d 100644 --- a/docs/commands/docusaurus.sidebar.js +++ b/docs/commands/docusaurus.sidebar.js @@ -1,7 +1,7 @@ /** * Import this file in your Docusaurus `sidebars.js` file. * - * Auto-generated by Alt3.Docusaurus.Powershell 1.0.36. + * Auto-generated by Alt3.Docusaurus.Powershell 1.0.37. * * Copyright (c) 2019-present, ALT3 B.V. * @@ -45,6 +45,7 @@ module.exports = [ 'commands/Should-BeFasterThan', 'commands/Should-BeGreaterThan', 'commands/Should-BeGreaterThanOrEqual', + 'commands/Should-BeHashtable', 'commands/Should-BeLessThan', 'commands/Should-BeLessThanOrEqual', 'commands/Should-BeLikeString', diff --git a/docs/usage/configuration.mdx b/docs/usage/configuration.mdx index 8ca7955..3309981 100644 --- a/docs/usage/configuration.mdx +++ b/docs/usage/configuration.mdx @@ -27,7 +27,7 @@ Import-Module Pester # get default from static property $configuration = New-PesterConfiguration # adding properties & discover via intellisense -$configuration.Run.Path = 'C:\projects\tst' +$configuration.Run.Path = 'C:\MyProject\tests' $configuration.Filter.Tag = 'Acceptance' $configuration.Filter.ExcludeTag = 'WindowsOnly' $configuration.Should.ErrorAction = 'Continue' @@ -38,7 +38,7 @@ $configuration.CodeCoverage.Enabled = $true # cast whole hashtable to configuration $configuration = [PesterConfiguration]@{ Run = @{ - Path = 'C:\projects\tst' + Path = 'C:\MyProject\tests' } Filter = @{ Tag = 'Acceptance' @@ -56,7 +56,7 @@ $configuration = [PesterConfiguration]@{ ```powershell # cast from empty hashtable to get default $configuration = [PesterConfiguration]@{} -$configuration.Run.Path = 'C:\projects\tst' +$configuration.Run.Path = 'C:\MyProject\tests' # cast hashtable to section $configuration.Filter = @{ Tag = 'Acceptance' @@ -127,7 +127,7 @@ Tests Passed: 1, Failed: 0, Skipped: 0, Total: 1, NotRun: 0 -*This section was generated using Pester 6.0.0-alpha5.* +*This section was generated using Pester 6.0.0-rc2.* ### Run @@ -145,8 +145,12 @@ General runtime options for Pester including tests containers to execute. | Run.Throw | Throw an exception when test run fails. When used together with Exit, throwing an exception is preferred. | `bool` | `$false` | | Run.PassThru | Return result object to the pipeline after finishing the test run. | `bool` | `$false` | | Run.SkipRun | Runs the discovery phase but skips run. Use it with PassThru to get object populated with all tests. | `bool` | `$false` | +| Run.Parallel | EXPERIMENTAL: Run test files in parallel, each file in its own runspace, using PowerShell 7+ 'ForEach-Object -Parallel'. Files that contain the '#pester:no-parallel' directive run sequentially after the parallel batch. Falls back to a sequential run on Windows PowerShell 5.1, when non-file containers (ScriptBlock) are used, when CodeCoverage is enabled, or when Run.SkipRemainingOnFailure is set to 'Run'. | `bool` | `$false` | +| Run.BeforeContainer | EXPERIMENTAL: One or more ScriptBlocks run before each test file is discovered and run, in both sequential and parallel runs. Use it to import helper modules or dot-source setup that the parent session would normally provide, e.g. { . './setup.ps1' } - this is especially useful in parallel runs, where each worker starts from a clean runspace. One scriptblock is usually enough and can dot-source as many files as needed. When set, the convention file is ignored; when not set, Pester dot-sources a 'Pester.BeforeContainer.ps1' from the repository root (Run.RepoRoot) if one is present. | `scriptblock[]` | `@()` | +| Run.ParallelThrottleLimit | EXPERIMENTAL: Maximum number of test files to run at the same time when Run.Parallel is enabled, passed through to 'ForEach-Object -Parallel -ThrottleLimit'. The default 0 uses all available processors ([Environment]::ProcessorCount). Set a lower number to cap how many runspaces run concurrently. Only used when Run.Parallel is enabled. | `int` | `0` | | Run.SkipRemainingOnFailure | Skips remaining tests after failure for selected scope, options are None, Run, Container and Block. | `string` | `'None'` | | Run.FailOnNullOrEmptyForEach | Fails discovery when -ForEach is provided $null or @() in a block or test. Can be overridden for a specific Describe/Context/It using -AllowNullOrEmptyForEach. | `bool` | `$true` | +| Run.RepoRoot | Root directory of the repository. Found by searching for the .git directory recursively. When not found, the current working directory is used. | `string` | `'C:\MyProject'` | ### Filter @@ -171,7 +175,7 @@ Options to enable and configure Pester's code coverage feature. | Option | Description | Type | Default | |--------|-------------|-----:|--------:| | CodeCoverage.Enabled | Enable CodeCoverage. | `bool` | `$false` | -| CodeCoverage.OutputFormat | Format to use for code coverage report. Possible values: JaCoCo, CoverageGutters, Cobertura | `string` | `'JaCoCo'` | +| CodeCoverage.OutputFormat | Format to use for code coverage report. Possible values: JaCoCo, Cobertura | `string` | `'JaCoCo'` | | CodeCoverage.OutputPath | Path relative to the current directory where code coverage report is saved. | `string` | `'coverage.xml'` | | CodeCoverage.OutputEncoding | Encoding of the output file. | `string` | `'UTF8'` | | CodeCoverage.Path | Directories or files to be used for code coverage, by default the Path(s) from general settings are used, unless overridden here. | `string[]` | `@()` | @@ -180,6 +184,7 @@ Options to enable and configure Pester's code coverage feature. | CodeCoverage.CoveragePercentTarget | Target percent of code coverage that you want to achieve, default 75%. | `decimal` | `75` | | CodeCoverage.UseBreakpoints | When false, use Profiler based tracer to do CodeCoverage instead of using breakpoints. | `bool` | `$false` | | CodeCoverage.SingleHitBreakpoints | Remove breakpoint when it is hit. This increases performance of breakpoint based CodeCoverage. | `bool` | `$true` | +| CodeCoverage.ReportRoot | Root path for the code coverage report. Uses Run.RepoRoot by default. | `string` | `$null` | ### TestResult @@ -218,6 +223,7 @@ Debug configuration for Pester. ⚠ Use at your own risk! | Debug.WriteDebugMessages | Write Debug messages to screen. | `bool` | `$false` | | 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. | `string[]` | `@('Discovery', 'Skip', 'Mock', 'CodeCoverage')` | | Debug.ShowNavigationMarkers | Write paths after every block and test, for easy navigation in VSCode. | `bool` | `$false` | +| Debug.ShowStartMarkers | Write an indication when each test starts. | `bool` | `$false` | | Debug.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. | `bool` | `$false` | diff --git a/generate-command-reference.ps1 b/generate-command-reference.ps1 index 43798a1..6fc822a 100644 --- a/generate-command-reference.ps1 +++ b/generate-command-reference.ps1 @@ -119,6 +119,26 @@ if (Test-Path -Path $outputFolder) { Write-Host 'Generating new MDX files' -ForegroundColor Magenta New-DocusaurusHelp @docusaurusOptions +# ----------------------------------------------------------------------------- +# Strip the spurious ProgressAction common parameter that PlatyPS emits on +# PowerShell 7.4+ (https://github.com/PowerShell/platyPS/issues/663). Pester 6 +# loads a .NET 8 assembly and therefore requires PowerShell 7.4+, so the docs +# can no longer be generated on an older PowerShell to avoid this. Remove the +# parameter from the generated MDX instead. +# ----------------------------------------------------------------------------- +Write-Host 'Removing spurious ProgressAction parameter from generated MDX files' -ForegroundColor Magenta +$commandsFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar +Get-ChildItem -Path $commandsFolder -Filter '*.mdx' | ForEach-Object { + $content = Get-Content -LiteralPath $_.FullName -Raw + # Remove from the SYNTAX code-blocks, e.g. ` [-ProgressAction ]` + $updated = $content -replace ' \[-ProgressAction \]', '' + # Remove the dedicated '### -ProgressAction' section up to the next '### ' heading + $updated = $updated -replace '(?ms)^### -ProgressAction\r?\n.*?(?=^### )', '' + if ($updated -ne $content) { + Set-Content -LiteralPath $_.FullName -Value $updated -NoNewline -Encoding utf8 + } +} + Write-Host 'Render completed successfully' -BackgroundColor DarkGreen Pop-Location diff --git a/generate-pesterconfiguration-docs.ps1 b/generate-pesterconfiguration-docs.ps1 index 82ccd91..62860ab 100644 --- a/generate-pesterconfiguration-docs.ps1 +++ b/generate-pesterconfiguration-docs.ps1 @@ -13,7 +13,35 @@ param ( ) #region helpers + +# Some path-options (e.g. Run.RepoRoot) are resolved by New-PesterConfiguration at +# runtime to the absolute path of the repository the generator runs in. We must not +# bake that machine-specific build path into the published docs, so any default that +# points at the generator's own working directory is replaced with an illustrative +# placeholder repo root. We reuse 'C:\MyProject' to stay consistent with the +# Run.Path examples elsewhere on the Configuration page. +$repoRootPlaceholder = 'C:\MyProject' +$environmentPaths = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase) +foreach ($p in @($PSScriptRoot, (Get-Location).Path)) { + if (-not [string]::IsNullOrEmpty($p)) { + $null = $environmentPaths.Add($p.TrimEnd('/', '\')) + try { $null = $environmentPaths.Add([System.IO.Path]::GetFullPath($p).TrimEnd('/', '\')) } catch { } + } +} + +function Test-IsEnvironmentPath ($value) { + if ($value -is [string] -and -not [string]::IsNullOrEmpty($value)) { + $full = try { [System.IO.Path]::GetFullPath($value).TrimEnd('/', '\') } catch { $value.TrimEnd('/', '\') } + return ($environmentPaths.Contains($value.TrimEnd('/', '\')) -or $environmentPaths.Contains($full)) + } + return $false +} + function Format-NicelyMini ($value) { + if ($null -eq $value) { + return '$null' + } + if ($value -is [bool]) { if ($value) { '$true' @@ -56,8 +84,10 @@ function generateSectionsMarkdownAsTable { $options = foreach ($configOption in $section.PSObject.Properties) { $optionName = $configOption.Name $option = $configOption.Value - $default = Format-NicelyMini $option.Default - $type = $option.Default.GetType() -as [string] -replace '^Pester\.' + $rawDefault = $option.Default + if (Test-IsEnvironmentPath $rawDefault) { $rawDefault = $repoRootPlaceholder } + $default = Format-NicelyMini $rawDefault + $type = $option.GetType().GetProperty('Default').PropertyType -as [string] -replace '^Pester\.' "| $sectionName.$optionName | $($option.Description) | ``$type`` | ``$default`` |" } @@ -86,8 +116,10 @@ function generateSectionsMarkdownAsList { $options = foreach ($configOption in $section.PSObject.Properties) { $optionName = $configOption.Name $option = $configOption.Value - $default = Format-NicelyMini $option.Default - $type = $option.Default.GetType() -as [string] + $rawDefault = $option.Default + if (Test-IsEnvironmentPath $rawDefault) { $rawDefault = $repoRootPlaceholder } + $default = Format-NicelyMini $rawDefault + $type = $option.GetType().GetProperty('Default').PropertyType -as [string] @" #### $sectionName.$optionName From a572487b87661a6dc0d8e1edee9b6d96e1161f1e Mon Sep 17 00:00:00 2001 From: nohwnd Date: Tue, 30 Jun 2026 00:09:43 +0200 Subject: [PATCH 2/3] Repair mismatched example code fences in generated command docs Pester rc2's comment-based help embeds Markdown code fences (and a 'powereshell' typo) inside its .EXAMPLE blocks. PlatyPS double-wraps these into mismatched fences, which MDX 3 mispairs - it then tries to parse an example's PowerShell `@{ ... }` as a JSX expression and fails the Docusaurus build ("Could not parse expression with acorn"). Add a Repair-ExampleFences post-processing pass to generate-command-reference.ps1 that normalizes fences within the EXAMPLES section so every example renders as a single well-formed powershell code block, and regenerate the two affected files (Should-BeEquivalent, Set-ItResult). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/commands/Set-ItResult.mdx | 2 +- docs/commands/Should-BeEquivalent.mdx | 10 ++-- generate-command-reference.ps1 | 86 ++++++++++++++++++++++++++- 3 files changed, 88 insertions(+), 10 deletions(-) diff --git a/docs/commands/Set-ItResult.mdx b/docs/commands/Set-ItResult.mdx index 26338b4..6d70dc9 100644 --- a/docs/commands/Set-ItResult.mdx +++ b/docs/commands/Set-ItResult.mdx @@ -58,7 +58,7 @@ Describe "Example" { the output should be -``` +```powershell Describing Example [?] Inconclusive test is inconclusive, because we want it to be inconclusive 35ms [!] Skipped test is skipped, because we want it to be skipped 3ms diff --git a/docs/commands/Should-BeEquivalent.mdx b/docs/commands/Should-BeEquivalent.mdx index faf8f03..be50f73 100644 --- a/docs/commands/Should-BeEquivalent.mdx +++ b/docs/commands/Should-BeEquivalent.mdx @@ -44,17 +44,15 @@ This example generates an equivalency option object that excludes the 'Id' and ' ### EXAMPLE 2 -``` -```powereshell +```powershell Should-BeEquivalent ... -ExcludePathsNotOnExpected ``` -```powershell This example generates an equivalency option object that excludes any paths not present on the expected object from the comparison, using the default deep comparison strategy. ### EXAMPLE 3 -``` +```powershell $expected = [PSCustomObject] @{ Name = "Thomas" } @@ -65,13 +63,13 @@ $actual = [PSCustomObject] @{ } $actual | Should-BeEquivalent $expected -```powershell +``` This will throw an error because the actual object has an additional property Age and the Name values are not equivalent. ### EXAMPLE 4 -``` +```powershell $expected = [PSCustomObject] @{ Name = "Thomas" } diff --git a/generate-command-reference.ps1 b/generate-command-reference.ps1 index 196db4a..ecceb2e 100644 --- a/generate-command-reference.ps1 +++ b/generate-command-reference.ps1 @@ -119,6 +119,81 @@ if (Test-Path -Path $outputFolder) { Write-Host 'Generating new MDX files' -ForegroundColor Magenta New-DocusaurusHelp @docusaurusOptions +function Repair-ExampleFences { + <# + Pester's source comment-based help embeds Markdown code fences (```powershell + ... ```), including a 'powereshell' typo, inside its .EXAMPLE blocks. PlatyPS + double-wraps these, emitting mismatched fences - a bare ``` opening paired with + a ```powershell "closing" fence, sometimes doubled up. MDX 3 then mispairs the + fences, treating an example's PowerShell '@{ ... }' as a JSX expression, which + breaks the Docusaurus build ("Could not parse expression with acorn"). + + Normalize fences inside the EXAMPLES section only: collapse runs of adjacent + fence lines and alternate them open/close per example, so each example becomes a + single well-formed ```powershell code block followed by its description. The + SYNTAX and PARAMETERS sections (and their YAML blocks) are left untouched. + #> + param([string] $Content) + + $eol = if ($Content -match "`r`n") { "`r`n" } else { "`n" } + $lines = $Content -split "`r?`n" + + # Locate the EXAMPLES section: '## EXAMPLES' up to the next H2 heading. + $start = -1 + for ($i = 0; $i -lt $lines.Count; $i++) { + if ($lines[$i] -match '^##\s+EXAMPLES\s*$') { $start = $i; break } + } + if ($start -lt 0) { return $Content } + + $end = $lines.Count + for ($i = $start + 1; $i -lt $lines.Count; $i++) { + if ($lines[$i] -match '^##\s' -and $lines[$i] -notmatch '^###') { $end = $i; break } + } + + $result = [System.Collections.Generic.List[string]]::new() + $inCode = $false + $i = 0 + while ($i -lt $lines.Count) { + $line = $lines[$i] + + # Outside the EXAMPLES section: pass through unchanged. + if ($i -le $start -or $i -ge $end) { + if ($i -eq $end -and $inCode) { $result.Add('```'); $inCode = $false } + $result.Add($line); $i++; continue + } + + # A new example heading closes any block left open by the previous one. + if ($line -match '^###\s') { + if ($inCode) { $result.Add('```'); $inCode = $false } + $result.Add($line); $i++; continue + } + + # Collapse a run of adjacent fence lines into a single open or close fence. + if ($line -match '^\s{0,3}```') { + $langs = @() + while ($i -lt $end -and $lines[$i] -match '^\s{0,3}```(.*)$') { + $langs += $Matches[1].Trim() + $i++ + } + if (-not $inCode) { + $lang = $langs | Where-Object { $_ -ne '' } | Select-Object -First 1 + if (-not $lang -or $lang -eq 'powereshell') { $lang = 'powershell' } + $result.Add('```' + $lang) + $inCode = $true + } + else { + $result.Add('```') + $inCode = $false + } + continue + } + + $result.Add($line); $i++ + } + + return ($result -join $eol) +} + # ----------------------------------------------------------------------------- # Post-process the generated MDX: # * Strip the spurious ProgressAction common parameter that PlatyPS emits on @@ -128,11 +203,14 @@ New-DocusaurusHelp @docusaurusOptions # * Drop the '[]' entry from the SYNTAX blocks. It carries no # useful information for these commands and, on 7.4+, the longer ProgressAction # token made PlatyPS wrap it onto a dangling line of its own. -# The replacements allow the token to sit inline or, when PlatyPS wrapped the -# syntax line, on a continuation line of its own (optional leading line-break + +# * Repair the mismatched code fences PlatyPS emits for .EXAMPLE blocks that +# contain their own Markdown fences (see Repair-ExampleFences) so the MDX +# compiles. +# The first two replacements allow the token to sit inline or, when PlatyPS wrapped +# the syntax line, on a continuation line of its own (optional leading line-break + # indentation) so no blank or dangling line is left behind. # ----------------------------------------------------------------------------- -Write-Host 'Removing ProgressAction and [] from generated MDX files' -ForegroundColor Magenta +Write-Host 'Post-processing generated MDX files (ProgressAction, [], example fences)' -ForegroundColor Magenta $commandsFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar Get-ChildItem -Path $commandsFolder -Filter '*.mdx' | ForEach-Object { $content = Get-Content -LiteralPath $_.FullName -Raw @@ -142,6 +220,8 @@ Get-ChildItem -Path $commandsFolder -Filter '*.mdx' | ForEach-Object { $updated = $updated -replace '(?ms)^### -ProgressAction\r?\n.*?(?=^### )', '' # Remove ' []' from the SYNTAX code-blocks $updated = $updated -replace '[ ]*(\r?\n[ ]*)?\[\]', '' + # Fix mismatched code fences inside the EXAMPLES section + $updated = Repair-ExampleFences -Content $updated if ($updated -ne $content) { Set-Content -LiteralPath $_.FullName -Value $updated -NoNewline -Encoding utf8 } From b10ad3d4bfd092bcea524a18b0a112a9cc3a6ee5 Mon Sep 17 00:00:00 2001 From: nohwnd Date: Tue, 30 Jun 2026 09:21:29 +0200 Subject: [PATCH 3/3] Keep [] token and section; reflow when wrapped Restore the '[]' SYNTAX token and the '### CommonParameters' section that PlatyPS emits, instead of dropping them. Removing the spurious ProgressAction token (PlatyPS #663 on PowerShell 7.4+) can leave the token orphaned on a wrapped continuation line, so Format-SyntaxCommonParameters re-wraps it onto its own line only when the SYNTAX line would exceed PlatyPS's wrap width (~110 chars), matching the layout PlatyPS produces natively without ProgressAction. Regenerated all command docs for 6.0.0-rc2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/commands/Add-ShouldOperator.mdx | 2 +- docs/commands/AfterAll.mdx | 2 +- docs/commands/AfterEach.mdx | 2 +- docs/commands/BeforeAll.mdx | 2 +- docs/commands/BeforeDiscovery.mdx | 2 +- docs/commands/BeforeEach.mdx | 2 +- docs/commands/Context.mdx | 2 +- docs/commands/ConvertTo-JUnitReport.mdx | 2 +- docs/commands/ConvertTo-NUnitReport.mdx | 2 +- docs/commands/ConvertTo-Pester4Result.mdx | 2 +- docs/commands/Describe.mdx | 2 +- docs/commands/Export-JUnitReport.mdx | 2 +- docs/commands/Export-NUnitReport.mdx | 2 +- docs/commands/Get-ShouldOperator.mdx | 2 +- docs/commands/InModuleScope.mdx | 2 +- docs/commands/Invoke-Pester.mdx | 4 +- docs/commands/It.mdx | 3 +- docs/commands/Mock.mdx | 1 + docs/commands/New-Fixture.mdx | 2 +- docs/commands/New-MockObject.mdx | 3 +- docs/commands/New-PesterConfiguration.mdx | 2 +- docs/commands/New-PesterContainer.mdx | 4 +- docs/commands/Set-ItResult.mdx | 4 +- docs/commands/Should-All.mdx | 2 +- docs/commands/Should-Any.mdx | 2 +- docs/commands/Should-Be.mdx | 2 +- docs/commands/Should-BeAfter.mdx | 8 +-- docs/commands/Should-BeBefore.mdx | 8 +-- docs/commands/Should-BeCollection.mdx | 4 +- docs/commands/Should-BeEmptyString.mdx | 2 +- docs/commands/Should-BeEquivalent.mdx | 2 +- docs/commands/Should-BeFalse.mdx | 2 +- docs/commands/Should-BeFalsy.mdx | 2 +- docs/commands/Should-BeFasterThan.mdx | 2 +- docs/commands/Should-BeGreaterThan.mdx | 2 +- docs/commands/Should-BeGreaterThanOrEqual.mdx | 2 +- docs/commands/Should-BeHashtable.mdx | 1 + docs/commands/Should-BeLessThan.mdx | 2 +- docs/commands/Should-BeLessThanOrEqual.mdx | 2 +- docs/commands/Should-BeLikeString.mdx | 1 + docs/commands/Should-BeNull.mdx | 2 +- docs/commands/Should-BeSame.mdx | 2 +- docs/commands/Should-BeSlowerThan.mdx | 2 +- docs/commands/Should-BeString.mdx | 2 +- docs/commands/Should-BeTrue.mdx | 2 +- docs/commands/Should-BeTruthy.mdx | 2 +- docs/commands/Should-ContainCollection.mdx | 2 +- docs/commands/Should-HaveParameter.mdx | 2 +- docs/commands/Should-HaveType.mdx | 2 +- docs/commands/Should-Invoke.mdx | 5 +- docs/commands/Should-MatchString.mdx | 1 + docs/commands/Should-NotBe.mdx | 2 +- docs/commands/Should-NotBeEmptyString.mdx | 2 +- docs/commands/Should-NotBeLikeString.mdx | 1 + docs/commands/Should-NotBeNull.mdx | 2 +- docs/commands/Should-NotBeSame.mdx | 2 +- docs/commands/Should-NotBeString.mdx | 2 +- .../commands/Should-NotBeWhiteSpaceString.mdx | 2 +- docs/commands/Should-NotContainCollection.mdx | 2 +- docs/commands/Should-NotHaveParameter.mdx | 1 + docs/commands/Should-NotHaveType.mdx | 2 +- docs/commands/Should-NotInvoke.mdx | 5 +- docs/commands/Should-NotMatchString.mdx | 1 + docs/commands/Should-Throw.mdx | 2 +- docs/commands/Should.mdx | 50 +++++++++--------- generate-command-reference.ps1 | 52 +++++++++++++++---- 66 files changed, 147 insertions(+), 104 deletions(-) diff --git a/docs/commands/Add-ShouldOperator.mdx b/docs/commands/Add-ShouldOperator.mdx index 2b483d7..ca3538f 100644 --- a/docs/commands/Add-ShouldOperator.mdx +++ b/docs/commands/Add-ShouldOperator.mdx @@ -24,7 +24,7 @@ Register a Should Operator with Pester ```powershell Add-ShouldOperator [-Name] [-Test] [[-Alias] ] [[-InternalName] ] - [-SupportsArrayInput] + [-SupportsArrayInput] [] ``` ## DESCRIPTION diff --git a/docs/commands/AfterAll.mdx b/docs/commands/AfterAll.mdx index 75cfe97..a36e950 100644 --- a/docs/commands/AfterAll.mdx +++ b/docs/commands/AfterAll.mdx @@ -24,7 +24,7 @@ Context or Describe block. ## SYNTAX ```powershell -AfterAll [-Scriptblock] +AfterAll [-Scriptblock] [] ``` ## DESCRIPTION diff --git a/docs/commands/AfterEach.mdx b/docs/commands/AfterEach.mdx index 619b302..403608f 100644 --- a/docs/commands/AfterEach.mdx +++ b/docs/commands/AfterEach.mdx @@ -24,7 +24,7 @@ the current Context or Describe block. ## SYNTAX ```powershell -AfterEach [-Scriptblock] +AfterEach [-Scriptblock] [] ``` ## DESCRIPTION diff --git a/docs/commands/BeforeAll.mdx b/docs/commands/BeforeAll.mdx index 21c8241..19a8bc1 100644 --- a/docs/commands/BeforeAll.mdx +++ b/docs/commands/BeforeAll.mdx @@ -24,7 +24,7 @@ Context or Describe block. ## SYNTAX ```powershell -BeforeAll [-Scriptblock] +BeforeAll [-Scriptblock] [] ``` ## DESCRIPTION diff --git a/docs/commands/BeforeDiscovery.mdx b/docs/commands/BeforeDiscovery.mdx index 965f41a..83137cf 100644 --- a/docs/commands/BeforeDiscovery.mdx +++ b/docs/commands/BeforeDiscovery.mdx @@ -23,7 +23,7 @@ Runs setup code that is used during Discovery phase. ## SYNTAX ```powershell -BeforeDiscovery [-ScriptBlock] +BeforeDiscovery [-ScriptBlock] [] ``` ## DESCRIPTION diff --git a/docs/commands/BeforeEach.mdx b/docs/commands/BeforeEach.mdx index 1958f84..c9fa5c7 100644 --- a/docs/commands/BeforeEach.mdx +++ b/docs/commands/BeforeEach.mdx @@ -24,7 +24,7 @@ the current Context or Describe block. ## SYNTAX ```powershell -BeforeEach [-Scriptblock] +BeforeEach [-Scriptblock] [] ``` ## DESCRIPTION diff --git a/docs/commands/Context.mdx b/docs/commands/Context.mdx index 17baec7..51f79ef 100644 --- a/docs/commands/Context.mdx +++ b/docs/commands/Context.mdx @@ -24,7 +24,7 @@ Provides logical grouping of It blocks within a single Describe block. ```powershell Context [-Name] [-Tag ] [[-Fixture] ] [-Skip] [-AllowNullOrEmptyForEach] - [-ForEach ] + [-ForEach ] [] ``` ## DESCRIPTION diff --git a/docs/commands/ConvertTo-JUnitReport.mdx b/docs/commands/ConvertTo-JUnitReport.mdx index a80286d..0fbe3e3 100644 --- a/docs/commands/ConvertTo-JUnitReport.mdx +++ b/docs/commands/ConvertTo-JUnitReport.mdx @@ -23,7 +23,7 @@ Converts a Pester result-object to an JUnit-compatible XML report ## SYNTAX ```powershell -ConvertTo-JUnitReport [-Result] [-AsString] +ConvertTo-JUnitReport [-Result] [-AsString] [] ``` ## DESCRIPTION diff --git a/docs/commands/ConvertTo-NUnitReport.mdx b/docs/commands/ConvertTo-NUnitReport.mdx index 598e554..3ab7d66 100644 --- a/docs/commands/ConvertTo-NUnitReport.mdx +++ b/docs/commands/ConvertTo-NUnitReport.mdx @@ -23,7 +23,7 @@ Converts a Pester result-object to an NUnit 2.5 or 3-compatible XML-report ## SYNTAX ```powershell -ConvertTo-NUnitReport [-Result] [-AsString] [[-Format] ] +ConvertTo-NUnitReport [-Result] [-AsString] [[-Format] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/ConvertTo-Pester4Result.mdx b/docs/commands/ConvertTo-Pester4Result.mdx index 1e08951..2e15c8d 100644 --- a/docs/commands/ConvertTo-Pester4Result.mdx +++ b/docs/commands/ConvertTo-Pester4Result.mdx @@ -23,7 +23,7 @@ Converts a Pester 5 result-object to an Pester 4-compatible object ## SYNTAX ```powershell -ConvertTo-Pester4Result [-PesterResult] +ConvertTo-Pester4Result [-PesterResult] [] ``` ## DESCRIPTION diff --git a/docs/commands/Describe.mdx b/docs/commands/Describe.mdx index d7e8ea1..d95ef64 100644 --- a/docs/commands/Describe.mdx +++ b/docs/commands/Describe.mdx @@ -24,7 +24,7 @@ Creates a logical group of tests. ```powershell Describe [-Name] [-Tag ] [[-Fixture] ] [-Skip] [-AllowNullOrEmptyForEach] - [-ForEach ] + [-ForEach ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Export-JUnitReport.mdx b/docs/commands/Export-JUnitReport.mdx index 081c0c1..ad89aa4 100644 --- a/docs/commands/Export-JUnitReport.mdx +++ b/docs/commands/Export-JUnitReport.mdx @@ -23,7 +23,7 @@ Exports a Pester result-object to an JUnit-compatible XML-report ## SYNTAX ```powershell -Export-JUnitReport [-Result] [-Path] +Export-JUnitReport [-Result] [-Path] [] ``` ## DESCRIPTION diff --git a/docs/commands/Export-NUnitReport.mdx b/docs/commands/Export-NUnitReport.mdx index be9a776..67e49f7 100644 --- a/docs/commands/Export-NUnitReport.mdx +++ b/docs/commands/Export-NUnitReport.mdx @@ -23,7 +23,7 @@ Exports a Pester result-object to an NUnit-compatible XML-report ## SYNTAX ```powershell -Export-NUnitReport [-Result] [-Path] [[-Format] ] +Export-NUnitReport [-Result] [-Path] [[-Format] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Get-ShouldOperator.mdx b/docs/commands/Get-ShouldOperator.mdx index 87462b3..3bf83ab 100644 --- a/docs/commands/Get-ShouldOperator.mdx +++ b/docs/commands/Get-ShouldOperator.mdx @@ -23,7 +23,7 @@ Display the assertion operators available for use with Should. ## SYNTAX ```powershell -Get-ShouldOperator [-Name ] +Get-ShouldOperator [-Name ] [] ``` ## DESCRIPTION diff --git a/docs/commands/InModuleScope.mdx b/docs/commands/InModuleScope.mdx index ddc0981..1a9c162 100644 --- a/docs/commands/InModuleScope.mdx +++ b/docs/commands/InModuleScope.mdx @@ -25,7 +25,7 @@ scope of a PowerShell script or manifest module. ```powershell InModuleScope [-ModuleName] [-ScriptBlock] [[-Parameters] ] - [[-ArgumentList] ] + [[-ArgumentList] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Invoke-Pester.mdx b/docs/commands/Invoke-Pester.mdx index 988f5f9..3263c02 100644 --- a/docs/commands/Invoke-Pester.mdx +++ b/docs/commands/Invoke-Pester.mdx @@ -27,13 +27,13 @@ Runs Pester tests ```powershell Invoke-Pester [[-Path] ] [-ExcludePath ] [-TagFilter ] [-ExcludeTagFilter ] [-FullNameFilter ] [-CI] [-Output ] [-PassThru] - [-Container ] + [-Container ] [] ``` ### Advanced ```powershell -Invoke-Pester [-Configuration ] +Invoke-Pester [-Configuration ] [] ``` ## DESCRIPTION diff --git a/docs/commands/It.mdx b/docs/commands/It.mdx index a170ca3..31ffe3b 100644 --- a/docs/commands/It.mdx +++ b/docs/commands/It.mdx @@ -26,13 +26,14 @@ Validates the results of a test inside of a Describe block. ```powershell It [-Name] [[-Test] ] [-ForEach ] [-Tag ] [-AllowNullOrEmptyForEach] + [] ``` ### Skip ```powershell It [-Name] [[-Test] ] [-ForEach ] [-Tag ] [-Skip] - [-AllowNullOrEmptyForEach] + [-AllowNullOrEmptyForEach] [] ``` ## DESCRIPTION diff --git a/docs/commands/Mock.mdx b/docs/commands/Mock.mdx index 8636a88..1d23790 100644 --- a/docs/commands/Mock.mdx +++ b/docs/commands/Mock.mdx @@ -26,6 +26,7 @@ implementation. ```powershell Mock [[-CommandName] ] [[-MockWith] ] [-Verifiable] [[-ParameterFilter] ] [[-ModuleName] ] [[-RemoveParameterType] ] [[-RemoveParameterValidation] ] + [] ``` ## DESCRIPTION diff --git a/docs/commands/New-Fixture.mdx b/docs/commands/New-Fixture.mdx index a190c88..9e66d56 100644 --- a/docs/commands/New-Fixture.mdx +++ b/docs/commands/New-Fixture.mdx @@ -24,7 +24,7 @@ and another one that contains its tests. ## SYNTAX ```powershell -New-Fixture [-Name] [[-Path] ] +New-Fixture [-Name] [[-Path] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/New-MockObject.mdx b/docs/commands/New-MockObject.mdx index 1098f06..1688d47 100644 --- a/docs/commands/New-MockObject.mdx +++ b/docs/commands/New-MockObject.mdx @@ -26,13 +26,14 @@ This function instantiates a .NET object from a type. ```powershell New-MockObject [-Type] [-Properties ] [-Methods ] [-MethodHistoryPrefix ] + [] ``` ### InputObject ```powershell New-MockObject -InputObject [-Properties ] [-Methods ] - [-MethodHistoryPrefix ] + [-MethodHistoryPrefix ] [] ``` ## DESCRIPTION diff --git a/docs/commands/New-PesterConfiguration.mdx b/docs/commands/New-PesterConfiguration.mdx index 03ed4d3..117a982 100644 --- a/docs/commands/New-PesterConfiguration.mdx +++ b/docs/commands/New-PesterConfiguration.mdx @@ -23,7 +23,7 @@ Creates a new PesterConfiguration object for advanced configuration of Invoke-Pe ## SYNTAX ```powershell -New-PesterConfiguration [[-Hashtable] ] +New-PesterConfiguration [[-Hashtable] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/New-PesterContainer.mdx b/docs/commands/New-PesterContainer.mdx index 28bfb82..635d7ed 100644 --- a/docs/commands/New-PesterContainer.mdx +++ b/docs/commands/New-PesterContainer.mdx @@ -25,13 +25,13 @@ Generates ContainerInfo-objects used as for Invoke-Pester -Container ### Path (Default) ```powershell -New-PesterContainer -Path [-Data ] +New-PesterContainer -Path [-Data ] [] ``` ### ScriptBlock ```powershell -New-PesterContainer -ScriptBlock [-Data ] +New-PesterContainer -ScriptBlock [-Data ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Set-ItResult.mdx b/docs/commands/Set-ItResult.mdx index 6d70dc9..bc674ba 100644 --- a/docs/commands/Set-ItResult.mdx +++ b/docs/commands/Set-ItResult.mdx @@ -25,13 +25,13 @@ Set-ItResult is used inside the It block to explicitly set the test result ### Inconclusive ```powershell -Set-ItResult [-Inconclusive] [-Because ] +Set-ItResult [-Inconclusive] [-Because ] [] ``` ### Skipped ```powershell -Set-ItResult [-Skipped] [-Because ] +Set-ItResult [-Skipped] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-All.mdx b/docs/commands/Should-All.mdx index de09a09..268a30b 100644 --- a/docs/commands/Should-All.mdx +++ b/docs/commands/Should-All.mdx @@ -24,7 +24,7 @@ If the filter returns true, or does not throw for all the items in the collectio ## SYNTAX ```powershell -Should-All [[-Actual] ] [-FilterScript] [-Because ] +Should-All [[-Actual] ] [-FilterScript] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-Any.mdx b/docs/commands/Should-Any.mdx index cbea0d6..af44ab0 100644 --- a/docs/commands/Should-Any.mdx +++ b/docs/commands/Should-Any.mdx @@ -24,7 +24,7 @@ If the filter returns true, or does not throw for any of the items in the collec ## SYNTAX ```powershell -Should-Any [[-Actual] ] [-FilterScript] [-Because ] +Should-Any [[-Actual] ] [-FilterScript] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-Be.mdx b/docs/commands/Should-Be.mdx index 6677875..4f84491 100644 --- a/docs/commands/Should-Be.mdx +++ b/docs/commands/Should-Be.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if they are equal. ## SYNTAX ```powershell -Should-Be [[-Actual] ] [-Expected] [-Because ] +Should-Be [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeAfter.mdx b/docs/commands/Should-BeAfter.mdx index 0bd37f9..d5c34b9 100644 --- a/docs/commands/Should-BeAfter.mdx +++ b/docs/commands/Should-BeAfter.mdx @@ -25,25 +25,25 @@ Asserts that the provided [datetime] is after the expected [datetime]. ### Now (Default) ```powershell -Should-BeAfter [[-Actual] ] [-Now] [-Because ] +Should-BeAfter [[-Actual] ] [-Now] [-Because ] [] ``` ### FluentFromNow ```powershell -Should-BeAfter [[-Actual] ] [[-Time] ] [-FromNow] [-Because ] +Should-BeAfter [[-Actual] ] [[-Time] ] [-FromNow] [-Because ] [] ``` ### FluentAgo ```powershell -Should-BeAfter [[-Actual] ] [[-Time] ] [-Ago] [-Because ] +Should-BeAfter [[-Actual] ] [[-Time] ] [-Ago] [-Because ] [] ``` ### Expected ```powershell -Should-BeAfter [[-Actual] ] [[-Expected] ] [-Because ] +Should-BeAfter [[-Actual] ] [[-Expected] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeBefore.mdx b/docs/commands/Should-BeBefore.mdx index 73c81e2..9f56488 100644 --- a/docs/commands/Should-BeBefore.mdx +++ b/docs/commands/Should-BeBefore.mdx @@ -25,25 +25,25 @@ Asserts that the provided [datetime] is before the expected [datetime]. ### Now (Default) ```powershell -Should-BeBefore [[-Actual] ] [-Now] [-Because ] +Should-BeBefore [[-Actual] ] [-Now] [-Because ] [] ``` ### FluentFromNow ```powershell -Should-BeBefore [[-Actual] ] [[-Time] ] [-FromNow] [-Because ] +Should-BeBefore [[-Actual] ] [[-Time] ] [-FromNow] [-Because ] [] ``` ### FluentAgo ```powershell -Should-BeBefore [[-Actual] ] [[-Time] ] [-Ago] [-Because ] +Should-BeBefore [[-Actual] ] [[-Time] ] [-Ago] [-Because ] [] ``` ### Expected ```powershell -Should-BeBefore [[-Actual] ] [[-Expected] ] [-Because ] +Should-BeBefore [[-Actual] ] [[-Expected] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeCollection.mdx b/docs/commands/Should-BeCollection.mdx index a113e5b..269e559 100644 --- a/docs/commands/Should-BeCollection.mdx +++ b/docs/commands/Should-BeCollection.mdx @@ -26,13 +26,13 @@ It does not compare the types of the input collections. ### Expected ```powershell -Should-BeCollection [[-Actual] ] [-Expected] [-Because ] +Should-BeCollection [[-Actual] ] [-Expected] [-Because ] [] ``` ### Count ```powershell -Should-BeCollection [[-Actual] ] [-Because ] [-Count ] +Should-BeCollection [[-Actual] ] [-Because ] [-Count ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeEmptyString.mdx b/docs/commands/Should-BeEmptyString.mdx index 2fe8183..447ee76 100644 --- a/docs/commands/Should-BeEmptyString.mdx +++ b/docs/commands/Should-BeEmptyString.mdx @@ -23,7 +23,7 @@ Ensures that input is an empty string. ## SYNTAX ```powershell -Should-BeEmptyString [[-Actual] ] [-Because ] +Should-BeEmptyString [[-Actual] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeEquivalent.mdx b/docs/commands/Should-BeEquivalent.mdx index be50f73..3509273 100644 --- a/docs/commands/Should-BeEquivalent.mdx +++ b/docs/commands/Should-BeEquivalent.mdx @@ -24,7 +24,7 @@ Compares two objects for equivalency, by recursively comparing their properties ```powershell Should-BeEquivalent [[-Actual] ] [-Expected] [-Because ] [-ExcludePath ] - [-ExcludePathsNotOnExpected] [-Comparator ] + [-ExcludePathsNotOnExpected] [-Comparator ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeFalse.mdx b/docs/commands/Should-BeFalse.mdx index 92dac45..370c31b 100644 --- a/docs/commands/Should-BeFalse.mdx +++ b/docs/commands/Should-BeFalse.mdx @@ -24,7 +24,7 @@ It does not convert input values to boolean, and will fail for any value that is ## SYNTAX ```powershell -Should-BeFalse [[-Actual] ] [[-Because] ] +Should-BeFalse [[-Actual] ] [[-Because] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeFalsy.mdx b/docs/commands/Should-BeFalsy.mdx index 975c625..ec7a7ca 100644 --- a/docs/commands/Should-BeFalsy.mdx +++ b/docs/commands/Should-BeFalsy.mdx @@ -24,7 +24,7 @@ It converts the input value to a boolean. ## SYNTAX ```powershell -Should-BeFalsy [[-Actual] ] [[-Because] ] +Should-BeFalsy [[-Actual] ] [[-Because] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeFasterThan.mdx b/docs/commands/Should-BeFasterThan.mdx index c262a0b..3eb9039 100644 --- a/docs/commands/Should-BeFasterThan.mdx +++ b/docs/commands/Should-BeFasterThan.mdx @@ -23,7 +23,7 @@ Asserts that the provided [timespan] or [scriptblock] is faster than the expecte ## SYNTAX ```powershell -Should-BeFasterThan [[-Actual] ] [[-Expected] ] [-Because ] +Should-BeFasterThan [[-Actual] ] [[-Expected] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeGreaterThan.mdx b/docs/commands/Should-BeGreaterThan.mdx index 705b075..5cb66cd 100644 --- a/docs/commands/Should-BeGreaterThan.mdx +++ b/docs/commands/Should-BeGreaterThan.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if the actual value is great ## SYNTAX ```powershell -Should-BeGreaterThan [[-Actual] ] [-Expected] [-Because ] +Should-BeGreaterThan [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeGreaterThanOrEqual.mdx b/docs/commands/Should-BeGreaterThanOrEqual.mdx index 55a1379..a9e97d2 100644 --- a/docs/commands/Should-BeGreaterThanOrEqual.mdx +++ b/docs/commands/Should-BeGreaterThanOrEqual.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if the actual value is great ## SYNTAX ```powershell -Should-BeGreaterThanOrEqual [[-Actual] ] [-Expected] [-Because ] +Should-BeGreaterThanOrEqual [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeHashtable.mdx b/docs/commands/Should-BeHashtable.mdx index 6156ec0..74fde48 100644 --- a/docs/commands/Should-BeHashtable.mdx +++ b/docs/commands/Should-BeHashtable.mdx @@ -25,6 +25,7 @@ entries, whether it is ordered, and that it contains specific keys. ```powershell Should-BeHashtable [[-Actual] ] [-Count ] [-Key ] [-Ordered] [-Because ] + [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeLessThan.mdx b/docs/commands/Should-BeLessThan.mdx index 180f110..d87828f 100644 --- a/docs/commands/Should-BeLessThan.mdx +++ b/docs/commands/Should-BeLessThan.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if the actual value is less ## SYNTAX ```powershell -Should-BeLessThan [[-Actual] ] [-Expected] [-Because ] +Should-BeLessThan [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeLessThanOrEqual.mdx b/docs/commands/Should-BeLessThanOrEqual.mdx index 3dd1ce4..84d0361 100644 --- a/docs/commands/Should-BeLessThanOrEqual.mdx +++ b/docs/commands/Should-BeLessThanOrEqual.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if the actual value is less ## SYNTAX ```powershell -Should-BeLessThanOrEqual [[-Actual] ] [-Expected] [-Because ] +Should-BeLessThanOrEqual [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeLikeString.mdx b/docs/commands/Should-BeLikeString.mdx index abfdcf5..22a1abf 100644 --- a/docs/commands/Should-BeLikeString.mdx +++ b/docs/commands/Should-BeLikeString.mdx @@ -24,6 +24,7 @@ Asserts that the actual value is like the expected value. ```powershell Should-BeLikeString [[-Actual] ] [-Expected] [-CaseSensitive] [-Because ] + [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeNull.mdx b/docs/commands/Should-BeNull.mdx index 1b5fc62..3457bb7 100644 --- a/docs/commands/Should-BeNull.mdx +++ b/docs/commands/Should-BeNull.mdx @@ -23,7 +23,7 @@ Asserts that the input is `$null`. ## SYNTAX ```powershell -Should-BeNull [[-Actual] ] [-Because ] +Should-BeNull [[-Actual] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeSame.mdx b/docs/commands/Should-BeSame.mdx index 63af8eb..6e7bb33 100644 --- a/docs/commands/Should-BeSame.mdx +++ b/docs/commands/Should-BeSame.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if they are the same instanc ## SYNTAX ```powershell -Should-BeSame [[-Actual] ] [-Expected] [-Because ] +Should-BeSame [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeSlowerThan.mdx b/docs/commands/Should-BeSlowerThan.mdx index 36e10e0..8d53f46 100644 --- a/docs/commands/Should-BeSlowerThan.mdx +++ b/docs/commands/Should-BeSlowerThan.mdx @@ -23,7 +23,7 @@ Asserts that the provided [timespan] is slower than the expected [timespan]. ## SYNTAX ```powershell -Should-BeSlowerThan [[-Actual] ] [[-Expected] ] [-Because ] +Should-BeSlowerThan [[-Actual] ] [[-Expected] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeString.mdx b/docs/commands/Should-BeString.mdx index 8ce08b5..fa1b3f0 100644 --- a/docs/commands/Should-BeString.mdx +++ b/docs/commands/Should-BeString.mdx @@ -24,7 +24,7 @@ Asserts that the actual value is equal to the expected value. ```powershell Should-BeString [[-Actual] ] [-Expected] [-Because ] [-CaseSensitive] - [-IgnoreWhitespace] [-TrimWhitespace] + [-IgnoreWhitespace] [-TrimWhitespace] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeTrue.mdx b/docs/commands/Should-BeTrue.mdx index 66f07fb..c752e1d 100644 --- a/docs/commands/Should-BeTrue.mdx +++ b/docs/commands/Should-BeTrue.mdx @@ -24,7 +24,7 @@ It does not convert input values to boolean, and will fail for any value is not ## SYNTAX ```powershell -Should-BeTrue [[-Actual] ] [[-Because] ] +Should-BeTrue [[-Actual] ] [[-Because] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-BeTruthy.mdx b/docs/commands/Should-BeTruthy.mdx index 5da0d37..e003c6c 100644 --- a/docs/commands/Should-BeTruthy.mdx +++ b/docs/commands/Should-BeTruthy.mdx @@ -24,7 +24,7 @@ It converts input values to boolean, and will fail for any value is not $true, o ## SYNTAX ```powershell -Should-BeTruthy [[-Actual] ] [[-Because] ] +Should-BeTruthy [[-Actual] ] [[-Because] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-ContainCollection.mdx b/docs/commands/Should-ContainCollection.mdx index a9cd817..05c88bc 100644 --- a/docs/commands/Should-ContainCollection.mdx +++ b/docs/commands/Should-ContainCollection.mdx @@ -24,7 +24,7 @@ It does not compare the types of the input collections. ## SYNTAX ```powershell -Should-ContainCollection [[-Actual] ] [-Expected] [-Because ] +Should-ContainCollection [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-HaveParameter.mdx b/docs/commands/Should-HaveParameter.mdx index 2f6fd47..df78d35 100644 --- a/docs/commands/Should-HaveParameter.mdx +++ b/docs/commands/Should-HaveParameter.mdx @@ -25,7 +25,7 @@ Asserts that a command has the expected parameter. ```powershell Should-HaveParameter [[-ParameterName] ] [[-Type] ] [[-DefaultValue] ] [-Mandatory] [[-InParameterSet] ] [-HasArgumentCompleter] [[-Alias] ] [[-Actual] ] - [[-Because] ] + [[-Because] ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-HaveType.mdx b/docs/commands/Should-HaveType.mdx index 720e1f0..460392d 100644 --- a/docs/commands/Should-HaveType.mdx +++ b/docs/commands/Should-HaveType.mdx @@ -23,7 +23,7 @@ Asserts that the input is of the expected type. ## SYNTAX ```powershell -Should-HaveType [[-Actual] ] [-Expected] [-Because ] +Should-HaveType [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-Invoke.mdx b/docs/commands/Should-Invoke.mdx index 2bd1415..5e7dce6 100644 --- a/docs/commands/Should-Invoke.mdx +++ b/docs/commands/Should-Invoke.mdx @@ -28,18 +28,19 @@ and throws an exception if it has not. ```powershell Should-Invoke [-CommandName] [[-Times] ] [-ParameterFilter ] [-ExclusiveFilter ] [-ModuleName ] [-Scope ] [-Exactly] [-Because ] + [] ``` ### ExclusiveFilter ```powershell -Should-Invoke -ExclusiveFilter +Should-Invoke -ExclusiveFilter [] ``` ### Verifiable ```powershell -Should-Invoke [-Because ] [-Verifiable] +Should-Invoke [-Because ] [-Verifiable] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-MatchString.mdx b/docs/commands/Should-MatchString.mdx index 5f8fc74..b5ae273 100644 --- a/docs/commands/Should-MatchString.mdx +++ b/docs/commands/Should-MatchString.mdx @@ -24,6 +24,7 @@ Tests whether a string matches a regular expression pattern. ```powershell Should-MatchString [[-Actual] ] [-Expected] [-CaseSensitive] [-Because ] + [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotBe.mdx b/docs/commands/Should-NotBe.mdx index 7d59c4f..3b79994 100644 --- a/docs/commands/Should-NotBe.mdx +++ b/docs/commands/Should-NotBe.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if they are not equal. ## SYNTAX ```powershell -Should-NotBe [[-Actual] ] [-Expected] [-Because ] +Should-NotBe [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotBeEmptyString.mdx b/docs/commands/Should-NotBeEmptyString.mdx index 10d8363..30f98ba 100644 --- a/docs/commands/Should-NotBeEmptyString.mdx +++ b/docs/commands/Should-NotBeEmptyString.mdx @@ -23,7 +23,7 @@ Ensures that the input is a string, and that the input is not $null or empty str ## SYNTAX ```powershell -Should-NotBeEmptyString [[-Actual] ] [-Because ] +Should-NotBeEmptyString [[-Actual] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotBeLikeString.mdx b/docs/commands/Should-NotBeLikeString.mdx index b281fa4..7097da0 100644 --- a/docs/commands/Should-NotBeLikeString.mdx +++ b/docs/commands/Should-NotBeLikeString.mdx @@ -24,6 +24,7 @@ Asserts that the actual value is not like the expected value. ```powershell Should-NotBeLikeString [[-Actual] ] [-Expected] [-CaseSensitive] [-Because ] + [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotBeNull.mdx b/docs/commands/Should-NotBeNull.mdx index c90e501..1f3625a 100644 --- a/docs/commands/Should-NotBeNull.mdx +++ b/docs/commands/Should-NotBeNull.mdx @@ -23,7 +23,7 @@ Asserts that the input is not `$null`. ## SYNTAX ```powershell -Should-NotBeNull [[-Actual] ] [-Because ] +Should-NotBeNull [[-Actual] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotBeSame.mdx b/docs/commands/Should-NotBeSame.mdx index 5e9a888..e036303 100644 --- a/docs/commands/Should-NotBeSame.mdx +++ b/docs/commands/Should-NotBeSame.mdx @@ -23,7 +23,7 @@ Compares the expected value to actual value, to see if the actual value is not t ## SYNTAX ```powershell -Should-NotBeSame [[-Actual] ] [-Expected] [-Because ] +Should-NotBeSame [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotBeString.mdx b/docs/commands/Should-NotBeString.mdx index d496fe6..162820f 100644 --- a/docs/commands/Should-NotBeString.mdx +++ b/docs/commands/Should-NotBeString.mdx @@ -24,7 +24,7 @@ Asserts that the actual value is not equal to the expected value. ```powershell Should-NotBeString [[-Actual] ] [[-Expected] ] [-Because ] [-CaseSensitive] - [-IgnoreWhitespace] + [-IgnoreWhitespace] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotBeWhiteSpaceString.mdx b/docs/commands/Should-NotBeWhiteSpaceString.mdx index 63509d2..bb73dc0 100644 --- a/docs/commands/Should-NotBeWhiteSpaceString.mdx +++ b/docs/commands/Should-NotBeWhiteSpaceString.mdx @@ -23,7 +23,7 @@ Ensures that the input is a string, and that the input is not $null, empty, or w ## SYNTAX ```powershell -Should-NotBeWhiteSpaceString [[-Actual] ] [-Because ] +Should-NotBeWhiteSpaceString [[-Actual] ] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotContainCollection.mdx b/docs/commands/Should-NotContainCollection.mdx index e7b4645..712c03a 100644 --- a/docs/commands/Should-NotContainCollection.mdx +++ b/docs/commands/Should-NotContainCollection.mdx @@ -24,7 +24,7 @@ It does not compare the types of the input collections. ## SYNTAX ```powershell -Should-NotContainCollection [[-Actual] ] [-Expected] [-Because ] +Should-NotContainCollection [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotHaveParameter.mdx b/docs/commands/Should-NotHaveParameter.mdx index 4f99809..8c9883a 100644 --- a/docs/commands/Should-NotHaveParameter.mdx +++ b/docs/commands/Should-NotHaveParameter.mdx @@ -24,6 +24,7 @@ Asserts that a command has does not have the parameter. ```powershell Should-NotHaveParameter [[-ParameterName] ] [[-Actual] ] [[-Because] ] + [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotHaveType.mdx b/docs/commands/Should-NotHaveType.mdx index 498917e..2d7a309 100644 --- a/docs/commands/Should-NotHaveType.mdx +++ b/docs/commands/Should-NotHaveType.mdx @@ -23,7 +23,7 @@ Asserts that the input is not of the expected type. ## SYNTAX ```powershell -Should-NotHaveType [[-Actual] ] [-Expected] [-Because ] +Should-NotHaveType [[-Actual] ] [-Expected] [-Because ] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotInvoke.mdx b/docs/commands/Should-NotInvoke.mdx index 2a53d5e..ed5bb57 100644 --- a/docs/commands/Should-NotInvoke.mdx +++ b/docs/commands/Should-NotInvoke.mdx @@ -27,18 +27,19 @@ Checks that mocked command was not called and throws exception if it was. ```powershell Should-NotInvoke [-CommandName] [[-Times] ] [-ParameterFilter ] [-ExclusiveFilter ] [-ModuleName ] [-Scope ] [-Exactly] [-Because ] + [] ``` ### ExclusiveFilter ```powershell -Should-NotInvoke -ExclusiveFilter +Should-NotInvoke -ExclusiveFilter [] ``` ### Verifiable ```powershell -Should-NotInvoke [-Because ] [-Verifiable] +Should-NotInvoke [-Because ] [-Verifiable] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-NotMatchString.mdx b/docs/commands/Should-NotMatchString.mdx index 2ce50ae..2982d2f 100644 --- a/docs/commands/Should-NotMatchString.mdx +++ b/docs/commands/Should-NotMatchString.mdx @@ -24,6 +24,7 @@ Tests whether a string does not match a regular expression pattern. ```powershell Should-NotMatchString [[-Actual] ] [-Expected] [-CaseSensitive] [-Because ] + [] ``` ## DESCRIPTION diff --git a/docs/commands/Should-Throw.mdx b/docs/commands/Should-Throw.mdx index d6c2a6d..632a46a 100644 --- a/docs/commands/Should-Throw.mdx +++ b/docs/commands/Should-Throw.mdx @@ -24,7 +24,7 @@ Asserts that a script block throws an exception. ```powershell Should-Throw -ScriptBlock [[-ExceptionMessage] ] [[-FullyQualifiedErrorId] ] - [[-ExceptionType] ] [[-Because] ] [-AllowNonTerminatingError] + [[-ExceptionType] ] [[-Because] ] [-AllowNonTerminatingError] [] ``` ## DESCRIPTION diff --git a/docs/commands/Should.mdx b/docs/commands/Should.mdx index 5a80755..c400b12 100644 --- a/docs/commands/Should.mdx +++ b/docs/commands/Should.mdx @@ -26,138 +26,140 @@ Should is a keyword that is used to define an assertion inside an It block. ```powershell Should [[-ActualValue] ] [-Be] [-Not] [-ExpectedValue ] - [-Because ] + [-Because ] [] ``` ### BeExactly ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeExactly] + [-Because ] [-BeExactly] [] ``` ### BeGreaterThan ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeGreaterThan] + [-Because ] [-BeGreaterThan] [] ``` ### BeLessOrEqual ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeLessOrEqual] + [-Because ] [-BeLessOrEqual] [] ``` ### BeIn ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeIn] + [-Because ] [-BeIn] [] ``` ### BeLessThan ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeLessThan] + [-Because ] [-BeLessThan] [] ``` ### BeGreaterOrEqual ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeGreaterOrEqual] + [-Because ] [-BeGreaterOrEqual] [] ``` ### BeLike ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeLike] + [-Because ] [-BeLike] [] ``` ### BeLikeExactly ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-BeLikeExactly] + [-Because ] [-BeLikeExactly] [] ``` ### BeNullOrEmpty ```powershell Should [[-ActualValue] ] [-Not] [-Because ] - [-BeNullOrEmpty] + [-BeNullOrEmpty] [] ``` ### BeOfType ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-BeOfType] - [-ExpectedType ] + [-ExpectedType ] [] ``` ### BeTrue ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-BeTrue] + [] ``` ### BeFalse ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-BeFalse] + [] ``` ### Contain ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-Contain] + [-Because ] [-Contain] [] ``` ### Exist ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-Exist] - [-LiteralPath] + [-LiteralPath] [] ``` ### FileContentMatch ```powershell Should [[-ActualValue] ] [-Not] [-Because ] - [-FileContentMatch] [-ExpectedContent ] + [-FileContentMatch] [-ExpectedContent ] [] ``` ### FileContentMatchExactly ```powershell Should [[-ActualValue] ] [-Not] [-Because ] - [-ExpectedContent ] [-FileContentMatchExactly] + [-ExpectedContent ] [-FileContentMatchExactly] [] ``` ### FileContentMatchMultiline ```powershell Should [[-ActualValue] ] [-Not] [-Because ] - [-ExpectedContent ] [-FileContentMatchMultiline] + [-ExpectedContent ] [-FileContentMatchMultiline] [] ``` ### FileContentMatchMultilineExactly ```powershell Should [[-ActualValue] ] [-Not] [-Because ] - [-ExpectedContent ] [-FileContentMatchMultilineExactly] + [-ExpectedContent ] [-FileContentMatchMultilineExactly] [] ``` ### HaveCount ```powershell Should [[-ActualValue] ] [-Not] [-ExpectedValue ] - [-Because ] [-HaveCount] + [-Because ] [-HaveCount] [] ``` ### HaveParameter @@ -165,35 +167,35 @@ Should [[-ActualValue] ] [-Not] [-ExpectedValue ] ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-HaveParameter] [-ParameterName ] [-Type ] [-DefaultValue ] [-Mandatory] - [-InParameterSet ] [-HasArgumentCompleter] [-Alias ] + [-InParameterSet ] [-HasArgumentCompleter] [-Alias ] [] ``` ### Match ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-Match] - [-RegularExpression ] + [-RegularExpression ] [] ``` ### MatchExactly ```powershell Should [[-ActualValue] ] [-Not] [-Because ] - [-RegularExpression ] [-MatchExactly] + [-RegularExpression ] [-MatchExactly] [] ``` ### Throw ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-Throw] - [-ExpectedMessage ] [-ErrorId ] [-ExceptionType ] [-PassThru] + [-ExpectedMessage ] [-ErrorId ] [-ExceptionType ] [-PassThru] [] ``` ### InvokeVerifiable ```powershell Should [[-ActualValue] ] [-Not] [-Because ] - [-InvokeVerifiable] + [-InvokeVerifiable] [] ``` ### Invoke @@ -201,7 +203,7 @@ Should [[-ActualValue] ] [-Not] [-Because ] ```powershell Should [[-ActualValue] ] [-Not] [-Because ] [-Invoke] [-CommandName ] [-Times ] [-ParameterFilter ] [-ExclusiveFilter ] - [-ModuleName ] [-Scope ] [-Exactly] [-CallerSessionState ] + [-ModuleName ] [-Scope ] [-Exactly] [-CallerSessionState ] [] ``` ## DESCRIPTION diff --git a/generate-command-reference.ps1 b/generate-command-reference.ps1 index ecceb2e..bf9733f 100644 --- a/generate-command-reference.ps1 +++ b/generate-command-reference.ps1 @@ -194,32 +194,62 @@ function Repair-ExampleFences { return ($result -join $eol) } +function Format-SyntaxCommonParameters { + # After ProgressAction is removed, '[]' is collapsed back inline. + # PlatyPS keeps it inline only while the SYNTAX line stays within its wrap width + # (~110 chars, measured from prior generated output) and otherwise wraps it onto its + # own continuation line. Reproduce that so we neither leave overly long lines nor + # dangling orphans. Only lines that still carry content before the token are wrapped; + # lines that are already just ' []' are left untouched. + param([string] $Content, [int] $MaxWidth = 110) + + $eol = if ($Content -match "`r`n") { "`r`n" } else { "`n" } + $lines = $Content -split "`r?`n" + $out = [System.Collections.Generic.List[string]]::new() + foreach ($line in $lines) { + if ($line.Length -gt $MaxWidth -and $line -match '\S[ ]\[\][ ]*$') { + $head = $line -replace '[ ]*\[\][ ]*$', '' + $out.Add($head) + $out.Add(' []') + } + else { + $out.Add($line) + } + } + return ($out -join $eol) +} + # ----------------------------------------------------------------------------- # Post-process the generated MDX: # * Strip the spurious ProgressAction common parameter that PlatyPS emits on # PowerShell 7.4+ (https://github.com/PowerShell/platyPS/issues/663). Pester 6 # loads a .NET 8 assembly and therefore requires PowerShell 7.4+, so the docs # can no longer be generated on an older PowerShell to avoid this. -# * Drop the '[]' entry from the SYNTAX blocks. It carries no -# useful information for these commands and, on 7.4+, the longer ProgressAction -# token made PlatyPS wrap it onto a dangling line of its own. # * Repair the mismatched code fences PlatyPS emits for .EXAMPLE blocks that # contain their own Markdown fences (see Repair-ExampleFences) so the MDX # compiles. -# The first two replacements allow the token to sit inline or, when PlatyPS wrapped -# the syntax line, on a continuation line of its own (optional leading line-break + -# indentation) so no blank or dangling line is left behind. +# The '[]' SYNTAX entry and the '### CommonParameters' section are +# kept as PlatyPS produces them. Because the ProgressAction token is longer than +# '[]' and always sits right before it, removing ProgressAction can +# leave '[]' orphaned on a wrapped continuation line. The first +# replacement handles that case by pulling '[]' back onto the line +# ProgressAction occupied; the second removes any remaining ProgressAction token, +# whether inline or wrapped onto its own line. Format-SyntaxCommonParameters then wraps +# '[]' back onto its own line where the result would exceed PlatyPS's +# syntax wrap width, matching the layout PlatyPS produces without ProgressAction. # ----------------------------------------------------------------------------- -Write-Host 'Post-processing generated MDX files (ProgressAction, [], example fences)' -ForegroundColor Magenta +Write-Host 'Post-processing generated MDX files (ProgressAction, example fences)' -ForegroundColor Magenta $commandsFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar Get-ChildItem -Path $commandsFolder -Filter '*.mdx' | ForEach-Object { $content = Get-Content -LiteralPath $_.FullName -Raw - # Remove ' [-ProgressAction ]' from the SYNTAX code-blocks - $updated = $content -replace '[ ]*(\r?\n[ ]*)?\[-ProgressAction \]', '' + # Pull '[]' back up when removing ProgressAction would orphan it + $updated = $content -replace '[ ]*\[-ProgressAction \][ ]*\r?\n[ ]*\[\]', ' []' + # Remove any remaining ' [-ProgressAction ]' from the SYNTAX code-blocks + $updated = $updated -replace '[ ]*(\r?\n[ ]*)?\[-ProgressAction \]', '' # Remove the dedicated '### -ProgressAction' section up to the next '### ' heading $updated = $updated -replace '(?ms)^### -ProgressAction\r?\n.*?(?=^### )', '' - # Remove ' []' from the SYNTAX code-blocks - $updated = $updated -replace '[ ]*(\r?\n[ ]*)?\[\]', '' + # Re-wrap '[]' onto its own line where the SYNTAX line is too long + $updated = Format-SyntaxCommonParameters -Content $updated # Fix mismatched code fences inside the EXAMPLES section $updated = Repair-ExampleFences -Content $updated if ($updated -ne $content) {