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[]>] [<CommonParameters>]

Advanced

Invoke-Pester [-Configuration <PesterConfiguration>] [<CommonParameters>]

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

-Path

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

Type: String[]
Parameter Sets: Simple
Aliases:

Required: False
Position: 1
Default value: .
Accept pipeline input: False
Accept wildcard characters: False

-ExcludePath

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

Type: String[]
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-TagFilter

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

Type: String[]
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExcludeTagFilter

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

Type: String[]
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FullNameFilter

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

Type: String[]
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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: SwitchParameter
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Output

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

Default value is: Normal

Type: String
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: Normal
Accept pipeline input: False
Accept wildcard characters: False

-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: SwitchParameter
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-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: ContainerInfo[]
Parameter Sets: Simple
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Configuration

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

Type: PesterConfiguration
Parameter Sets: Advanced
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.

INPUTS

OUTPUTS

Pester.Run

NOTES

RELATED LINKS

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

https://pester.dev/docs/quick-start

VERSION

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