Skip to main content
Version: v6

Invoke-Pester

This page was generated

Contributions are welcome in Pester-repo.

SYNOPSIS​

Runs Pester tests

SYNTAX​

Simple (Default)​

Invoke-Pester [[-Path] <string[]>] [-ExcludePath <string[]>] [-TagFilter <string[]>]
 [-ExcludeTagFilter <string[]>] [-FullNameFilter <string[]>] [-CI] [-Output <string>] [-PassThru]
 [-Container <ContainerInfo[]>]

Advanced​

Invoke-Pester [-Configuration <PesterConfiguration>]

DESCRIPTION​

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 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 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 parameterized tests, or to mix files and script blocks, use New-PesterContainer or the Configuration parameter.

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.

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. To view, comment, or contribute to the repository, see https://github.com/Pester.

EXAMPLES​

EXAMPLE 1​

Invoke-Pester

This command runs all *.Tests.ps1 files in the current directory and its subdirectories.

EXAMPLE 2​

Invoke-Pester -Path .\Util*

This commands runs all *.Tests.ps1 files in subdirectories with names that begin with 'Util' and their subdirectories.

EXAMPLE 3​

$config = [PesterConfiguration]@{
    Should = @{ # <- Should configuration.
        ErrorAction = 'Continue' # <- Always run all Should-assertions in a test
    }
}

Invoke-Pester -Configuration $config

This example runs all *.Tests.ps1 files in the current directory and its subdirectories. It shows how advanced configuration can be used by casting a hashtable to override default settings, in this case to make Pester run all Should-assertions in a test even if the first fails.

EXAMPLE 4​

$config = New-PesterConfiguration
$config.TestResult.Enabled = $true
Invoke-Pester -Configuration $config

This example runs all *.Tests.ps1 files in the current directory and its subdirectories. It uses advanced configuration to enable testresult-output to file. Access $config.TestResult to see other testresult options like output path and format and their default values.

PARAMETERS​

-CI​

Enable Test Results and Exit after Run.

Equivalent to setting: TestResult.Enabled = $true Run.Exit = $true

To also enable CodeCoverage use this configuration option: CodeCoverage.Enabled = $true

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Configuration​

[PesterConfiguration] object for Advanced Configuration created using New-PesterConfiguration. For help on each option see about_PesterConfiguration or inspect the object.

Type: PesterConfiguration
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Advanced
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Container​

Specifies one or more ContainerInfo-objects that define containers with tests. ContainerInfo-objects are generated using New-PesterContainer. Useful for scenarios where data-driven test are generated, e.g. parametrized test files.

Type: Pester.ContainerInfo[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ExcludePath​

Specifies one or more paths to exclude from the test run. Equivalent to ConfigurationProperty Run.ExcludePath.

Type: System.String[]
DefaultValue: '@()'
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ExcludeTagFilter​

Specifies tags to exclude from the test run. Equivalent to ConfigurationProperty Filter.ExcludeTag.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-FullNameFilter​

Specifies test full names (including Describe/Context/It path) to run. Equivalent to ConfigurationProperty Filter.FullName.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Output​

Specifies the verbosity of the test output. Supports Diagnostic, Detailed, Normal, Minimal, None. Equivalent to ConfigurationProperty Output.Verbosity.

Default value is: Normal

Type: System.String
DefaultValue: Normal
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-PassThru​

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. Equivalent to ConfigurationProperty Run.PassThru. To suppress the host output, use the Output parameter with value None.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Path​

Specifies one or more paths to files containing tests. The value is a path\file name or name pattern. Wildcards are permitted.

Type: System.String[]
DefaultValue: .
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: 0
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-TagFilter​

Specifies tags to include in the test run. Only tests with matching tags will run. Equivalent to ConfigurationProperty Filter.Tag.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: Simple
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters​

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS​

OUTPUTS​

Pester.Run​

NOTES​

VERSION​

This page was generated using comment-based help in Pester 6.0.0.