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..3ab7d66 100644 --- a/docs/commands/ConvertTo-NUnitReport.mdx +++ b/docs/commands/ConvertTo-NUnitReport.mdx @@ -148,4 +148,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..67e49f7 100644 --- a/docs/commands/Export-NUnitReport.mdx +++ b/docs/commands/Export-NUnitReport.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/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..635d7ed 100644 --- a/docs/commands/New-PesterContainer.mdx +++ b/docs/commands/New-PesterContainer.mdx @@ -154,4 +154,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..bc674ba 100644 --- a/docs/commands/Set-ItResult.mdx +++ b/docs/commands/Set-ItResult.mdx @@ -58,10 +58,10 @@ Describe "Example" { the output should be -``` +```powershell 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..268a30b 100644 --- a/docs/commands/Should-All.mdx +++ b/docs/commands/Should-All.mdx @@ -29,7 +29,8 @@ 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 +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/Should-Any.mdx b/docs/commands/Should-Any.mdx index e9a9be0..af44ab0 100644 --- a/docs/commands/Should-Any.mdx +++ b/docs/commands/Should-Any.mdx @@ -29,7 +29,8 @@ 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 +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-Be.mdx b/docs/commands/Should-Be.mdx index 91a2d57..4f84491 100644 --- a/docs/commands/Should-Be.mdx +++ b/docs/commands/Should-Be.mdx @@ -28,7 +28,8 @@ Should-Be [[-Actual] ] [-Expected] [-Because ] [] [-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 +113,7 @@ Parameter Sets: Now Aliases: Required: False -Position: 1 +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -119,8 +126,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 +143,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 +159,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 +185,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 +221,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..9f56488 100644 --- a/docs/commands/Should-BeBefore.mdx +++ b/docs/commands/Should-BeBefore.mdx @@ -25,24 +25,31 @@ 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 +63,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 +113,7 @@ Parameter Sets: Now Aliases: Required: False -Position: 1 +Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False @@ -120,8 +126,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 +143,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 +159,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 +185,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 +221,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..269e559 100644 --- a/docs/commands/Should-BeCollection.mdx +++ b/docs/commands/Should-BeCollection.mdx @@ -37,7 +37,8 @@ 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 +147,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..447ee76 100644 --- a/docs/commands/Should-BeEmptyString.mdx +++ b/docs/commands/Should-BeEmptyString.mdx @@ -28,7 +28,8 @@ Should-BeEmptyString [[-Actual] ] [-Because ] [] [-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 ```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. +Should-BeEquivalent ... -ExcludePathsNotOnExpected ``` +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 ``` This will throw an error because the actual object has an additional property Age and the Name values are not equivalent. @@ -71,15 +70,15 @@ This will throw an error because the actual object has an additional property Ag ### 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 +204,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..370c31b 100644 --- a/docs/commands/Should-BeFalse.mdx +++ b/docs/commands/Should-BeFalse.mdx @@ -29,7 +29,8 @@ 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 +109,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..ec7a7ca 100644 --- a/docs/commands/Should-BeFalsy.mdx +++ b/docs/commands/Should-BeFalsy.mdx @@ -29,7 +29,8 @@ 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 +109,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..3eb9039 100644 --- a/docs/commands/Should-BeFasterThan.mdx +++ b/docs/commands/Should-BeFasterThan.mdx @@ -23,12 +23,13 @@ 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 +83,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 +119,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..5cb66cd 100644 --- a/docs/commands/Should-BeGreaterThan.mdx +++ b/docs/commands/Should-BeGreaterThan.mdx @@ -28,7 +28,7 @@ Should-BeGreaterThan [[-Actual] ] [-Expected] [-Because ] [-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 +109,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..d87828f 100644 --- a/docs/commands/Should-BeLessThan.mdx +++ b/docs/commands/Should-BeLessThan.mdx @@ -28,7 +28,7 @@ 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 +109,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..84d0361 100644 --- a/docs/commands/Should-BeLessThanOrEqual.mdx +++ b/docs/commands/Should-BeLessThanOrEqual.mdx @@ -28,7 +28,7 @@ Should-BeLessThanOrEqual [[-Actual] ] [-Expected] [-Because ] [-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 +93,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..6e7bb33 100644 --- a/docs/commands/Should-BeSame.mdx +++ b/docs/commands/Should-BeSame.mdx @@ -28,7 +28,8 @@ Should-BeSame [[-Actual] ] [-Expected] [-Because ] [] [[-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 +91,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 +127,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..c752e1d 100644 --- a/docs/commands/Should-BeTrue.mdx +++ b/docs/commands/Should-BeTrue.mdx @@ -29,7 +29,8 @@ 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 +109,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..e003c6c 100644 --- a/docs/commands/Should-BeTruthy.mdx +++ b/docs/commands/Should-BeTruthy.mdx @@ -29,7 +29,8 @@ 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 +110,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..05c88bc 100644 --- a/docs/commands/Should-ContainCollection.mdx +++ b/docs/commands/Should-ContainCollection.mdx @@ -29,7 +29,8 @@ Should-ContainCollection [[-Actual] ] [-Expected] [-Because ] [-Expected] [-Because ] [] [-Expected] [-Because ] [] [-Because ] [] [-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 +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-NotBeSame.mdx b/docs/commands/Should-NotBeSame.mdx index 7f358f8..e036303 100644 --- a/docs/commands/Should-NotBeSame.mdx +++ b/docs/commands/Should-NotBeSame.mdx @@ -28,20 +28,20 @@ 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 +121,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..bb73dc0 100644 --- a/docs/commands/Should-NotBeWhiteSpaceString.mdx +++ b/docs/commands/Should-NotBeWhiteSpaceString.mdx @@ -28,7 +28,8 @@ Should-NotBeWhiteSpaceString [[-Actual] ] [-Because ] [] [-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 +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/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..2d7a309 100644 --- a/docs/commands/Should-NotHaveType.mdx +++ b/docs/commands/Should-NotHaveType.mdx @@ -28,7 +28,8 @@ 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 +112,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..632a46a 100644 --- a/docs/commands/Should-Throw.mdx +++ b/docs/commands/Should-Throw.mdx @@ -29,7 +29,8 @@ Should-Throw -ScriptBlock [[-ExceptionMessage] ] [[-FullyQ ## 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 +175,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 9125539..340928b 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' @@ -154,7 +154,7 @@ General runtime options for Pester including tests containers to execute. | 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` | `$null` | +| 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 diff --git a/generate-command-reference.ps1 b/generate-command-reference.ps1 index 43798a1..bf9733f 100644 --- a/generate-command-reference.ps1 +++ b/generate-command-reference.ps1 @@ -119,6 +119,144 @@ 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) +} + +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. +# * Repair the mismatched code fences PlatyPS emits for .EXAMPLE blocks that +# contain their own Markdown fences (see Repair-ExampleFences) so the MDX +# compiles. +# 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 +$commandsFolder = Join-Path -Path $docusaurusOptions.DocsFolder -ChildPath $docusaurusOptions.Sidebar +Get-ChildItem -Path $commandsFolder -Filter '*.mdx' | ForEach-Object { + $content = Get-Content -LiteralPath $_.FullName -Raw + # 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.*?(?=^### )', '' + # 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) { + 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 a24180f..8e8b964 100644 --- a/generate-pesterconfiguration-docs.ps1 +++ b/generate-pesterconfiguration-docs.ps1 @@ -13,6 +13,12 @@ param ( ) #region helpers + +# Run.RepoRoot is resolved by New-PesterConfiguration to the absolute path of the +# repository the generator runs in (machine-specific). We replace it with an +# illustrative placeholder repo root so no build path leaks into the published docs. +$repoRootPlaceholder = 'C:\MyProject' + function Format-MdxDescription ($text) { # Escape characters that are structurally significant to MDX 3 / Markdown tables so raw # PesterConfiguration help text (e.g. "{ . './setup.ps1' }") doesn't break the docs build. @@ -69,8 +75,8 @@ function generateSectionsMarkdownAsTable { $optionName = $configOption.Name $option = $configOption.Value $rawDefault = $option.Default - # Run.RepoRoot defaults to an auto-detected, machine-specific path. Render it as $null so the generated docs stay machine-independent. - if ($rawDefault -is [string] -and $rawDefault -eq $configObject.Run.RepoRoot.Value) { $rawDefault = $null } + # Run.RepoRoot defaults to an auto-detected, machine-specific path. Render an illustrative placeholder (C:\MyProject) so the generated docs stay machine-independent. + if ($rawDefault -is [string] -and $rawDefault -eq $configObject.Run.RepoRoot.Value) { $rawDefault = $repoRootPlaceholder } $default = Format-NicelyMini $rawDefault # Use the declared property type so options with a $null default (e.g. CodeCoverage.ReportRoot) still report their type. $type = $option.GetType().GetProperty('Default').PropertyType -as [string] -replace '^Pester\.' @@ -103,8 +109,8 @@ function generateSectionsMarkdownAsList { $optionName = $configOption.Name $option = $configOption.Value $rawDefault = $option.Default - # Run.RepoRoot defaults to an auto-detected, machine-specific path. Render it as $null so the generated docs stay machine-independent. - if ($rawDefault -is [string] -and $rawDefault -eq $configObject.Run.RepoRoot.Value) { $rawDefault = $null } + # Run.RepoRoot defaults to an auto-detected, machine-specific path. Render an illustrative placeholder (C:\MyProject) so the generated docs stay machine-independent. + if ($rawDefault -is [string] -and $rawDefault -eq $configObject.Run.RepoRoot.Value) { $rawDefault = $repoRootPlaceholder } $default = Format-NicelyMini $rawDefault # Use the declared property type so options with a $null default (e.g. CodeCoverage.ReportRoot) still report their type. $type = $option.GetType().GetProperty('Default').PropertyType -as [string]