diff options
Diffstat (limited to 'vendor/phpspec/prophecy/README.md')
| -rw-r--r-- | vendor/phpspec/prophecy/README.md | 411 |
1 files changed, 0 insertions, 411 deletions
diff --git a/vendor/phpspec/prophecy/README.md b/vendor/phpspec/prophecy/README.md deleted file mode 100644 index fbb58f69b..000000000 --- a/vendor/phpspec/prophecy/README.md +++ /dev/null @@ -1,411 +0,0 @@ -# Prophecy - -[](https://packagist.org/packages/phpspec/prophecy) -[](https://travis-ci.org/phpspec/prophecy) - -Prophecy is a highly opinionated yet very powerful and flexible PHP object mocking -framework. Though initially it was created to fulfil phpspec2 needs, it is flexible -enough to be used inside any testing framework out there with minimal effort. - -## A simple example - -```php -<?php - -class UserTest extends PHPUnit\Framework\TestCase -{ - private $prophet; - - public function testPasswordHashing() - { - $hasher = $this->prophet->prophesize('App\Security\Hasher'); - $user = new App\Entity\User($hasher->reveal()); - - $hasher->generateHash($user, 'qwerty')->willReturn('hashed_pass'); - - $user->setPassword('qwerty'); - - $this->assertEquals('hashed_pass', $user->getPassword()); - } - - protected function setUp() - { - $this->prophet = new \Prophecy\Prophet; - } - - protected function tearDown() - { - $this->prophet->checkPredictions(); - } -} -``` - -## Installation - -### Prerequisites - -Prophecy requires PHP 7.2.0 or greater. - -### Setup through composer - -First, add Prophecy to the list of dependencies inside your `composer.json`: - -```json -{ - "require-dev": { - "phpspec/prophecy": "~1.0" - } -} -``` - -Then simply install it with composer: - -```bash -$> composer install --prefer-dist -``` - -You can read more about Composer on its [official webpage](http://getcomposer.org). - -## How to use it - -First of all, in Prophecy every word has a logical meaning, even the name of the library -itself (Prophecy). When you start feeling that, you'll become very fluid with this -tool. - -For example, Prophecy has been named that way because it concentrates on describing the future -behavior of objects with very limited knowledge about them. But as with any other prophecy, -those object prophecies can't create themselves - there should be a Prophet: - -```php -$prophet = new Prophecy\Prophet; -``` - -The Prophet creates prophecies by *prophesizing* them: - -```php -$prophecy = $prophet->prophesize(); -``` - -The result of the `prophesize()` method call is a new object of class `ObjectProphecy`. Yes, -that's your specific object prophecy, which describes how your object would behave -in the near future. But first, you need to specify which object you're talking about, -right? - -```php -$prophecy->willExtend('stdClass'); -$prophecy->willImplement('SessionHandlerInterface'); -``` - -There are 2 interesting calls - `willExtend` and `willImplement`. The first one tells -object prophecy that our object should extend a specific class. The second one says that -it should implement some interface. Obviously, objects in PHP can implement multiple -interfaces, but extend only one parent class. - -### Dummies - -Ok, now we have our object prophecy. What can we do with it? First of all, we can get -our object *dummy* by revealing its prophecy: - -```php -$dummy = $prophecy->reveal(); -``` - -The `$dummy` variable now holds a special dummy object. Dummy objects are objects that extend -and/or implement preset classes/interfaces by overriding all their public methods. The key -point about dummies is that they do not hold any logic - they just do nothing. Any method -of the dummy will always return `null` and the dummy will never throw any exceptions. -Dummy is your friend if you don't care about the actual behavior of this double and just need -a token object to satisfy a method typehint. - -You need to understand one thing - a dummy is not a prophecy. Your object prophecy is still -assigned to `$prophecy` variable and in order to manipulate with your expectations, you -should work with it. `$dummy` is a dummy - a simple php object that tries to fulfil your -prophecy. - -### Stubs - -Ok, now we know how to create basic prophecies and reveal dummies from them. That's -awesome if we don't care about our _doubles_ (objects that reflect originals) -interactions. If we do, we need to use *stubs* or *mocks*. - -A stub is an object double, which doesn't have any expectations about the object behavior, -but when put in specific environment, behaves in specific way. Ok, I know, it's cryptic, -but bear with me for a minute. Simply put, a stub is a dummy, which depending on the called -method signature does different things (has logic). To create stubs in Prophecy: - -```php -$prophecy->read('123')->willReturn('value'); -``` - -Oh wow. We've just made an arbitrary call on the object prophecy? Yes, we did. And this -call returned us a new object instance of class `MethodProphecy`. Yep, that's a specific -method with arguments prophecy. Method prophecies give you the ability to create method -promises or predictions. We'll talk about method predictions later in the _Mocks_ section. - -#### Promises - -Promises are logical blocks, that represent your fictional methods in prophecy terms -and they are handled by the `MethodProphecy::will(PromiseInterface $promise)` method. -As a matter of fact, the call that we made earlier (`willReturn('value')`) is a simple -shortcut to: - -```php -$prophecy->read('123')->will(new Prophecy\Promise\ReturnPromise(array('value'))); -``` - -This promise will cause any call to our double's `read()` method with exactly one -argument - `'123'` to always return `'value'`. But that's only for this -promise, there's plenty others you can use: - -- `ReturnPromise` or `->willReturn(1)` - returns a value from a method call -- `ReturnArgumentPromise` or `->willReturnArgument($index)` - returns the nth method argument from call -- `ThrowPromise` or `->willThrow($exception)` - causes the method to throw specific exception -- `CallbackPromise` or `->will($callback)` - gives you a quick way to define your own custom logic - -Keep in mind, that you can always add even more promises by implementing -`Prophecy\Promise\PromiseInterface`. - -#### Method prophecies idempotency - -Prophecy enforces same method prophecies and, as a consequence, same promises and -predictions for the same method calls with the same arguments. This means: - -```php -$methodProphecy1 = $prophecy->read('123'); -$methodProphecy2 = $prophecy->read('123'); -$methodProphecy3 = $prophecy->read('321'); - -$methodProphecy1 === $methodProphecy2; -$methodProphecy1 !== $methodProphecy3; -``` - -That's interesting, right? Now you might ask me how would you define more complex -behaviors where some method call changes behavior of others. In PHPUnit or Mockery -you do that by predicting how many times your method will be called. In Prophecy, -you'll use promises for that: - -```php -$user->getName()->willReturn(null); - -// For PHP 5.4 -$user->setName('everzet')->will(function () { - $this->getName()->willReturn('everzet'); -}); - -// For PHP 5.3 -$user->setName('everzet')->will(function ($args, $user) { - $user->getName()->willReturn('everzet'); -}); - -// Or -$user->setName('everzet')->will(function ($args) use ($user) { - $user->getName()->willReturn('everzet'); -}); -``` - -And now it doesn't matter how many times or in which order your methods are called. -What matters is their behaviors and how well you faked it. - -Note: If the method is called several times, you can use the following syntax to return different -values for each call: - -```php -$prophecy->read('123')->willReturn(1, 2, 3); -``` - -This feature is actually not recommended for most cases. Relying on the order of -calls for the same arguments tends to make test fragile, as adding one more call -can break everything. - -#### Arguments wildcarding - -The previous example is awesome (at least I hope it is for you), but that's not -optimal enough. We hardcoded `'everzet'` in our expectation. Isn't there a better -way? In fact there is, but it involves understanding what this `'everzet'` -actually is. - -You see, even if method arguments used during method prophecy creation look -like simple method arguments, in reality they are not. They are argument token -wildcards. As a matter of fact, `->setName('everzet')` looks like a simple call just -because Prophecy automatically transforms it under the hood into: - -```php -$user->setName(new Prophecy\Argument\Token\ExactValueToken('everzet')); -``` - -Those argument tokens are simple PHP classes, that implement -`Prophecy\Argument\Token\TokenInterface` and tell Prophecy how to compare real arguments -with your expectations. And yes, those classnames are damn big. That's why there's a -shortcut class `Prophecy\Argument`, which you can use to create tokens like that: - -```php -use Prophecy\Argument; - -$user->setName(Argument::exact('everzet')); -``` - -`ExactValueToken` is not very useful in our case as it forced us to hardcode the username. -That's why Prophecy comes bundled with a bunch of other tokens: - -- `IdenticalValueToken` or `Argument::is($value)` - checks that the argument is identical to a specific value -- `ExactValueToken` or `Argument::exact($value)` - checks that the argument matches a specific value -- `TypeToken` or `Argument::type($typeOrClass)` - checks that the argument matches a specific type or - classname -- `ObjectStateToken` or `Argument::which($method, $value)` - checks that the argument method returns - a specific value -- `CallbackToken` or `Argument::that(callback)` - checks that the argument matches a custom callback -- `AnyValueToken` or `Argument::any()` - matches any argument -- `AnyValuesToken` or `Argument::cetera()` - matches any arguments to the rest of the signature -- `StringContainsToken` or `Argument::containingString($value)` - checks that the argument contains a specific string value -- `InArrayToken` or `Argument::in($array)` - checks if value is in array -- `NotInArrayToken` or `Argument::notIn($array)` - checks if value is not in array - -And you can add even more by implementing `TokenInterface` with your own custom classes. - -So, let's refactor our initial `{set,get}Name()` logic with argument tokens: - -```php -use Prophecy\Argument; - -$user->getName()->willReturn(null); - -// For PHP 5.4 -$user->setName(Argument::type('string'))->will(function ($args) { - $this->getName()->willReturn($args[0]); -}); - -// For PHP 5.3 -$user->setName(Argument::type('string'))->will(function ($args, $user) { - $user->getName()->willReturn($args[0]); -}); - -// Or -$user->setName(Argument::type('string'))->will(function ($args) use ($user) { - $user->getName()->willReturn($args[0]); -}); -``` - -That's it. Now our `{set,get}Name()` prophecy will work with any string argument provided to it. -We've just described how our stub object should behave, even though the original object could have -no behavior whatsoever. - -One last bit about arguments now. You might ask, what happens in case of: - -```php -use Prophecy\Argument; - -$user->getName()->willReturn(null); - -// For PHP 5.4 -$user->setName(Argument::type('string'))->will(function ($args) { - $this->getName()->willReturn($args[0]); -}); - -// For PHP 5.3 -$user->setName(Argument::type('string'))->will(function ($args, $user) { - $user->getName()->willReturn($args[0]); -}); - -// Or -$user->setName(Argument::type('string'))->will(function ($args) use ($user) { - $user->getName()->willReturn($args[0]); -}); - -$user->setName(Argument::any())->will(function () { -}); -``` - -Nothing. Your stub will continue behaving the way it did before. That's because of how -arguments wildcarding works. Every argument token type has a different score level, which -wildcard then uses to calculate the final arguments match score and use the method prophecy -promise that has the highest score. In this case, `Argument::type()` in case of success -scores `5` and `Argument::any()` scores `3`. So the type token wins, as does the first -`setName()` method prophecy and its promise. The simple rule of thumb - more precise token -always wins. - -#### Getting stub objects - -Ok, now we know how to define our prophecy method promises, let's get our stub from -it: - -```php -$stub = $prophecy->reveal(); -``` - -As you might see, the only difference between how we get dummies and stubs is that with -stubs we describe every object conversation instead of just agreeing with `null` returns -(object being *dummy*). As a matter of fact, after you define your first promise -(method call), Prophecy will force you to define all the communications - it throws -the `UnexpectedCallException` for any call you didn't describe with object prophecy before -calling it on a stub. - -### Mocks - -Now we know how to define doubles without behavior (dummies) and doubles with behavior, but -no expectations (stubs). What's left is doubles for which we have some expectations. These -are called mocks and in Prophecy they look almost exactly the same as stubs, except that -they define *predictions* instead of *promises* on method prophecies: - -```php -$entityManager->flush()->shouldBeCalled(); -``` - -#### Predictions - -The `shouldBeCalled()` method here assigns `CallPrediction` to our method prophecy. -Predictions are a delayed behavior check for your prophecies. You see, during the entire lifetime -of your doubles, Prophecy records every single call you're making against it inside your -code. After that, Prophecy can use this collected information to check if it matches defined -predictions. You can assign predictions to method prophecies using the -`MethodProphecy::should(PredictionInterface $prediction)` method. As a matter of fact, -the `shouldBeCalled()` method we used earlier is just a shortcut to: - -```php -$entityManager->flush()->should(new Prophecy\Prediction\CallPrediction()); -``` - -It checks if your method of interest (that matches both the method name and the arguments wildcard) -was called 1 or more times. If the prediction failed then it throws an exception. When does this -check happen? Whenever you call `checkPredictions()` on the main Prophet object: - -```php -$prophet->checkPredictions(); -``` - -In PHPUnit, you would want to put this call into the `tearDown()` method. If no predictions -are defined, it would do nothing. So it won't harm to call it after every test. - -There are plenty more predictions you can play with: - -- `CallPrediction` or `shouldBeCalled()` - checks that the method has been called 1 or more times -- `NoCallsPrediction` or `shouldNotBeCalled()` - checks that the method has not been called -- `CallTimesPrediction` or `shouldBeCalledTimes($count)` - checks that the method has been called - `$count` times -- `CallbackPrediction` or `should($callback)` - checks the method against your own custom callback - -Of course, you can always create your own custom prediction any time by implementing -`PredictionInterface`. - -### Spies - -The last bit of awesomeness in Prophecy is out-of-the-box spies support. As I said in the previous -section, Prophecy records every call made during the double's entire lifetime. This means -you don't need to record predictions in order to check them. You can also do it -manually by using the `MethodProphecy::shouldHave(PredictionInterface $prediction)` method: - -```php -$em = $prophet->prophesize('Doctrine\ORM\EntityManager'); - -$controller->createUser($em->reveal()); - -$em->flush()->shouldHaveBeenCalled(); -``` - -Such manipulation with doubles is called spying. And with Prophecy it just works. - - -## FAQ - -### Can I call the original methods on a prophesized class? - -Prophecy does not support calling the original methods on a phrophesized class. If you find yourself needing to mock some methods of a class while calling the original version of other methods, it's likely a sign that your class violates the [single-responsibility principle](https://en.wikipedia.org/wiki/Single-responsibility_principle) and should be refactored. |