Powershell BDD style testing framework
Clone or download
Pull request Compare This branch is 2 commits ahead, 648 commits behind pester:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Examples
Functions
Snippets
bin
en-US
vendor
.gitattributes
.gitignore
Build.bat
CHANGELOG.md
LICENSE
Pester.Tests.ps1
Pester.nuspec
Pester.psd1
Pester.psm1
README.md
build.psake.ps1
chocolateyInstall.ps1
nunit_schema_2.5.xsd

README.md

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 inside of PowerShell. Pester follows a file naming convention for naming tests to be discovered by pester at test time and a simple set of functions that expose a Testing 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 system.

Pester also contains a powerful set of Mocking Functions that allow tests to mimic and mock the functionality of any command inside of a piece of powershell code being tested.

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
}

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 downwards and print a report of all failing and passing tests to the console.

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 commands run from cmd.exe 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.

Some further reading and resources: