Verification for PHP 7 generator responses

[ezzatron]

Relates to #94.

[ezzatron]

At the moment, I'm thinking that returned() will probably need to work for generator returns too. In order to allow the user to still assert that a call originally returned a generator, we will probably need to introduce something like generated():

$spy = spy(
    function () {
        yield 'a';
        return 'b';
    }
);

iterator_to_array($spy());

$spy->generated();
$spy->produced('a');
$spy->returned('b');

[jmalloc]

I think I was the one that was keen to use returned in this way, though looking at it now I wonder if it's wise to reuse returned(). If you had a verification that was simply:

$spy->returned('b');

The implementation of the spy could be either a regular function or a generator and the test would still pass, but usage of the two would be very different in reality.

That said, I don't think I've ever used return verification, since I rarely use spies outside of verification of callback functions, and the rest of the time the spy is also the stub that provides the behaviour.

[ezzatron]

Okay, so what would we call the verification method of a generator return value? The best I can think of is generatorReturned($value).

[ezzatron]

Also, if you were faced with the edge case that a single method could return something via a generator OR normally, we could still allow for:

$spy->never()->generated();
$spy->returned('b');