Disclaimer
This post title can be misleading. Method order is just an implementation detail that should not be tested as PHPSpec philosophy is to test your public API, not the implementation as it would lead to fragile tests. Fundamentalists might say that following example should not be performed in PHPSpec but with a functional test. Sadly, when you start with BDD, you may not know that your class will end in a situation where you’re somehow forced to be sure of method invocation order; in such cases you have two choices: drop the spec for this particular class and go on with a functional test or follow this post that provide a solution for the situation where being dependent from implementation could be, somehow, acceptable as test failure due to implementation changes (ie.: method order change) is what we’re trying to reach.
For more information about PHPSpec philosophy, you can read this blog post by Everzet
Scenario
We need a class that keeps a log of operations performed onto an entity in a way that, for each operation, we can recreate a step-by-step status change. For the sake of this example, we log the whole entity in the operation stack though we could keep only property changes.
This is the entity
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
<?php class Entity { private $prop1; private $prop2; public function copy() { return clone $this; } public function changeProp1($newValue) { $this->prop1 = $newValue; } public function changeProp2($newValue) { $this->prop2 = $newValue; } } |
We introduced a copy method to have full control on the stub: using PHP built in __clone method would make us lose control over the process.
This is the spec file that we wrote before writing the code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
<?php namespace spec; use PhpSpec\ObjectBehavior; use Prophecy\Prophet; class EntityTransformerSpec extends ObjectBehavior { /** * @var Prophet */ private $prophet; function let() { $this->prophet = new Prophet(); } function it_is_initializable() { $this->shouldHaveType(\EntityTransformer::class); } function it_logs_every_change() { $entity = $this->prophet->prophesize(\Entity::class); $operations = [ \EntityTransformer::CHANGE_PROP1 => 10, \EntityTransformer::CHANGE_PROP2 => -20 ]; $clonedEntity1 = $this->prophet->prophesize(\Entity::class); $clonedEntity2 = $this->prophet->prophesize(\Entity::class); $entity->copy()->willReturn($clonedEntity1, $clonedEntity2); $entity->changeProp1(10)->shouldBeCalled(); $entity->changeProp2(-20)->shouldBeCalled(); $this ->getTransformationLog($entity, $operations) ->shouldBeEqualTo([ 'entity' => $entity, 'log' => [ [\EntityTransformer::CHANGE_PROP1, $clonedEntity1], [\EntityTransformer::CHANGE_PROP2, $clonedEntity2], ] ]); $this->prophet->checkPredictions(); } } |
There are two ways to create stubs: one is PHPSpec automagic injection thanks to type hint. Other is to create through Prophecy.
Usually we adopt a strategy where all collaborators are type hinted whereas other doubles are created directly trough Prophecy. This means that you need to check predictions for mocks directly with
$this->prophet->checkPredictions()
If you miss this line, no predictions of mock created thought Prophecy are checked and, probably, your tests will be green even if they shouldn’t.
Writing test before the code helps you to spot this problem as first run should always be a failing one.
“Never trust a test you’ve never seen failing
– Anonymous”
And this is the code
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
<?php class EntityTransformer { const CHANGE_PROP1 = 'cp1'; const CHANGE_PROP2 = 'cp2'; public function getTransformationLog(Entity $entity, array $operations) { $result = ['entity' => $entity, 'log' => []]; foreach ($operations as $operation => $value) { $result['log'][] = $this->transformEntity($entity, $operation, $value); } return $result; } private function transformEntity(Entity $entity, $operation, $value) { $entityCopy = $entity->copy(); if ($operation == self::CHANGE_PROP1) { $entity->changeProp1($value); } elseif ($operation == self::CHANGE_PROP2) { $entity->changeProp2($value); } return [$operation, $entityCopy]; } } |
Running PHPSpec will result in green examples
By the way this test is not proving anything about test correctness: it says that in output we should have a log with entity and its cloned copies along with operations performed onto original entity. We have no way to check if clonedEntity1 and clonedEntity2 has a copy of the entity before the operations were performed (that is the goal of this spec). We can’t simply check, by getters on clones, if values before operations are kept as them are doubles so they are not actual entities.
Let’s pretend that I shift copy method after original entity modification for error
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<?php class EntityTransformer { [...] private function transformEntity(Entity $entity, $operation, $value) { if ($operation == self::CHANGE_PROP1) { $entity->changeProp1($value); } elseif ($operation == self::CHANGE_PROP2) { $entity->changeProp2($value); } $entityCopy = $entity->copy(); // shifted after changes return [$operation, $entityCopy]; } } |
Running tests again results in
This spec is clearly wrong but there is no straightforward solution provided by PHPSpec to get what we need (as said before, PHPSpec is not design for this kind of implementation checks)
Deferred Expectations
When a method is invoked on a mock, PHPSpec/Prophecy immediately checks if it is registered as expected calls; if it is not, an exception is raised. This is the key concept: register expectations (changeProp1 and changeProp2) only if a method is called (copy). In this way if no copy is called before changeProp1 or changeProp2, the expectations are never registered and any call on those method will result in Exceptions. This is what I call “deferred expectation” (or conditional expectation if you prefer).
This is how Spec file change
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
function it_logs_every_change() { [...] // $entity->copy()->willReturn($clonedEntity1, $clonedEntity2); $entity->copy()->will(function() use ($clonedEntity1, $clonedEntity2) { $this->changeProp1(10)->shouldBeCalled(); $this->changeProp2(-20)->shouldBeCalled(); $this->copy()->willReturn($clonedEntity2); return $clonedEntity1; }); // $entity->changeProp1(10)->shouldBeCalled(); // $entity->changeProp2(-20)->shouldBeCalled(); [...] } |
If we now run last EntityTransformer code (the one with copy in the wrong place) we get
Bingo!
Looking at spec code above you will notice that
|
1 2 |
$this->changeProp1(10)->shouldBeCalled(); $this->changeProp2(-20)->shouldBeCalled(); |
are registered as expectations only when copy method is called (thanks to closure; this is a deferred behavior). It’s worth to notice that copy will also return first cloned object along with second invocation copy canned method.
If no copy is ever invoked before changeProp* method, example will be broken as no canned response is registered to answer to changeProp* invocation.
If EntityTransformer code is brought back to original and correct version, example will return quickly green
If this example does not make any sense to you, just think about Doctrine entity manager: you can expect that persist($entity) and flush should be called but, as long as you don’t guarantee the correct order of this calls, you can never be sure that spec is fine.
That’s all. Hope this quick trick will help you with your spec and, as usual, don’t take this as a rule of thumb: try to keep your spec files independent of implementation as much as you can.
