Build Status:

Pester 3.0 has been released! To see a list of changes in this version, refer to the What's New in Pester 3.0? Wiki page.

---

Pester

Pester provides a framework for running unit tests to execute and validate PowerShell commands from within PowerShell. Pester consists of a simple set of functions that expose a testing domain-specific language (DSL) for isolating, running, evaluating and reporting the results of PowerShell commands.

Pester tests can execute any command or script that is accessible to a Pester test file. This can include functions, cmdlets, modules and scripts. Pester can be run in ad-hoc style in a console or it can be integrated into the build scripts of a continuous integration (CI) system.

Pester also contains a powerful set of mocking functions in which tests mimic any command functionality within the tested PowerShell code.

A Pester Test

BuildChanges.ps1

function Build ($version) {
  write-host "A build was run for version: $version"
}

function BuildIfChanged {
  $thisVersion=Get-Version
  $nextVersion=Get-NextVersion
  if($thisVersion -ne $nextVersion) {Build $nextVersion}
  return $nextVersion
}

# Imagine that the following functions have heavy side-effect
function Get-Version {
  throw New-Object NotImplementedException
}

function Get-NextVersion {
  throw New-Object NotImplementedException
}

BuildChanges.Tests.ps1

$here = Split-Path -Parent $MyInvocation.MyCommand.Path
$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'
. "$here\$sut"

Describe "BuildIfChanged" {
  Context "When there are changes" {
    Mock Get-Version {return 1.1}
    Mock Get-NextVersion {return 1.2}
    Mock Build {} -Verifiable -ParameterFilter {$version -eq 1.2}

    $result = BuildIfChanged

      It "Builds the next version" {
          Assert-VerifiableMocks
      }
      It "Returns the next version number" {
          $result | Should Be 1.2
      }
    }
  Context "When there are no changes" {
    Mock Get-Version -MockWith {return 1.1}
    Mock Get-NextVersion -MockWith {return 1.1}
    Mock Build {}

    $result = BuildIfChanged

      It "Should not build the next version" {
          Assert-MockCalled Build -Times 0 -ParameterFilter {$version -eq 1.1}
      }
    }
}

Running Tests

C:\PS> Invoke-Pester

This will run all tests inside of files named *.Tests.ps1 recursively from the current directory and print a report of all failing and passing test results to the console.

C:\PS> Invoke-Pester -TestName BuildIfChanged

You can also run specific tests by using the -TestName parameter of the Invoke-Pester command. The above example runs all tests with a Describe block named BuildIfChanged. If you want to run multiple tests, you can pass a string array into the -TestName parameter, similar to the following example:

C:\PS> Invoke-Pester -TestName BuildIfChanged, BaconShouldBeCrispy

Continuous Integration with Pester

Pester integrates well with almost any build automation solution. There are several options for this integration:

• The -OutputFile parameter allows you to export data about the test execution. Currently, this parameter allows you to produce NUnit-style XML output, which any modern CI solution should be able to read.
• The -PassThru parameter can be used if your CI solution supports running PowerShell code directly. After Pester finishes running, check the FailedCount property on the object to determine whether any tests failed, and take action from there.
• The -EnableExit switch causes Pester to exit the current PowerShell session with an error code. This error code will be the number of failed tests; 0 indicates success.

As an example, there is also a file named Pester.bat in the bin folder which shows how you might integrate with a CI solution that does not support running PowerShell directly. By wrapping a call to Invoke-Pester in a batch file, and making sure that batch file returns a non-zero exit code if any tests fail, you can still use Pester even when limited to cmd.exe commands in your CI jobs.

Whenever possible, it's better to run Invoke-Pester directly (either in an interactive PowerShell session, or using CI software that supports running PowerShell steps in jobs). This is the method that we test and support in our releases.

For Further Learning:

• Getting started with Pester
• Testing your scripts with Pester, Assertions and more
• Pester Wiki
• Google Discussion Group
• C:\PS> Import-Module ./pester.psm1; Get-Help about_pester
• Microsoft's PowerShell test suite itself is being converted into Pester tests. See the PowerShell-Tests repository.
• Note: The following two links were for Pester v1.0. The syntax shown, particularly for performing assertions with Should, is no longer applicable to later versions of Pester.
  • powershell-bdd-testing-pester-screencast
  • pester-bdd-for-the-system-administrator