Invoke‑PesterJob

SYNOPSIS

Runs Pester tests using a job-based approach.

SYNTAX

Invoke-PesterJob [[-Path] <String[]>] [-RootPath <String>] [-Tag <String[]>] [-TestNameFilter <String[]>]
 [-ModuleName <String>] [-Output <String>] [[-CodeCoveragePath] <String[]>] [-SkipCodeCoverage] [-PassThru]
 [-EnableSourceLineMapping] [-FilterCodeCoverageResult <String[]>] [-ShowError] [-SkipRun]
 [-BuildScriptPath <String>] [-BuildScriptParameter <Hashtable>] 
 [<CommonParameters>]

DESCRIPTION

The Invoke-PesterJob command runs Pester tests using a job-based approach. It allows you to specify various parameters such as the test path, root path, module name, output verbosity, code coverage path, and more.

Its primary purpose is to run Pester tests in a separate job to avoid polluting the current session with PowerShell classes and project specific assemblies which can cause issues when building the project.

It is most helpful for projects based on the Sampler project template, but it can also be used for other projects.

EXAMPLES

EXAMPLE 1

$invokePesterJobParameters = @{
    Path = './tests/Unit/DSC_SqlAlias.Tests.ps1'
    CodeCoveragePath = './output/builtModule/SqlServerDsc/0.0.1/DSCResources/DSC_SqlAlias/DSC_SqlAlias.psm1'
}
Invoke-PesterJob @invokePesterJobParameters

Runs the Pester test DSC_SqlAlias.Tests.ps1 located in the 'tests/Unit' folder. The code coverage is based on the code in the DSC_SqlAlias.psm1 file.

EXAMPLE 2

$invokePesterJobParameters = @{
    Path = './tests'
    RootPath = 'C:\Projects\MyModule'
    Tag = 'Unit'
    Output = 'Detailed'
    CodeCoveragePath = 'C:\Projects\MyModule\coverage'
}
Invoke-PesterJob @invokePesterJobParameters

Runs Pester tests located in the 'tests' directory of the 'C:\Projects\MyModule' root path. Only tests with the 'Unit' tag will be executed. Detailed output will be displayed, and code coverage will be collected from the 'C:\Projects\MyModule\coverage' directory.

EXAMPLE 3

$invokePesterJobParameters = @{
    Path = './tests/Unit'
    SkipRun = $true
    SkipCodeCoverage = $true
    PassThru = $true
}
Invoke-PesterJob @invokePesterJobParameters

Runs the discovery phase on all the Pester tests files located in the 'tests/Unit' folder and outputs the Pester result object.

EXAMPLE 4

Invoke-PesterJob -Path './tests/Unit' -EnableSourceLineMapping -FilterCodeCoverageResult 'Get-Something'

Runs Pester tests located in the 'tests/Unit' folder with source line mapping enabled. After running, automatically processes and returns all commands that were missed for functions or classes matching 'Get-Something' with a reference to the SourceLineNumber in SourceFile.

EXAMPLE 5

Invoke-PesterJob -Path './tests/Unit' -EnableSourceLineMapping -FilterCodeCoverageResult @('Get-*', 'Set-*')

Runs Pester tests located in the 'tests/Unit' folder with source line mapping enabled. After running, automatically processes and returns all commands that were missed for functions or classes matching either 'Get-' or 'Set-' patterns with a reference to the SourceLineNumber in SourceFile.

EXAMPLE 6

Invoke-PesterJob -Path './tests/Unit' -EnableSourceLineMapping

Runs Pester tests located in the 'tests/Unit' folder with source line mapping enabled. After running, automatically processes and returns all commands that were missed with a reference to the SourceLineNumber in SourceFile for all functions and classes.

EXAMPLE 7

Invoke-PesterJob -Path './tests/Unit' -TestNameFilter 'Should do something*'

Runs only tests with names matching 'Should do something*' from the 'tests/Unit' folder. This is useful for running specific tests during development or debugging.

EXAMPLE 8

Invoke-PesterJob -Path './tests/Unit' -TestNameFilter @('Should validate input', 'Should handle errors*')

Runs tests with names matching either 'Should validate input' or 'Should handle errors*' from the 'tests/Unit' folder.

PARAMETERS

-BuildScriptParameter

Specifies a hashtable with the parameters to pass to the build script. Defaults to parameter 'Task' with a value of 'noop'.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: @{ Task = 'noop' }
Accept pipeline input: False
Accept wildcard characters: False

-BuildScriptPath

Specifies the path to the build script. If not specified, it defaults to 'build.ps1' in the root path. This is used to ensure that the test environment is configured correctly, for example required modules are available in the session. It is also used to ensure to find the specific Pester module used by the project.

Type: String
Parameter Sets: (All)
Aliases:

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

-CodeCoveragePath

Specifies the paths to one or more the code coverage files (script or module script files). If not provided the default path for code coverage is the content of the built module. This parameter also has tab completion support. Just write part of the script file name and press tab to get a list of available script files matching the input, or if only one file matches, it will be auto-completed.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-EnableSourceLineMapping

Indicates whether to enable source line mapping for code coverage results. When enabled, this feature maps code coverage lines from the built module files back to their corresponding lines in the source files using ModuleBuilder's Convert-LineNumber command. This also automatically enables the PassThru parameter as it is required for this feature. Requires ModuleBuilder module to be available.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-FilterCodeCoverageResult

Specifies one or more filter patterns for code coverage results when EnableSourceLineMapping is used. The patterns support wildcards and are used to filter commands by function or class name. If not specified, all missed lines are returned.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-ModuleName

Specifies the name of the module to test. If not specified, it will be inferred based on the project type.

Type: String
Parameter Sets: (All)
Aliases:

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

-Output

Specifies the output verbosity level. Valid values are 'Normal', 'Detailed', 'None', 'Diagnostic', and 'Minimal'. Default is 'Detailed'.

Type: String
Parameter Sets: (All)
Aliases:

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

-PassThru

Indicates whether to pass the Pester result object through.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-Path

Specifies one or more paths to the Pester test files. If not specified, the current location is used. This also has tab completion support. Just write part of the test script file name and press tab to get a list of available test files matching the input, or if only one file matches, it will be auto-completed.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: (Get-Location).Path
Accept pipeline input: False
Accept wildcard characters: False

-RootPath

Specifies the root path for the Pester tests. If not specified, the current location is used.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: (Get-Location).Path
Accept pipeline input: False
Accept wildcard characters: False

-ShowError

Indicates whether to display detailed error information. When using this to debug a test it is recommended to run as few tests as possible, or just the test having issues, to limit the amount of error information displayed.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-SkipCodeCoverage

Indicates whether to skip code coverage.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-SkipRun

Indicates whether to skip running the tests, this just runs the discovery phase. This is useful when you want to see what tests would be run without actually running them. To actually make use of this, the PassThru parameter should also be specified. Suggest to also use the parameter SkipCodeCoverage.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-Tag

Specifies the tags to filter the Pester tests.

Type: String[]
Parameter Sets: (All)
Aliases:

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

-TestNameFilter

Specifies the test names to filter. Tests with names that match any of the provided patterns will be executed. Supports wildcards and can be used to run specific tests. This parameter is useful for AI agents and automation scenarios that need to focus on specific tests.

Type: String[]
Parameter Sets: (All)
Aliases: TestName, Test

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

NOTES

This function requires the Pester module to be imported. If the module is not available, it will attempt to run the build script to ensure the required modules are available in the session.

When EnableSourceLineMapping is used, the ModuleBuilder module is required unless running in a Sampler project environment where it is assumed to be available.

RELATED LINKS