November 21, 2012 09:56 pm GMT

Mockery: A Better Way

Mockery is a PHP extension that offers a superior mocking experience, particularly when compared to PHPUnit. While PHPUnit’s mocking framework is powerful, Mockery offers a more natural language with a Hamcrest-like set of matchers. In this article, I’ll compare the two mocking frameworks and highlight the best features of Mockery.

Mockery offers a set of mocking-related matchers that are very similar to a Hamcrest dictionary, offering a very natural way to express mocked expectations. Mockery does not override or conflict with PHPUnit’s built-in mocking functions; in fact, you can use them both at the same time (and even in the same test method).

---

Installing Mockery

There are multiple ways to install Mockery; here are the most common methods.

Use Composer

Create a file called composer.json in you project’s root folder, and add the following code to that file:

{    "require": {        "Mockery/Mockery": ">=0.7.2"    }}

Next, simply install Composer in your project’s root folder using the following command:

curl -s https://getcomposer.org/installer | php

Finally, install any required dependencies (including Mockery) with this command:

php composer.phar install

With everything installed, let’s ensure that our Mockery installation works. For the sake of simplicity, I’ll assume that you have a folder, called Test in your project’s root directory. All of the examples in this tutorial will reside in this folder. Here’s the code I’ve used to ensure that Mockery works with my project:

//Filename: JustToCheckMockeryTest.phprequire_once '../vendor/autoload.php';class JustToCheckMockeryTest extends PHPUnit_Framework_TestCase {protected function tearDown() {\Mockery::close();}function testMockeryWorks() {$mock = \Mockery::mock('AClassToBeMocked');$mock->shouldReceive('someMethod')->once();$workerObject = new AClassToWorkWith;$workerObject->doSomethingWit($mock);}}class AClassToBeMocked {}class AClassToWorkWith {function doSomethingWit($anotherClass) {return $anotherClass->someMethod();}}

Linux Users: Use Your Distro’s Packages

Some Linux distributions make it easy to install Mockery, but only a handful provide a Mockery package for their system. The following list are the only distros I’m aware of:

• Sabayon: equo install Mockery
• Fedora / RHE: yum install Mockery

Use PEAR

PEAR fans can install Mockery by issuing the following commands:

sudo pear channel-discover pear.survivethedeepend.comsudo pear channel-discover hamcrest.googlecode.com/svn/pearsudo pear install --alldeps deepend/Mockery

Installing from Source

Installing from GitHub is for the real geeks! You can always grab the latest version of Mockery through its GitHub repository.

git clone git://github.com/padraic/Mockery.gitcd Mockerysudo pear channel-discover hamcrest.googlecode.com/svn/pearsudo pear install --alldeps package.xml

---

Creating our First Mocked Object

Let’s mock some objects before we define any expectations. The following code will modify the previous example to include both PHPUnit and Mockery examples:

//Filename: MockeryABetterWayOfMockingTest.phprequire_once '../vendor/autoload.php';class MockeryVersusPHPUnitGetMockTest extends PHPUnit_Framework_TestCase {function testCreateAMockedObject() {// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');// With Mockery$mockeryMock = \Mockery::mock('AClassToBeMocked');}}class AClassToBeMocked {}

Mockery allows you to define mocks for classes that do not exist.

The first line ensures that we have access to Mockery. Next, we create a test class, called MockeryVersusPHPUnitGetMockTest, which has a method, testCreateAMockedObject(). The mocked class, AClassToBeMocked, is completely empty at this time; in fact, you could completely remove the class without causing the test to fail.

The testCreateAMockedObject() test method defines two objects. The first is a PHPUnit mock, and the second is created with Mockery. Mockery’s syntax is:

$mockedObject = \Mockery::mock('SomeClassToBeMocked');

---

Assign Simple Expectations

Mocks are commonly used to verify an object’s behavior (primarily its methods) by specifying what are called expectations. Let’s set up a few simple expectations.

Expect a Method to be Called

Probably the most common expectation is one that expects a specific method call. Most mocking frameworks allow you to specify the amount of calls you expect a method to receive. We’ll begin with a simple single call expectation:

//Filename: MockeryABetterWayOfMockingTest.phprequire_once '../vendor/autoload.php';class MockeryVersusPHPUnitGetMockTest extends PHPUnit_Framework_TestCase {protected function tearDown() {\Mockery::close();}function testExpectOnce() {$someObject = new SomeClass();// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');$phpunitMock->expects($this->once())->method('someMethod');// Exercise for PHPUnit$someObject->doSomething($phpunitMock);// With Mockery$mockeryMock = \Mockery::mock('AnInexistentClass');$mockeryMock->shouldReceive('someMethod')->once();// Exercise for Mockery$someObject->doSomething($mockeryMock);}}class AClassToBeMocked {function someMethod() {}}class SomeClass {function doSomething($anotherObject) {$anotherObject->someMethod();}}

This code configures an expectation for both PHPUnit and Mockery. Let’s start with the former.

