Download the PHP package net-tools/phpunit-given without Composer

olvlvl/phpunit-given

olvlvl/phpunit-given provides an alternative to PHPUnit's ReturnValueMap and ReturnCallback, as well as a convenient solution to migrate from Prophecy.

Disclaimer

In most cases ReturnCallback with match can be used effectively. Don't use this package if you're comfortable with these and don't need extra features.

Usage

This is a simple example, more use cases below.

Installation

Motivation

Coming from Prophecy, [C# Moq](), Golang Mock, or Kotlin Mockk, one would expect at least one of the following examples to work, but they do not.

To return a value given certain arguments, one is expected to use ReturnValueMap or ReturnCallback. ReturnValueMap seems simple enough, but because it looks for exact matches it fails when objects are included in the arguments, unless they are the same instances. Besides, ReturnValueMap does not support constraints, you can forget doing anything fancy with it. That leaves us with ReturnCallback, which can be used effectively with match but requires the introduction of logic in the test, a practice that is discouraged.

My motivation creating olvlvl/phpunit-given, is to have an alternative to ReturnValueMap and ReturnCallback, that looks similar to what we find in other testing frameworks, and that allows easy migration from Prophecy.

Some PHPUnit issues, for reference:

• Feature similar to withConsecutive(), but without checking order
• Improvements on withConsecutive with return
• Remove withConsecutive()

Use cases

Comparing objects

ReturnValueMap doesn't work with objects because it uses strict equality when comparing arguments. The following code throws a TypeError exception because ReturnValueMap cannot find a match and defaults to a null value.

olvlvl/phpunit-given substitutes values with Assert::equalTo() and compares arguments using constraints. Having objects in the arguments is not a problem.

Note: You can use Assert::identicalTo() to check for the same instance.

Using constraints

We established that values are substituted with Assert::equalTo() internally. Instead of values, you can also use constraints:

Of course, you could use ReturnCallback, although it adds logic to the test. Use whatever you feel more comfortable with.

Migrating from Prophecy

olvlvl/phpunit-given is a convenient solution to migrate from Prophecy because the code is quite similar:

throw() is an alternative to willThrow(), and you can mismatch return() and throw():

Contrary to Prophecy, olvlvl/phpunit-given does not return null by default, instead it throws an exception:

Continuous Integration

The project is continuously tested by GitHub actions.

Code of Conduct

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.

Contributing

Please see CONTRIBUTING for details.

License

olvlvl/phpunit-given is released under the BSD-3-Clause.