Skip to main content
Version: v5

New-PesterConfiguration

SYNOPSIS#

Creates a new [PesterConfiguration] object for advanced configuration of Invoke-Pester.

SYNTAX#

New-PesterConfiguration [[-Hashtable] <IDictionary>] [<CommonParameters>]

DESCRIPTION#

The New-PesterConfiguration function creates a new [PesterConfiguration] object to enable advanced configurations for runnings tests using Invoke-Pester.

Without parameters, the function generates a configuration-object with default options. The returned [PesterConfiguration] object can be modified to suit your requirements.

Calling New-PesterConfiguration is equivalent to calling [PesterConfiguration]::Default which was used in early versions of Pester 5.

Sections and options:

Run:
Path: Directories to be searched for tests, paths directly to test files, or combination of both.
Default value: @('.')
ExcludePath: Directories or files to be excluded from the run.
Default value: @()
ScriptBlock: ScriptBlocks containing tests to be executed.
Default value: @()
Container: ContainerInfo objects containing tests to be executed.
Default value: @()
TestExtension: Filter used to identify test files.
Default value: '.Tests.ps1'
Exit: Exit with non-zero exit code when the test run fails. When used together with Throw, throwing an exception is preferred.
Default value: $false
Throw: Throw an exception when test run fails. When used together with Exit, throwing an exception is preferred.
Default value: $false
PassThru: Return result object to the pipeline after finishing the test run.
Default value: $false
SkipRun: Runs the discovery phase but skips run. Use it with PassThru to get object populated with all tests.
Default value: $false
Filter:
Tag: Tags of Describe, Context or It to be run.
Default value: @()
ExcludeTag: Tags of Describe, Context or It to be excluded from the run.
Default value: @()
Line: Filter by file and scriptblock start line, useful to run parsed tests programatically to avoid problems with expanded names. Example: 'C:\tests\file1.Tests.ps1:37'
Default value: @()
FullName: Full name of test with -like wildcards, joined by dot. Example: '*.describe Get-Item.test1'
Default value: @()
CodeCoverage:
Enabled: Enable CodeCoverage.
Default value: $false
OutputFormat: Format to use for code coverage report. Possible values: JaCoCo, CoverageGutters
Default value: 'JaCoCo'
OutputPath: Path relative to the current directory where code coverage report is saved.
Default value: 'coverage.xml'
OutputEncoding: Encoding of the output file.
Default value: 'UTF8'
Path: Directories or files to be used for codecoverage, by default the Path(s) from general settings are used, unless overridden here.
Default value: @()
ExcludeTests: Exclude tests from code coverage. This uses the TestFilter from general configuration.
Default value: $true
RecursePaths: Will recurse through directories in the Path option.
Default value: $true
CoveragePercentTarget: Target percent of code coverage that you want to achieve, default 75%.
Default value: 75
SingleHitBreakpoints: Remove breakpoint when it is hit.
Default value: $true
TestResult:
Enabled: Enable TestResult.
Default value: $false
OutputFormat: Format to use for test result report. Possible values: NUnitXml, NUnit2.5 or JUnitXml
Default value: 'NUnitXml'
OutputPath: Path relative to the current directory where test result report is saved.
Default value: 'testResults.xml'
OutputEncoding: Encoding of the output file.
Default value: 'UTF8'
TestSuiteName: Set the name assigned to the root 'test-suite' element.
Default value: 'Pester'
Should:
ErrorAction: Controls if Should throws on error. Use 'Stop' to throw on error, or 'Continue' to fail at the end of the test.
Default value: 'Stop'
Debug:
ShowFullErrors: Show full errors including Pester internal stack.
Default value: $false
WriteDebugMessages: Write Debug messages to screen.
Default value: $false
WriteDebugMessagesFrom: Write Debug messages from a given source, WriteDebugMessages must be set to true for this to work. You can use like wildcards to get messages from multiple sources, as well as * to get everything.
Default value: @('Discovery', 'Skip', 'Filter', 'Mock', 'CodeCoverage')
ShowNavigationMarkers: Write paths after every block and test, for easy navigation in VSCode.
Default value: $false
ReturnRawResultObject: Returns unfiltered result object, this is for development only. Do not rely on this object for additional properties, non-public properties will be renamed without previous notice.
Default value: $false
Output:
Verbosity: The verbosity of output, options are None, Normal, Detailed and Diagnostic.
Default value: 'Normal'

Adding codeblock

EXAMPLES#

EXAMPLE 1#

$config = New-PesterConfiguration
$config.Run.PassThru = $true
Invoke-Pester -Configuration $config

Creates a default [PesterConfiguration] object and changes the Run.PassThru option to return the result object after the test run. The configuration object is provided to Invoke-Pester to alter the default behaviour.

EXAMPLE 2#

$MyOptions = @{
Run = @{ # <- Run configuration.
PassThru = $true # <- Return result object after finishing the test run.
}
Filter = @{ # <- Filter configuration
Tag = "Core","Integration" # <- Run only Describe/Context/It-blocks with 'Core' or 'Integration' tags
}
}
$config = New-PesterConfiguration -Hashtable $MyOptions
Invoke-Pester -Configuration $config

A hashtable is created with custom options and passed to the New-PesterConfiguration to merge with the default configuration. The options in the hashtable will override the default values. The configuration object is then provided to Invoke-Pester to begin the test run using the new configuration.

PARAMETERS#

-Hashtable#

Override the default values for the options defined in the provided dictionary/hashtable. Inspect a default [PesterConfiguration] object to learn about the schema and available options.

Type: IDictionary
Parameter Sets: (All)
Aliases:
Required: False
Position: 1
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.

INPUTS#

OUTPUTS#

NOTES#

RELATED LINKS#

https://pester.dev/docs/commands/New-PesterConfiguration

https://pester.dev/docs/usage/Configuration

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

EDIT THIS PAGE#

This page was auto-generated using the comment based help in Pester 5.2.1. To edit the content of this page, change the corresponding help in the pester/Pester repository. See our contribution guide for more information.