Some Linux distributions make it easy to install Mockery.

We use the expects() method to define an expectation to call someMethod() once. But in order for PHPUnit to work correctly, we must define a class called AClassToBeMocked, and it must have a someMethod() method.

This is a problem. If you are mocking a lot of objects and developing using TDD principles for a top-down design, you would not want to create all the classes and methods before your test. Your test should fail for the right reason, that the expected method was not called, instead of a critical PHP error with no relation to the real implementation. Go ahead and try to remove the someMethod() definition from AClassToBeMocked, and see what happens.

Mockery, on the other hand, allows you to define mocks for classes that do not exist.

Notice that the above example creates a mock for AnInexistentClass, which as its name implies, does not exist (nor does its someMethod() method).

At the end of the above example, we define the SomeClass class to exercise our code. We initialize an object, called $someObject in the first line of the test method, and we effectively exercise the code after defining our expectations.

Please Note: Mockery evaluates expectations on its close() method. For this reason, you should always have a tearDown() method on your test that calls \Mockery::close(). Otherwise, Mockery gives false positives.

Expect More Than One Call

As I noted previously, most mocking frameworks have the ability to specify expectations for multiple method calls. PHPUnit uses the $this->exactly() construct for this purpose. The following code defines the expectations for calling a method multiple times:

