About Help

Choose a topic from the list on the left or search for a specific topic. Choose a topic from the list or search for a specific topic.
Cmdlets  Providers  Aliases  Modules
 

Pester

Pester

Pester
	Pester 
 

SYNOPSIS

	Pester is a BDD based test runner for PowerShell. 
 

DESCRIPTION

	Pester provides a framework for running Unit Tests to execute and validate  
	PowerShell commands. 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. See about_Mocking. 
 

CREATING A PESTER TEST

	To start using Pester, you may use the New-Fixture function to scaffold both  
	a new implementation function and a test function. 
 
	C:\PS>New-Fixture deploy Clean 
 
	Creates two files: 
	./deploy/Clean.ps1 
	function clean { 
 
	} 
 
    ./deploy/clean.Tests.ps1 
    $here = Split-Path -Parent $MyInvocation.MyCommand.Path 
    $sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.' 
    . "$here\$sut" 
 
    Describe "clean" { 
 
        It "does something useful" { 
            $true | should be $false 
        } 
    } 
 
    Now you have a skeleton of a clean function with a failing test. Pester  
    considers all files containing *Tests.ps1 to be a test file (see  
    Invoke-Pester) and by default it will look for these files and run all  
    Describe blocks inside the file (See Describe). The Describe block can  
    contain several behavior validations expressed in It blocks (see It).  
    Each It block should test one thing and throw an exception if the test  
    fails. Pester will consider any It block that throws an exception to be a  
    failed test. Pester provides a set of extensions that can perform various  
    comparisons between the values emitted or altered by a test and an expected  
    value (see about_Should).  
 

RUNNNING A PESTER TEST

	Once you have some logic that you are ready to test, run the Tests file directly,  
	usually by pressing F5 in your ISE.  
	 
	To run multiple test files, get summary for the test run, to get nUnit compatible XML 
	report or to get PesterResult object use the Invoke-Pester command. You can zero in on  
	just one test (Describe block) or an entire tree of directories. 
 
	function BuildIfChanged { 
		$thisVersion=Get-Version 
		$nextVersion=Get-NextVersion 
		if($thisVersion -ne $nextVersion) {Build $nextVersion} 
		return $nextVersion 
	} 
 
	$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} 
	        } 
        } 
    } 
 
	C:\PS>Invoke-Pester 
 
	This will run all tests recursively from the current directory downwards  
	and print a report of all failing and passing tests to the console. 
 

PESTER AND CONTINUOUS INTEGRATION

	Pester integrates well with almost any build automation solution. You  
	could create a MSBuild target that calls Pester's convenience Batch file: 
 
	<Target Name="Tests"> 
	<Exec Command="cmd /c $(baseDir)pester\bin\pester.bat" /> 
	</Target> 
 
	This will start a PowerShell session, import the Pester Module and call  
	invoke pester within the current directory. If any test fails, it will  
	return an exit code equal to the number of failed tests and all test  
	results will be saved to Test.xml using NUnit's Schema allowing you to  
	plug these results nicely into most Build systems like CruiseControl,  
	TeamCity, TFS or Jenkins. 
 

OTHER EXAMPLES

	Pester's own tests. See all files in the Pester Functions folder  
	containing *Tests.ps1 
	 
	Chocolatey tests. Chocolatey is a popular PowerShell based Windows  
	package management system. It uses Pester tests to validate its own  
	functionality. 
 

SEE ALSO

about_Mocking
Describe
Context
It
New-Fixture
Invoke-Pester
about_Should
about_TestDrive