about_Mocking.help.txt

TOPIC
	Mocking

SYNOPSIS
	Pester provides a set of Mocking functions making it easy to fake dependencies 
	and also to verify behavior. Using these mocking functions can allow you to 
	"shim" a data layer or mock other complex functions that already have their 
	own tests.

DESCRIPTION
	With the set of Mocking functions that Pester exposes, one can:

	- Mock the behavior of ANY powershell command.
	- Verify that specific commands were (or were not) called.
	- Verify the number of times a command was called with a set of specified 
	  parameters.

MOCKING FUNCTIONS
	See Get-Help for any of the below functions for more detailed information.

	Mock
		Mocks the behavior of an existing command with an alternate 
		implementation.

	Assert-VerifiableMocks
		Checks if any Verifiable Mock has not been invoked. If so, this will 
		throw an exception.

	Assert-MockCalled
		Checks if a Mocked command has been called a certain number of times 
		and throws an exception if it has not.

EXAMPLE
	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" {
    	Mock Get-Version {return 1.1}
    	Context "Wnen there are Changes" {
    		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 "Wnen there are no Changes" {
    		Mock Get-NextVersion -MockWith {return 1.1}
    		Mock Build -MockWith {}

    		$result = BuildIfChanged

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

    Notice how 'Mock Get-Version {return 1.1}' is declared within the 
    Describe block. This allows all context blocks inside the describe to 
    use this Mock. If a context scoped mock, mocks Get-Version, that mock 
    will override the describe scoped mock within that contex tif both mocks 
    apply to the parameters passed to Get-Version.

LIMITATIONS
	The SUT (code being tested) that calls the actual commands that you have 
	mocked must not be executing from inside a module. Otherwise, the mocked 
	commands will not be invoked and the real commands will run. The SUT must 
	be in the same Script scope as the test. So it must be either dot sourced, 
	in the same file, or in a script file.

SEE ALSO
	Mock
	Assert-VerifiableMocks
	Assert-MockCalled
	Describe
	Context
	It