PHP, Zend Framework and Other Crazy Stuff
Archive for May, 2010
Mockery 0.6 Released – PHP Mock Object Framework
May 27th
Mockery is a Mock Object framework for PHP, compatible with most unit testing frameworks including PHPUnit. Its purpose is to implement a lightweight grammer for the creation and testing of Mock Objects, Test Stubs, and Test Spies as an alternative to the built-in support offered by PHPUnit, etc.
Mockery is hosted on Github (http://github.com/padraic/mockery) where you can find an extensive README covering its API and uses. The Mockery 0.6 release may be installed from the SurviveTheDeepEnd.com PEAR channel at http://pear.survivethedeepend.com.
Mockery 0.6 features:
- Full Mock Object and Test Stub support
- Lightweight fluent API
- Flexible mocking and stubbing
- Object Interaction Recording
- Natural language syntax and expectation constructs
- Supports generic (untyped) mock objects for rapid prototyping
- Simple partial mocking of real objects
- Both local and global Mock Object call ordering
- Built-in return value queue for repeated method calls
- Support for default expectations
- Support for expectation replacement and stacking
- Fluent API/Law of Demeter mocking
If that sounds complex, it’s not! Mockery can be picked up and used with little study.
Why Mockery?
Mockery’s objective is to simplify Mock Objects in PHP while maintaining significant flexibility and a default level of intuitive behaviour. In Mockery, Mock Objects behave exactly as you write them with liberal interpretations otherwise applied. Mockery was born out of my own need to innovate the use of Mock Objects in PHP and draw away from the original import of aging Mocking approaches from Java. While Java (and almost every other programming language) has been steadily progressing its mock object libraries, and complementing them with new solutions, PHP has a relatively static approach depending on similarly static library components. That result has seen solutions using clunky APIs, poorly described syntax and behaviour, a lack of focus on the practice of using Mock Objects, user confusion, and raised barriers to new programmers trying to learn about Mock Objects. Mockery is one potential solution to these problems. Also, as a dedicated Test-Driven Design user, I really want something that clicks immediately and doesn’t have any gotchas.
Installation
Mockery may be installed from its PEAR channel using:
pear channel-discover pear.survivethedeepend.com
pear install deepend/Mockery
Mockery is written in PHP 5.3 (I know, but all you 5.2 users will get there eventually 
). It is released under a New BSD license.
Example
The README offers a good look at some examples, and explains the API in a lot of detail. If you are trying to figure something out, the README undoubtedly has a section for it. Here’s an API example (assuming Mockery namespace used as MK). We’re capturing an interaction where we login into a bookmarking service, check for the existance of a “php” tagged bookmark, add three more bookmarks and then recheck if a “php” tag exists (twice for fun). We’re mocking the service since we don’t actually want to mess with a real account! Following the description closely…
[geshi lang=php]$service = \MK::mock(‘MyService’);
$service->shouldReceive(‘login’)->with(‘user’, ‘pass’)->once()->andReturn(true);
$service->shouldReceive(‘hasBookmarksTagged’)->with(‘php’)->once()->andReturn(false);
$service->shouldReceive(‘addBookmark’)->with(‘/^http:/’, \MK::type(‘string’))->times(3)->andReturn(true);
$service->shouldReceive(‘hasBookmarksTagged’)->with(‘php’)->twice()->andReturn(true);[/geshi]
The example uses some of the basic parts of Mockery to describe some interaction with a mocked web service class (obviously
also stubbing the web service’s responses in terms of booleans). The setup is straightforward, easy to follow, and there’s zero
misinterpretations possible. Our description was likewise simple and uncomplicated. The third line just shows two argument matchers at work, a default regex (intrepreted from any string argument set so long as any eventual string comparison fails and it’s a valid regex) and a Type matcher set to match any valid string.
To put this into some perspective, here’s an equivalent attempt using PHPUnit in a similar order of thought (excerpt from a test).
[geshi lang=php]$service = $this->getMock(‘MyService’);
$service->expects($this->once())->method(‘login’)->with(‘user’, ‘pass’)->will($this->returnValue(true));
$service->expects($this->once())->method(‘hasBookmarksTagged’)->with(‘php’)->will($this->returnValue(false));
$service->expects($this->exactly(3))->method(‘addBookmark’)
->with($this->matchesRegularExpression(‘/^http:/’), $this->isType(‘string’))
->will($this->returnValue(true));
$service->expects($this->exactly(2))->method(‘hasBookmarksTagged’)->with(‘php’)->will($this->returnValue(true));[/geshi]
Besides the differences in API, there are others. If MyService is just intended as a fake unimplemented object (the class doesn’t exist), Mockery carries on and just uses a generic Mock instance without error. PHPUnit will throw an exception, however, stating that login() is not a valid method. If we assume the class is real, but missing some methods, the same thing happens and PHPUnit complains about missing methods. Eventually, you’ll get the idea to implement the dependent class… If we add all the relevant methods (say, we mock an interface with all methods declared), PHPUnit STILL fails. This time complaining that hasBookmarksTagged() was expected only once. This occurs because PHPUnit has no capacity for stacking later expectations, and so, it ignores the second (and any later) ones. We can fix that by merging both into a single expectation using:
[geshi lang=php]$service = $this->getMock(‘MyService’);
$service->expects($this->once())->method(‘login’)->with(‘user’, ‘pass’)->will($this->returnValue(true));
$service->expects($this->exactly(3))->method(‘hasBookmarksTagged’)->with(‘php’)
->will($this->onConsecutiveCalls(false, true, true));
$service->expects($this->exactly(3))->method(‘addBookmark’)
->with($this->matchesRegularExpression(‘/^http:/’), $this->isType(‘string’))
->will($this->returnValue(true));[/geshi]
Using OnConsecutiveCalls() to create a return value queue, and merging the two stacked expectations, allows the PHPUnit variant to pass. Unlike Mockery, if there were ten hasBookmarksTagged() calls, you would need to add all ten return values (Mockery let’s you set the last return value to act infinitely). The merging simply demonstrates that complex class interactions across classes will fall victim to the need to constantly merge expectations until they are unreadable and explain little.
While your mileage may vary, Mockery just doesn’t need reworking, deep thought or extra work. Just state what you want your Mock Object to do in plain unconfused English according to your natural thought order! If nothing else, it helps make the expected interaction obvious which makes your tests more readable and explicit.
Feedback
Any issues can be reported via our Github hosted issue tracker. If you wish to discuss Mockery in more detail, you’re welcome to join the mailing list at http://groups.google.com/group/phpmockery.
Mockery: From Mock Objects to Test Spies
May 23rd
With next week seeing the formal release of Mockery 0.6 which is currently fermenting on Github at http://github.com/padraic/mockery, I’m already looking forward to next piece of the puzzle arriving with 0.7. Mockery is an opportunity to being something new and fresh to the PHP mock objects environment beyond a far neater flexible API.
If you follow the test double debate in other languages there are two popular concepts making their presence felt. The first is that the over-specified definitions of test doubles (we have dummy objects, test stubs, mock objects, test spies and fake objects) do more harm than good since in reality we never really distinguish (nor care to) between most of them. In most cases we just sort of wing it, using our own concepts and intent to create test doubles which do what we want with little thought as to the kind of test double we’re creating. In the end, the definitions all merge together into a spectrum of possible behaviours we add as and if needed.
The second is that we’re seeing a lot more attention over whether Mock Objects are the best way to do things. Nobody doubts they have the right idea with Mock Objects, but the upfront setting of expectations may come across as unintuitive. A typical test begins with exercising code, and thereafter we typically make assertions on the behaviour (whether it be a resulting state change or an object interaction). Mock Objects reverse that – we expect first, and then we exercise the code.
With the future (before end of June) 0.7 release, Mockery will offer an alternative approach to the traditional Expect-Exercise-Verify cycle called the Test Spy. 0.6 already offers a measure of that capability through its ability to record interactions, though recording is completely automated and geared primarily towards comparing two sets of source code which should behave identically (e.g. during refactoring). The new Test Spy implementation will be API driven, using a similar form to Mockery’s existing Mock Object approach.
Why Test Spies?
Using Test Spies returns to the test based approach of exercising code first, and then making assertions. There’s a reason why this cyclical approach is used in unit testing. It’s easy to understand and makes sense from the start. Applying it to what we do with Mock Objects can make using Test Doubles in general easier to learn and teach. It may also remove barriers to entry for those who simply never understood Mock Objects or loathed their expectation setup. Test Spies also operate on a selective basis – where Mock Objects require upfront expectations to define how they will behave, Test Spies just do what you need them to and then allow selective assertions afterwards (i.e. you only need to test what you want to test).
The difference, once you see the code, is very subtle. Not unusually for testing practices, subtle differences in approach rely on the YMMV yardstick. Some people prefer the upfront expectation setting, others find the after-use assertion approach easier to understand or as more applicable to their thinking.
By supporting both approaches as equal citizens, Mockery once again lets go of the proverbial rope around your neck tied there by Java traditions. You’ll be free to go with whatever approach you find yourself preferring. Better, they can both co-exist in relative peace since they are drawn from the same framework and both share nearly all of the exact same API elements, with the exact same meaning. Whether you prefer Mock Objects or Test Spies (both equally are capable of being used as Test Stubs), they are both equally understandable by anyone using Mockery.
As a means of showing the differences, here are two test cases. The first is written using the Mock Object terminology, the second using the Test Spy terminology – each actually achieves the exact same goal.
[geshi lang=php]use \Mockery as M;
class StarshipTest extends PHPUnit_Framework_TestCase
{
public function testEngagingWarpDrive()
{
$engineering = M::mock(‘Engineering’);
$engineering->shouldReceive(‘prepForWarpFactor’)->with(8)->once()->andReturn(true);
$engineering->shouldReceive(‘engage’)->once();
$starship = new Starship($engineering);
$starship->accelerateToWarp(8);
}
}[/geshi]
Or, using a Test Spy approach.
[geshi lang=php]use \Mockery as M;
class StarshipTest extends PHPUnit_Framework_TestCase
{
public function testEngagingWarpDrive()
{
$engineering = M::mock(‘Engineering’);
$engineering->whenReceives(‘prepForWarpFactor’)->thenReturn(true);
$starship = new Starship($engineering);
$starship->accelerateToWarp(8);
$engineering->assertReceived(‘prepForWarpFactor’)->with(8)->once();
$engineering->assertReceived(‘engage’)->once();
}
}[/geshi]
To demonstrate the selective assertion approach, what if we just didn’t care about whether or not the engage() method was used? In that case, we could just drop it from the assertions altogether – never mentioning it in the test at all. In the Mock Object approach, we cannot do this – mocking means we must set all methods expected (otherwise the methods would not exist on the mock). We could even drop the assertion on prepForWarpFactor, although we still need to retain the stubbing of its return value (since it’s needed).
Supporting Test Spies and Mock Objects also has the other obvious benefit that you can switch modes effortlessly. There will always be cases where expectation setting is preferable over assertions and vice versa. Both have their uses even if you heavily prefer any one over the other.
Watch for the Mockery 0.6 release next week! I’ll follow through with Test Spies in 0.7 once I get the final API down (working on making it even shorter than our Mock Object API can achieve).
Recent Comments