PHPUnit: expects method meaning

Question

When I create a new mock I need to call the expects method. What exactly it does? What about its arguments?

$todoListMock = $this->getMock('\Model\Todo_List');         $todoListMock->expects($this->any())             ->method('getItems')             ->will($this->returnValue(array($itemMock))); 

I can't find the reason anywhere (I've tried docs). I've read the sources but I can't understand it.

Answer 1

expects() - Sets how many times you expect a method to be called:

$mock = $this->getMock('nameOfTheClass', array('firstMethod','secondMethod','thirdMethod')); $mock->expects($this->once())      ->method('firstMethod')      ->will($this->returnValue('value')); $mock->expects($this->once())      ->method('secondMethod')      ->will($this->returnValue('value')); $mock->expects($this->once())      ->method('thirdMethod')      ->will($this->returnValue('value')); 

If you know, that method is called once use $this->once() in expects(), otherwise use $this->any()

see:
PHPUnit mock with multiple expects() calls

https://phpunit.de/manual/current/en/test-doubles.html#test-doubles.stubs

http://www.slideshare.net/mjlivelyjr/advanced-phpunit-testing

Answer 2

A look into the source code will tell you:

/**  * Registers a new expectation in the mock object and returns the match  * object which can be infused with further details.  *  * @param  PHPUnit_Framework_MockObject_Matcher_Invocation $matcher  * @return PHPUnit_Framework_MockObject_Builder_InvocationMocker  */ public function expects(PHPUnit_Framework_MockObject_Matcher_Invocation $matcher); 

And the PHPUnit Manual lists the available Matchers at

• https://phpunit.de/manual/current/en/test-doubles.html#test-doubles.mock-objects.tables.matchers

• any() returns a matcher that matches when the method it is evaluated for is executed zero or more times.
• never() returns a matcher that matches when the method it is evaluated for is never executed.
• atLeastOnce() returns a matcher that matches when the method it is evaluated for is executed at least once.
• once() returns a matcher that matches when the method it is evaluated for is executed exactly once.
• exactly(int $count) returns a matcher that matches when the method it is evaluated for is executed exactly $count times.
• at(int $index) returns a matcher that matches when the method it is evaluated for is invoked at the given $index.