The Grumpy Programmer's Guide To Building Testable PHP Applications (2015)
13. Metatesting: Understanding Mock Objects
This content originally appeared on my blog in March 2012.
One of the things that I have learned to quickly appreciate about working at Kaplan Professional is the very large suite of unit and integration tests. I believe there are 2000+ tests, and although there has been a dip in code coverage, it is still impressive to see coverage levels for most things in the 65%+ range. We’ll get it back up to where it belongs in no time.
With such an extensive array of tests, I have received an education in what it really means to write unit tests for live, production-ready code that really takes unit testing seriously. I think the biggest problem that most developers face when getting into Test Driven Development is not understanding how to efficiently use mock objects.
If you are really writing your unit tests the way you should, each test is focusing on testing one bit of functionality in isolation, which means that you will be heavily relying on mock objects to make things work. I’ve come up with an example scenario that I hope goes a long way to explaining how to effectively use mock objects.
In these examples I am using PHPUnit’s built-in support for mock objects. At Kaplan our testing engineer told me that he had tried to use Mockery but there were problems getting it to play nicely with the dependency injection container that is in use (it’s a customized version of Pimple). Can’t argue with that. Not until I experiment with Mockery myself to see if it gains us anything instead of using what comes with PHPUnit.
So here is our scenario: we have a class called Alpha, that contains a method called munge(). We wish to test that method in a unit test. what does this class look like?
1 <?php
2
3 class Alpha
4 {
5 // Omit code showing constructor...
6
7 public function munge(Foo $foo, Bar $bar)
8 {
9 $fooDetails = $foo->getDetails();
10 $fooId = $foo->getId();
11
12 $barStartDate = $bar->getStartDate();
13 $barEndDate = $bar->getEndDate();
14
15 $source = "{$fooId}|{$fooDetails}|{$barStartDate}|{$barEndDate}";
16
17 return md5('rocksalt' . $source);
18 }
19 }
My grumpy tester’s eye looks at that and immediately says “we will need to mock those Foo and Bar objects to make this test work.” First we need to look at the Foo object:
1 <?php
2 class Foo
3 {
4 // Omit code showing how we construct a Foo object
5
6 public function getId()
7 {
8 return $this->_id;
9 }
10
11 public function getDetails()
12 {
13 $tree = $this->_tree;
14 $branch = $this->_branch;
15
16 return $tree . '->' . $branch;
17 }
18 }
So it looks like this class represents one “Foo” object in the system. I omitted the constructor as it’s not really important to the lesson I’m trying to teach here. Let’s assume we have a way to generate a Foo object via some sort of mapper.
Our Alpha->munge() method expects to be passed in a Foo object and to retrieve info via getDetails() and getId() calls. Let’s start our test and mock that up.
1 <?php
2 class Test extends PHPUnit_Framework_TestCase
3 {
4
5 public function testAlphaMunge()
6 {
7 $mockFoo = $this->getMockBuilder('Foo')
8 ->disableOriginalConstructor()
9 ->getMock();
10 $mockFoo->expects($this->atLeastOnce())
11 ->method('getDetails')
12 ->will($this->returnValue('1->2'));
13 $mockFoo->expects($this->atLeastOnce())
14 ->method('getId')
15 ->will($this->returnValue('1'));
16
17 // More test fun to come
18 }
19 }
When you build a mock for use in your test, you generally have to do two things:
· create a mock of the object itself
· tell it what to do when specific methods are called
What I’ve done here is pretty standard EXCEPT for the use of that disableOriginalConstructor() method. Why is it used? Well, sometimes when you are creating a mock of an object it will often have a constructor that accepts parameters. I’m not testing to see if we can create the object, I am merely trying to simulate some of the methods of that object.
Once I’ve created the mock of the object, I then tell it what to do when I make certain method calls. Clearly I’ve just pulled some arbitrary values out of my ass for this example, but usually you can figure out what some reasonable return values are supposed to be by, you know, actually looking at the code you are mocking.
So what does our Bar object look like?
1 <?php
2 class Bar
3 {
4 // Same drill, no need to show constructor details
5
6 public function getStartDate()
7 {
8 return $this->_startDate;
9 }
10
11 public function getEndDate()
12 {
13 return $this->_endDate;
14 }
15 }
Time to add a mock Bar to our test
1 <?php
2 class Test extends PHPUnit_Framework_TestCase
3 {
4 public function testAlphaMunge()
5 {
6 $mockFoo = $this->getMockBuilder('Foo')
7 ->disableOriginalConstructor()
8 ->getMock();
9 $mockFoo->expects($this->atLeastOnce())
10 ->method('getDetails')
11 ->will($this->returnValue('1->2'));
12 $mockFoo->expects($this->atLeastOnce())
13 ->method('getId')
14 ->will($this->returnValue('1'));
15
16 $mockBar = $this->getMockBuilder('Bar')
17 ->disableOriginalConstructor()
18 ->getMock();
19 $mockBar->expects($this->atLeastOnce())
20 ->method('getStartDate')
21 ->will($this->returnValue('2012-03-27'));
22 $mockBar->expects($this->atLeastOnce())
23 ->method('getEndDate')
24 ->will($this->returnValue('2012-04-09'));
25
26 // More test fun to come
27 }
28 }
A quick note about $this->atLeastOnce(): when you mock the objects you can tell it how often you expect that method to be called. I had a long discussion about this with our testing engineer Will Parker after I posted the orginal version of this post.
We have multiple options
· $this->once() - should be used only when you REALLY want that method to be called once
· $this->atLeastOnce() - should be used when you need to do it once but aren’t sure how many times
· $this->any() - you really don’t care how many times it’s called
If you’re lazy, you’ll go with $this->any() so you don’t have to worry about it. After a discussion with Will, I have come to like the use of $this->atLeastOnce(). It’s not a deal-breaker no matter which one you choose, a lot of it comes down to personal preferences.
So now we have our two objects mocked. Now we can go back to our test and add in the creation of our Alpha class, inject the two mocks into the method we are testing, and check for expected results.
1 <?php
2 class Test extends PHPUnit_Framework_TestCase
3 {
4 public function testAlphaMunge()
5 {
6 $mockFoo = $this->getMockBuilder('Foo')
7 ->disableOriginalConstructor()
8 ->getMock();
9 $mockFoo->expects($this->atLeastOnce())
10 ->method('getDetails')
11 ->will($this->returnValue('1->2'));
12 $mockFoo->expects($this->atLeastOnce())
13 ->method('getId')
14 ->will($this->returnValue('1'));
15
16 $mockBar = $this->getMockBuilder('Bar')
17 ->disableOriginalConstructor()
18 ->getMock();
19 $mockBar->expects($this->atLeastOnce())
20 ->method('getStartDate')
21 ->will($this->returnValue('2012-03-27'));
22 $mockBar->expects($this->atLeastOnce())
23 ->method('getEndDate')
24 ->will($this->returnValue('2012-04-09'));
25
26 $source = "1|1->2|2012-03-27|2012-04-09";
27 $expectedMunge = md5('rocksalt' . $source);
28
29 $testAlpha = new Alpha();
30 $munge = $testAlpha->getMunge($mockFoo, $mockBar);
31
32 $this->assertEquals(
33 $expectedMunge,
34 $munge,
35 'Munge value should match expected'
36 );
37 }
38 }
And there you have it! A test for a specific method that uses mocks to properly isolate functionality that is required for the test to work.
I hope this blog post makes things a lot clearer when it comes to understanding the role of mocks when creating unit tests.