Invoke-Pester: Running Selected Tests
- Details
- Written by June Blender
- Last Updated: 18 July 2016
- Created: 14 June 2016
- Hits: 26173
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:
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.
For licensed customers, use the forum associated with your product in our Product Support Forums for Registered Customers.
For users of trial versions, please post in our Former and Future Customers - Questions forum.