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: IDictionaryParameter Sets: (All)Aliases:
Required: FalsePosition: 1Default value: NoneAccept pipeline input: FalseAccept 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.