Applies to: Pester 3.4.0
When you crack open the Pester module, you find the New-Fixture function, which creates a script and test file pair, and the Invoke-Pester function, which runs Pester tests.
But New-Fixture is not the only way to create a Pester test and Invoke-Pester is not the only way to run a test.
In this blog post, we’ll discuss the different ways to run a Pester test, including, but not limited to, the Invoke-Pester function. In the next post, I’ll rave about the cool parameters of Invoke-Pester.
See the posts in this Pester series:
Where can I put Pester tests?
To decide where to put your Pester tests, consider how you plan to run them and when you want them to be available.
The best place to put a Pester test is in a *.Tests.ps1 file. A .Tests.ps1 script is immediately recognizable as a file of Pester tests. This is critical in a shared project, like an open source module, where collaborators might need to search for or identify tests, or verify that tests exist.
Also, by default, Invoke-Pester runs all *.Tests.ps1 files. When you make it easy for people to run your tests, they’re more likely to run them.
However, syntactically, a Pester test is a Describe block and its valid contents, including at least one It block that encloses a test. A .Tests.ps1 script is the best place to put Pester tests, but it’s not the only valid place.
You can put the Pester test in any one of these places (and probably in a few others):
- Tests script: The best place to put Pester tests is in a Tests script, that is, a *.Tests.ps1 file.
- Script: You can place Pester tests in a standard Windows PowerShell script (.ps1), including the script that contains the code that is being tested.
- Command: You can place Pester tests in a cmdlet, function, or workflow. Be sure that the code that is being tested is in a scope that the test can access.
- Module: You can place Pester tests in a *.Tests.ps1, a different .ps1, or .psm1 file in a module directory. Again, be sure that the command that is being tested is available to the test, including being in an accessible scope. To mock or test commands in a function that are not exported, enclose the tests in an InModuleScope script block. To export a test into a session, place it in an exported cmdlet, function, or workflow.
How can I run Pester tests?
The standard way to run Pester tests is by using the Invoke-Pester function. Invoke-Pester is a fantastic tool — a little dynamo in your toolbox. When you use Invoke-Pester, you get it’s terrific output and parameters.
But it’s not the only way to run a Pester test.
A Pester test consists of valid Windows PowerShell commands. We don’t think of it as such, but Describe is a Windows PowerShell function that the Pester module exports. Its contents, including Context and It blocks and Should assertions are all valid Windows PowerShell commands.
Therefore, you can run Pester tests…
- At the command line
You can run a Pester test at the command line in the console. Notice that you don’t get the little test summary that Invoke-Pester adds, but it’s otherwise the same.
- By running a scriptWhen you run a script that contains a Pester test, the Pester test runs. So, any way that you can run a script runs a Pester test, including typing the path at the command line or running in your favorite script editor.In PowerShell Studio, you can run and debug Pester tests. I like to use the Run in Console command so I can see the familiar purple, green, and red colors of the test results.
- By using Invoke-Pester
Invoke-Pester is a terrific function. You don’t need to use it to run scripts, but once you understand it fully, you’ll use it more often and enjoy its features.By default, Invoke-Pester runs all Pester tests in all .Tests.ps1 files in the local directory and all subdirectories recursively.It’s a brilliant default because it works well for continuous integration and it doesn’t duplicate other commands that require more complex command syntax to run recursively.
But, the power of Invoke-Pester is in it’s knockout parameters. I’ll save those for a separate post.