Configuration

Advanced interface

Advanced interface uses PesterConfiguration object which contains all options that you can provide to Pester and contains descriptions for all the configuration sections and as well as default values. Here is what you see when you look at the default Debug section of the object:

(New-PesterConfiguration).Debug | Format-List

ShowFullErrors         : Show full errors including Pester internal stack. This property is deprecated, and if set to true it will override Output.StackTraceVerbosity to 'Full'. (False, default: False)
WriteDebugMessages     : Write Debug messages to screen. (False, default: 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. (System.String[], default: System.String[])
ShowNavigationMarkers  : Write paths after every block and test, for easy navigation in VSCode. (False, default: 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. (False,
                         default: False)

The configuration object can be constructed either using the New-PesterConfiguration command or by casting a hashtable to the PesterConfiguration type. Here are three different ways to the same goal:

# import module before creating the object
Import-Module Pester
# get default from static property
$configuration = New-PesterConfiguration
# adding properties & discover via intellisense
$configuration.Run.Path = 'C:\MyProject\tests'
$configuration.Filter.Tag = 'Acceptance'
$configuration.Filter.ExcludeTag = 'WindowsOnly'
$configuration.Should.ErrorAction = 'Continue'
$configuration.CodeCoverage.Enabled = $true

# cast whole hashtable to configuration
$configuration = [PesterConfiguration]@{
    Run = @{
        Path = 'C:\MyProject\tests'
    }
    Filter = @{
        Tag = 'Acceptance'
        ExcludeTag = 'WindowsOnly'
    }
    Should = @{
        ErrorAction = 'Continue'
    }
    CodeCoverage = @{
        Enabled = $true
    }
}

# cast from empty hashtable to get default
$configuration = [PesterConfiguration]@{}
$configuration.Run.Path = 'C:\MyProject\tests'
# cast hashtable to section
$configuration.Filter = @{
        Tag = 'Acceptance'
        ExcludeTag = 'WindowsOnly'
    }
$configuration.Should.ErrorAction = 'Continue'
$configuration.CodeCoverage.Enabled = $true

This configuration object contains all the options that are currently supported and the Simple interface is internally translates to this object internally. It is the source of truth for the defaults and configuration. The Intermediate api will be figured out later, as well as all the other details.

PesterPreference

There is one more way to provide the configuration object which is $PesterPreference. On Invoke-Pester (in case of interactive execution Invoke-Pester is called inside of the first Describe) the preference is collected and merged with the configuration object if provided. This allows you to configure everything that you would via Invoke-Pester also when you are running interactively (via F5). You can also use this to define the defaults for your session by putting $PesterPreference into your PowerShell profile.

Here is a simple example of enabling Mock logging output while running interactively :

$PesterPreference = New-PesterConfiguration
$PesterPreference.Debug.WriteDebugMessages = $true
$PesterPreference.Debug.WriteDebugMessagesFrom = "Mock"

BeforeAll {
    function a { "hello" }
}
Describe "pester preference" {
    It "mocks" {
        Mock a { "mock" }
        a | Should -Be "mock"
    }
}

Running tests from 1 files.

Running tests from 'C:\Users\jajares\Desktop\mck.tests.ps1'
Describing pester preference
Mock: Setting up mock for a.
Mock: We are in a test. Returning mock table from test scope.
Mock: Resolving command a.
Mock: Searching for command in the caller scope.
Mock: Found the command a in the caller scope.
Mock: Mock does not have a hook yet, creating a new one.
Mock: Defined new hook with bootstrap function PesterMock_b0bde5ee-1b4f-4b8f-b1dd-aef38b3bc13d and aliases a.
Mock: Adding a new default behavior to a.
Mock: Mock bootstrap function a called from block Begin.
Mock: Capturing arguments of the mocked command.
Mock: Mock for a was invoked from block Begin.
Mock: Getting all defined mock behaviors in this and parent scopes for command a.
Mock: We are in a test. Finding all behaviors in this test.
Mock: Found behaviors for 'a' in the test.
Mock: Finding all behaviors in this block and parents.
... shortened Mock does a lot of stuff
Verifiable: False
Mock: We are in a test. Returning mock table from test scope.
Mock: Removing function PesterMock_b0bde5ee-1b4f-4b8f-b1dd-aef38b3bc13d and aliases a for .
  [+] mocks 857ms
Tests completed in 1.12s
Tests Passed: 1, Failed: 0, Skipped: 0, Inconclusive: 0, NotRun: 0

PesterConfiguration Options

TestResult and CodeCoverage auto-enable

In Pester v6 you don't have to set TestResult.Enabled or CodeCoverage.Enabled separately. Setting any non-default option in the TestResult or CodeCoverage section automatically enables that feature, so a report you configured never silently goes unwritten. For example, setting TestResult.OutputPath is enough to produce a test-result file.

This section was generated using Pester 6.0.0-rc2.

Run

General runtime options for Pester including tests containers to execute.

Option	Description	Type	Default
Run.Path	Directories to be searched for tests, paths directly to test files, or combination of both.	string[]	@('.')
Run.ExcludePath	Directories or files to be excluded from the run.	string[]	@()
Run.ScriptBlock	ScriptBlocks containing tests to be executed.	scriptblock[]	@()
Run.Container	ContainerInfo objects containing tests to be executed.	ContainerInfo[]	@()
Run.TestExtension	Filter used to identify test files.	string	'.Tests.ps1'
Run.Exit	Exit with non-zero exit code when the test run fails. Exit code is always set to $LASTEXITCODE even when this option is $false. When used together with Throw, throwing an exception is preferred.	bool	$false
Run.Throw	Throw an exception when test run fails. When used together with Exit, throwing an exception is preferred.	bool	$false
Run.PassThru	Return result object to the pipeline after finishing the test run.	bool	$false
Run.SkipRun	Runs the discovery phase but skips run. Use it with PassThru to get object populated with all tests.	bool	$false
Run.Parallel	EXPERIMENTAL: Run test files in parallel, each file in its own runspace, using PowerShell 7+ 'ForEach-Object -Parallel'. Files that contain the '#pester:no-parallel' directive run sequentially after the parallel batch. Falls back to a sequential run on Windows PowerShell 5.1, when non-file containers (ScriptBlock) are used, when CodeCoverage is enabled, or when Run.SkipRemainingOnFailure is set to 'Run'.	bool	$false
Run.BeforeContainer	EXPERIMENTAL: One or more ScriptBlocks run before each test file is discovered and run, in both sequential and parallel runs. Use it to import helper modules or dot-source setup that the parent session would normally provide, e.g. { . './setup.ps1' } - this is especially useful in parallel runs, where each worker starts from a clean runspace. One scriptblock is usually enough and can dot-source as many files as needed. When set, the convention file is ignored; when not set, Pester dot-sources a 'Pester.BeforeContainer.ps1' from the repository root (Run.RepoRoot) if one is present.	scriptblock[]	@()
Run.ParallelThrottleLimit	EXPERIMENTAL: Maximum number of test files to run at the same time when Run.Parallel is enabled, passed through to 'ForEach-Object -Parallel -ThrottleLimit'. The default 0 uses all available processors ([Environment]::ProcessorCount). Set a lower number to cap how many runspaces run concurrently. Only used when Run.Parallel is enabled.	int	0
Run.SkipRemainingOnFailure	Skips remaining tests after failure for selected scope, options are None, Run, Container and Block.	string	'None'
Run.FailOnNullOrEmptyForEach	Fails discovery when -ForEach is provided $null or @() in a block or test. Can be overridden for a specific Describe/Context/It using -AllowNullOrEmptyForEach.	bool	$true
Run.RepoRoot	Root directory of the repository. Found by searching for the .git directory recursively. When not found, the current working directory is used.	string	'C:\MyProject'

Filter

Filter options to include/exclude tests and blocks in the targeted containers using tags, name or location. Include by default when no include filters are provided. Exclude filters take precedence.

Option	Description	Type	Default
Filter.Tag	Tags of Describe, Context or It to be run.	string[]	@()
Filter.ExcludeTag	Tags of Describe, Context or It to be excluded from the run.	string[]	@()
Filter.Line	Filter by file and scriptblock start line, useful to run parsed tests programmatically to avoid problems with expanded names. Explicit filter that overrides -Skip. Example: 'C:\tests\file1.Tests.ps1:37'	string[]	@()
Filter.ExcludeLine	Exclude by file and scriptblock start line, takes precedence over Line.	string[]	@()
Filter.FullName	Full name of test with -like wildcards, joined by dot. Example: '*.describe Get-Item.test1'	string[]	@()

CodeCoverage

Options to enable and configure Pester's code coverage feature.

Option	Description	Type	Default
CodeCoverage.Enabled	Enable CodeCoverage.	bool	$false
CodeCoverage.OutputFormat	Format to use for code coverage report. Possible values: JaCoCo, Cobertura	string	'JaCoCo'
CodeCoverage.OutputPath	Path relative to the current directory where code coverage report is saved.	string	'coverage.xml'
CodeCoverage.OutputEncoding	Encoding of the output file.	string	'UTF8'
CodeCoverage.Path	Directories or files to be used for code coverage, by default the Path(s) from general settings are used, unless overridden here.	string[]	@()
CodeCoverage.ExcludeTests	Exclude tests from code coverage. This uses the TestFilter from general configuration.	bool	$true
CodeCoverage.RecursePaths	Will recurse through directories in the Path option.	bool	$true
CodeCoverage.CoveragePercentTarget	Target percent of code coverage that you want to achieve, default 75%.	decimal	75
CodeCoverage.UseBreakpoints	When false, use Profiler based tracer to do CodeCoverage instead of using breakpoints.	bool	$false
CodeCoverage.SingleHitBreakpoints	Remove breakpoint when it is hit. This increases performance of breakpoint based CodeCoverage.	bool	$true
CodeCoverage.ReportRoot	Root path for the code coverage report. Uses Run.RepoRoot by default.	string	$null

TestResult

Export options to output Pester's testresult to known file formats like NUnit and JUnit XML.

Option	Description	Type	Default
TestResult.Enabled	Enable TestResult.	bool	$false
TestResult.OutputFormat	Format to use for test result report. Possible values: NUnitXml, NUnit2.5, NUnit3 or JUnitXml	string	'NUnitXml'
TestResult.OutputPath	Path relative to the current directory where test result report is saved.	string	'testResults.xml'
TestResult.OutputEncoding	Encoding of the output file.	string	'UTF8'
TestResult.TestSuiteName	Set the name assigned to the root 'test-suite' element.	string	'Pester'

Should

Options to control the behavior of the Pester's Should assertions.

Option	Description	Type	Default
Should.ErrorAction	Controls if Should throws on error. Use 'Stop' to throw on error, or 'Continue' to fail at the end of the test.	string	'Stop'
Should.DisableV5	Disables usage of Should -Be assertions, that are replaced by Should-Be in version 6.	bool	$false

Debug

Debug configuration for Pester. ⚠ Use at your own risk!

Option	Description	Type	Default
Debug.ShowFullErrors	Show full errors including Pester internal stack. This property is deprecated, and if set to true it will override Output.StackTraceVerbosity to 'Full'.	bool	$false
Debug.WriteDebugMessages	Write Debug messages to screen.	bool	$false
Debug.WriteDebugMessagesFrom	Write Debug messages from a given source, WriteDebugMessages must be set to true for this to work. You can use like wildcards to get messages from multiple sources, as well as * to get everything.	string[]	@('Discovery', 'Skip', 'Mock', 'CodeCoverage')
Debug.ShowNavigationMarkers	Write paths after every block and test, for easy navigation in VSCode.	bool	$false
Debug.ShowStartMarkers	Write an indication when each test starts.	bool	$false
Debug.ReturnRawResultObject	Returns unfiltered result object, this is for development only. Do not rely on this object for additional properties, non-public properties will be renamed without previous notice.	bool	$false

Output

Options to customize the console output generated by Pester.

Option	Description	Type	Default
Output.Verbosity	The verbosity of output, options are None, Normal, Detailed and Diagnostic.	string	'Normal'
Output.StackTraceVerbosity	The verbosity of stacktrace output, options are None, FirstLine, Filtered and Full.	string	'Filtered'
Output.CIFormat	The CI format of error output in build logs, options are None, Auto, AzureDevops and GithubActions.	string	'Auto'
Output.CILogLevel	The CI log level in build logs, options are Error and Warning.	string	'Error'
Output.RenderMode	The mode used to render console output, options are Auto, Ansi, ConsoleColor and Plaintext.	string	'Auto'

TestDrive

Options to configure the TestDrive feature.

Option	Description	Type	Default
TestDrive.Enabled	Enable TestDrive.	bool	$true

TestRegistry

Options to configure the TestRegistry feature. TestRegistry is only available on Windows-systems.

Option	Description	Type	Default
TestRegistry.Enabled	Enable TestRegistry.	bool	$true