• Windows PowerShell
• Pester

Applies to: Pester 3.4.0

In How to Run a Pester Test, I talked about the different places that you can put your Pester days and the different ways to run them, including, but not limited to, the Invoke-Pester function. Today, I’ll talk about the parameters of Invoke-Pester function that let you determine which tests run. Next, I’ll show you how to pass parameters to a Pester test file.

By default, Invoke-Pester runs all *.Tests.ps1 files in the local directory and its subdirectories. That’s a useful default, but the parameters of Invoke-Pester let you control the alternatives.

See the posts in this Pester series:

• How to Run a Pester Test
• Invoke-Pester: Running Selected Tests
• How to Pass Parameters to a Pester Test Script
• Testing Pester Code Coverage

Run all Tests.ps1 files in a path

To run all *.Tests.ps1 files in a particular directory or collection of directories, use the Script parameter. The Script parameter of Invoke-Pester was originally named Path, but it does so many things that they had to come up with a more generic name for it.

When you use the Script parameter of Invoke-Pester and give it paths to one or more directories, Invoke-Pester runs all .Tests.ps1 files in all subdirectories of the directories recursively. This is terrific for testing modules and other projects in progress. It supports wildcard characters, too.

For example, this command runs all *.Tests.ps1 files in the two specified directories and their subdirectories.

Invoke-Pester -Script C:\GitHub\MyProject, D:\Working\*\1.0

But, you can tell it to run other types of files.

Run tests in other files

To direct Invoke-Pester to run any file, enter the path and file name in the value of the Script parameter. For example, this command tells Invoke-Pester to run the elusively named Test-ScriptWithPesterTest.ps1 file.

Invoke-Pester -Script C:\GitHub\MyProject\Test-ScriptWithPesterTest.ps1

Invoke-Pester runs the files that you specify as the value of the Script parameter, just as though you ran them at the command line, including code that is not part of the Pester test.

You can even use Invoke-Pester to run PowerShell scripts that contain no tests, like my PowerShell profile. It dutifully reports that no tests passed or failed.

PS C:\> Invoke-Pester C:\Users\JuneB\Documents\WindowsPowerShell\profile.ps1

Tests completed in 0ms
Passed: 0 Failed: 0 Skipped: 0 Pending: 0 Inconclusive: 0

Be sure to include the file name of non-.Tests.ps1 files. If you use a wildcard, Invoke-Pester reverts to its default, which runs only the .Tests.ps1 files (recursively).

Invoke-Pester -Script C:\GitHub\MyProject\*.ps1   # Runs only .Tests.ps1 files

You can specify both directories and files. Again, if you specify a directory, Invoke-Pester runs only the .Tests.ps1 files in the directory (recursively).

Invoke-Pester -Script C:\GitHub\MyProject\Project.ps1, D:\Working\*\1.0

And, you can specify a particular .Tests.ps1 file, too.

Invoke-Pester -Script C:\GitHub\MyProject\Project.ps1, C:\Scripts\Module.Help.Tests.ps1

But, you can also select tests within files

Run Selected Pester Tests

To run only certain tests within the files specified by the Script parameter, use the TestName, Tag, and ExcludeTag parameters of Invoke-Pester. These parameter filter within the files specified by the paths in the Script parameter; they never expand its range.

The TestName parameter runs only Describe blocks with the specified test names or name patterns. It is case-insensitive. Remember that TestName looks only at names of Describe blocks, even though the InModuleScope, Context, and It blocks have required names.

For example, this command runs only the Describe blocks with names that include “parameter.”

Invoke-Pester C:\Scripts\Module.Help.Tests.ps1 -TestName '*parameter*'
 
#In file
Describe "gets parameter descriptions" {...}  # runs this one
Describe "gets correct types of parameters" {...} # runs this one, too
Describe "gets mandatory" { It "parameter is mandatory" {...}...} # doesn't run this one

If you specify multiple TestName values, Invoke-Pester runs tests that have any of the values in the Describe name (it ORs the values).

Invoke-Pester C:\Scripts\Module.Help.Tests.ps1 -TestName '*correct*', "*mandatory*"
 
#In file
Describe "gets parameter descriptions" {...}  # doesn't run this one
Describe "gets correct parameter types" {...} # runs this one
Describe "gets mandatory" { It "parameter is mandatory" {...}...} # runs this one

The Tag and ExcludeTag parameters run Describe blocks that have the specified tags, that is, the values of the Tag parameter of the Describe function. They are case-insensitive, but they don’t support wildcard characters. And, at least in Pester 3.4.0, they cannot find tags that include spaces. So they find “UnitTest,” but cannot find “Unit Test,” even if its an exact match for a tag.

Invoke-Pester C:\Scripts\Module.Help.Tests.ps1 -Tag UnitTest, 'Unit test'
 
#In file
Describe "finds the synopsis" -Tag UnitTest {...}         #Runs this test
Describe "finds the return value" -Tag 'Unit Test' {...}  #Doesn't run this test

When you specify multiple tags, Invoke-Pester runs tests that have any of the listed tags (it ORs the tags).

Invoke-Pester C:\Scripts\Module.Help.Tests.ps1 -Tag Unit, Regression
 
#In file
Describe "gets parameter descriptions" -Tag Unit       {...}     # Runs this test
Describe "gets mandatory value" -Tag regression {...}            # Runs this test
Describe "gets correct parameter types" {...}                    # Doesn't run this test

But, when you use the TestName and Tag parameters in the same command (at least in version 3.4.0), Invoke-Pester combines the requirements and runs only the tests that have the specified TestName and Tag (it ANDs the requirements).

Invoke-Pester C:\Scripts\Module.Help.Tests.ps1 -TestName '*parameter*' -Tag UnitTest
 
#In file
Describe "gets parameter descriptions" -Tag UnitTest {...} # Runs this test
Describe "gets correct parameter types" {...}              # Doesn't run this test
Describe "gets mandatory value" -Tag UnitTest {...}        # Doesn't run this test

Predictably, the ExcludeTag parameter runs all Describe blocks except for those that match any of the Tag values. If a test is included by the Tag parameter and excluded by the ExcludeTag parameter, ExcludeTag takes precedence over Tag, and the test does not run.

Interestingly, tests that are filtered out by TestName, Tag, and ExcludeTag are not counted as skipped. Only tests that have the Skip parameter of the It function are listed in the Skip count value.

For example, there are multiple tests in the file, but only one has the NullTest tag. Notice that the Skipped value is 0.

PS C:\ > C:\Scripts\Module.Help.Tests.ps1 -TestName '*parameter*' -Tag NullTest

Describing gets parameter descriptions

[+] parameter description is not null 42ms
Tests completed in 0ms

Passed: 1 Failed: 0 Skipped: 0 Pending: 0 Inconclusive: 0

That’s pretty high-resolution control. Next, we’ll talk about passing parameters to a Pester test script.

Learning Pester? Check out Real-World Test-Driven Development with Pester. The code and slides are in Github at https://github.com/juneb/PesterTDD.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. You can reach her at This email address is being protected from spambots. You need JavaScript enabled to view it. or follow her on Twitter at @juneb_get_help.

• Prev
• Next