function testExpectMultiple() {$someObject = new SomeClass();// With PHPUnit 2 times$phpunitMock = $this->getMock('AClassToBeMocked');$phpunitMock->expects($this->exactly(2))->method('someMethod');// Exercise for PHPUnit$someObject->doSomething($phpunitMock);$someObject->doSomething($phpunitMock);// With Mockery 2 times$mockeryMock = \Mockery::mock('AnInexistentClass');$mockeryMock->shouldReceive('someMethod')->twice();// Exercise for Mockery$someObject->doSomething($mockeryMock);$someObject->doSomething($mockeryMock);// With Mockery 3 times$mockeryMock = \Mockery::mock('AnInexistentClass');$mockeryMock->shouldReceive('someMethod')->times(3);// Exercise for Mockery$someObject->doSomething($mockeryMock);$someObject->doSomething($mockeryMock);$someObject->doSomething($mockeryMock);}

Mockery provides two different methods to better suit your needs. The first method, twice(), expects two method calls. The other method is times(), which lets you specify an amount. Mockery’s approach is much cleaner and easier to read.

Returning Values

Another common use for mocks is to test a method’s return value. Naturally, both PHPUnit and Mockery have the means to verify return values. Once again, let’s start with something simple.

Simple Return Values

The following code contains both PHPUnit and Mockery code. I also updated SomeClass to provide a testable return value.

class MockeryVersusPHPUnitGetMockTest extends PHPUnit_Framework_TestCase {protected function tearDown() {\Mockery::close();}// [...] //function testSimpleReturnValue() {$someObject = new SomeClass();$someValue = 'some value';// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');$phpunitMock->expects($this->once())->method('someMethod')->will($this->returnValue($someValue));// Expect the returned value$this->assertEquals($someValue, $someObject->doSomething($phpunitMock));// With Mockery$mockeryMock = \Mockery::mock('AnInexistentClass');$mockeryMock->shouldReceive('someMethod')->once()->andReturn($someValue);// Expect the returned value$this->assertEquals($someValue, $someObject->doSomething($mockeryMock));}}class AClassToBeMocked {function someMethod() {}}class SomeClass {function doSomething($anotherObject) {return $anotherObject->someMethod();}}

Both PHPUnit’s and Mockery’s API is straight-forward and easy to use, but I still find Mockery to be cleaner and more readable.

Returning Different Values

Frequent unit testers can testify to complications with methods that return different values. Unfortunately, PHPUnit’s limited $this->at($index) method is the only way to return different values from the same method. The following code demonstrates the at() method:

function testDemonstratePHPUnitCallIndexing() {$someObject = new SomeClass();$firstValue = 'first value';$secondValue = 'second value';// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');$phpunitMock->expects($this->at(0))->method('someMethod')->will($this->returnValue($firstValue));$phpunitMock->expects($this->at(1))->method('someMethod')->will($this->returnValue($secondValue));// Expect the returned value$this->assertEquals($firstValue, $someObject->doSomething($phpunitMock));$this->assertEquals($secondValue, $someObject->doSomething($phpunitMock));}

This code defines two separate expectations and makes two different calls to someMethod(); so, this test passes. But let’s introduce a twist and add a double call in the tested class:

// [...] //function testDemonstratePHPUnitCallIndexingOnTheSameClass() {$someObject = new SomeClass();$firstValue = 'first value';$secondValue = 'second value';// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');$phpunitMock->expects($this->at(0))->method('someMethod')->will($this->returnValue($firstValue));$phpunitMock->expects($this->at(1))->method('someMethod')->will($this->returnValue($secondValue));// Expect the returned value$this->assertEquals('first value second value', $someObject->concatenate($phpunitMock));}class SomeClass {function doSomething($anotherObject) {return $anotherObject->someMethod();}function concatenate($anotherObject) {return $anotherObject->someMethod() . ' ' . $anotherObject->someMethod();}}

The test still passes. PHPUnit expects two calls to someMethod() that happen inside the tested class when performing the concatenation via the concatenate() method. The first call returns the first value, and the second call returns the second value. But, here’s the catch: what would happen if you double the assertion? Here’s the code:

function testDemonstratePHPUnitCallIndexingOnTheSameClass() {$someObject = new SomeClass();$firstValue = 'first value';$secondValue = 'second value';// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');$phpunitMock->expects($this->at(0))->method('someMethod')->will($this->returnValue($firstValue));$phpunitMock->expects($this->at(1))->method('someMethod')->will($this->returnValue($secondValue));// Expect the returned value$this->assertEquals('first value second value', $someObject->concatenate($phpunitMock));$this->assertEquals('first value second value', $someObject->concatenate($phpunitMock));}

It returns the following error:

Failed asserting that two strings are equal.--- Expected+++ Actual@@ @@-'first value second value'+' '

PHPUnit continues counting between distinct calls to concatenate(). By the time the second call in the last assertion occurs, $index is at the values 2 and 3. You can make the test pass by modifying your expectations to consider the two new steps, like this:

function testDemonstratePHPUnitCallIndexingOnTheSameClass() {$someObject = new SomeClass();$firstValue = 'first value';$secondValue = 'second value';// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');$phpunitMock->expects($this->at(0))->method('someMethod')->will($this->returnValue($firstValue));$phpunitMock->expects($this->at(1))->method('someMethod')->will($this->returnValue($secondValue));$phpunitMock->expects($this->at(2))->method('someMethod')->will($this->returnValue($firstValue));$phpunitMock->expects($this->at(3))->method('someMethod')->will($this->returnValue($secondValue));// Expect the returned value$this->assertEquals('first value second value', $someObject->concatenate($phpunitMock));$this->assertEquals('first value second value', $someObject->concatenate($phpunitMock));}

You can probably live with this code, but Mockery makes this scenario trivial. Don’t believe me? Take a look:

function testMultipleReturnValuesWithMockery() {$someObject = new SomeClass();$firstValue = 'first value';$secondValue = 'second value';// With Mockery$mockeryMock = \Mockery::mock('AnInexistentClass');$mockeryMock->shouldReceive('someMethod')->andReturn($firstValue, $secondValue, $firstValue, $secondValue);// Expect the returned value$this->assertEquals('first value second value', $someObject->concatenate($mockeryMock));$this->assertEquals('first value second value', $someObject->concatenate($mockeryMock));}

Like PHPUnit, Mockery uses index counting, but we don’t have to worry about indices. Instead, we simply list all the expected values, and Mockery returns them in order.

Additionally, PHPUnit returns NULL for unspecified indexes, but Mockery always returns the last specified value. That’s a nice touch.

Try Multiple Methods with Indexing

Let’s introduce a second method into our code, the concatWithMinus() method:

class SomeClass {function doSomething($anotherObject) {return $anotherObject->someMethod();}function concatenate($anotherObject) {return $anotherObject->someMethod() . ' ' . $anotherObject->someMethod();}function concatWithMinus($anotherObject) {return $anotherObject->anotherMethod() . ' - ' . $anotherObject->anotherMethod();}}

This method behaves similarly to concatenate(), but it concatenates the string values with “ - ” as opposed to a single space. Because these two methods perform similar tasks, it makes sense to to test them inside the same test method to avoid duplicate testing.

As demonstrated in the above code, the second function uses a different mocked method called anotherMethod(). I made this change to force us to mock both methods in our tests. Our mockable class now looks like this:

class AClassToBeMocked {function someMethod() {}function anotherMethod() {}}

Testing this with PHPUnit might look like the following:

function testPHPUnitIndexingOnMultipleMethods() {$someObject = new SomeClass();$firstValue = 'first value';$secondValue = 'second value';// With PHPUnit$phpunitMock = $this->getMock('AClassToBeMocked');// First and second call on the semeMethod:$phpunitMock->expects($this->at(0))->method('someMethod')->will($this->returnValue($firstValue));$phpunitMock->expects($this->at(1))->method('someMethod')->will($this->returnValue($secondValue));// Expect the returned value$this->assertEquals('first value second value', $someObject->concatenate($phpunitMock));// First and second call on the anotherMethod:$phpunitMock->expects($this->at(0))->method('anotherMethod')->will($this->returnValue($firstValue));$phpunitMock->expects($this->at(1))->method('anotherMethod')->will($this->returnValue($secondValue));// Expect the returned value$this->assertEquals('first value - second value', $someObject->concatWithMinus($phpunitMock));}

The logic is sound. Define two different expectations for each method and specify the return value. This works only with PHPUnit 3.6 or newer.