Adds HigherOrderExpectations

[nedwors]

Hi!

Thanks for the amazing package 🚀

This is a PR to allow properties to be dynamically accessed from the expectation value. For example, given a User, the following is possible:

expect($user)
    ->name->toEqual('Dr Pest')
    ->email->not->toBeNull->toEqual('dr@pest.com')
    ->posts->toHaveCount(2)->each(fn ($post) => $post->published->toBeTrue)
    ->posts->sequence(
        fn ($post) => $post->title->toEqual('Simply the Pest'),
        fn ($post) => $post->title->toEqual('Pest Friends')
    )

This will work with an array or an object.

I appreciate this PR is quite heavy on additions - eg. changing how the __get method functions in Expectation - and I may have missed something along the way. So, it might not even be desired. But I thought it was a cool feature to submit and see what everyone thinks. Happy to hear all thoughts and suggestions.

expect($me)->is_waiting_patiently->toBeTrue

Thanks!

Update:

Support for methods has been added. So now the following would be possible:

expect($user)->getName()->toEqual('Nuno')

And even:

expect($calculator)->add(1, 4)->toEqual(5)

[lukeraymonddowning]

Could the $asMethod and $arguments be passed in a separate method?

return (new HigherOrderExpectation($this, $method))->asMethod(...$parameters);

[nedwors]

I thought exactly this but went with parameters to allow the expectation set-up to happen in the constructor?

I'm not sure of a clean way to defer the setup of the expectation in the class without having everywhere that calls $this->expectation to instead call $this->expectation() and have that method as:

private function expectation()
{
   return $this->expectation ??= // Set up the expectation here
}

[nedwors]

@lukeraymonddowning - I've added static constructors as one way at solving this:

return HigherOrderExpectation::forProperty($this, $name)

return HigherOrderExpectation::forMethod($this, $name, ...$parameters)

I'm not sure if static constructors are in fitting with this project's code style but I thought it was at least worth presenting it.

[lukeraymonddowning]

Could we instead assume asMethod if the constructor received more than 2 arguments? Perhaps remove the varadic and have it as an array.

Just thinking that when you look at the static constructors they're actually remarkably similar and properties will never have arguments.

[nedwors]

@lukeraymonddowning chef's kiss. Great call, thank you 🔥

[nedwors]

Wow, amazing! @nunomaduro, should I start on something for the docs, or do you have more things brewing? 😀

[lukeraymonddowning]

@nedwors please crack on and start work on the docs 👌

[nedwors]

I'll get on it tonight 👍

[nunomaduro]

@nedwors Thank you!

[nedwors]

@nunomaduro, @lukeraymonddowning PR opened - pestphp/docs#57. Any and all suggestions welcome!