Download the PHP package sirbrillig/spies without Composer

Spies

A library to make testing in PHP so much easier. You can install it in a PHP project by following the instructions below.

What is it? If you've ever used sinon in JavaScript testing, you know about the concept of Test Spies, and in many ways this library is just implementing those concepts in PHP. It also includes Expectations to simplify spy assertions, inspired by sinon-chai.

If you want to just skip to the details, you can read the API here.

If you are not familiar with Test Spies, here's a brief primer: Basically they are objects that behave like functions and keep a record of how they are called. You can inject them into objects when writing tests and monitor the spies to determine if the objects are behaving as you expect.

Spies can also be programmed to behave in certain ways (in which case they are more properly called "stubs" or "mocks"), forcing your code down certain paths in order to test specific behavior.

In PHP, we often need to spy on whole objects with instance methods, so Spies provides a mechanism to do that as well:

The final piece, Expectations add a layer of syntax to test assertions that should be easier to read as well as providing better failure messages:

Spies was designed as an optional replacement for the very excellent WP_Mock and Mockery, both of which are powerful but have many aspects and quirks that I don't find intuitive.

Suggestions, bug reports, and feature requests all welcome!

Installation

A library to make testing in PHP so much easier. You can install it in a PHP project by running:

composer require --dev sirbrillig/spies.

Then just make sure you include the autoloader somewhere in your code:

If using in PHPUnit, you can add autoload to your phpunit.xml file:

Otherwise you can include the autoloader manually:

However, please see the note on mocking and spying on existing functions. If you need to do this, you will need to add an explicit bootstrap file.

The Details

Global Functions

If you want to create a Spy for a global function (a function in the global namespace, like WordPress's wp_insert_post), you can pass the name of the global function to \Spies\get_spy_for():

You can Spy on functions defined within a namespace in the same way:

Stubs and Mocks

You can create stubs with the \Spies\stub_function() method. A stub is a fake function that can be called like a real function except that you control its behavior.

Stubs can also be used to mock a global function or a namespaced function, just like a Spy. In fact, a stub is also a Spy, which means you can query it for any information you like.

There are a few basic behaviors you can program into a stub:

1. You can simply use one to replace a global function (it will return null).
2. You can use one to return a specific value when called.
3. You can use one to return a specific value when called with specific arguments.
4. You can use one to return one of the arguments it was passed.
5. You can use one to call a substitute function.

Here's just setting a return value:

Here's returning a value with certain arguments:

Here's one returning one of its arguments:

Here's one returning the result of a substitute function:

Objects

Sometimes you need to create a whole object with stubs as functions. In that case you can use \Spies\mock_object() which will return an object that can be passed around. The object by default has no methods, but you can use add_method() to add some.

add_method(), or its alias, spy_on_method(), when called without a second argument, returns a stub (which, remember, is also a Spy), so you can program its behavior or query it for expectations. You can also use the second argument to pass a function (or Spy) explicitly, in which case whatever you pass is what will be returned.

It can be tedious to call add_method() for every public method of an existing class that you are trying to mock. For that reason you can use \Spies\mock_object_of( $class_name ) which will create a MockObject and automatically add a Spy for each public method on the original class. These Spies will all return null by default, but you can replace any of them with your own Spy by using add_method() as above.

If you'd rather not call add_method() and you don't have an original class to copy, you can also just ignore all method calls on the object using and_ignore_missing():

Object Method Delegation

Sometimes it's helpful to be able to be able to spy on actual methods of an object, or to replace some methods on an object, but not others. This involves creating a delegate object, which can be done by passing a class instance to \Spies\mock_object().

The resulting MockObject will forward all method calls to the original class instance, except those overridden by using add_method(). It's possible to use spy_on_method() to spy on any method call of the object, just as you would do with a regular MockObject.

Expectations

Spies can be useful all by themselves, but Spies also provides the Expectation class to make writing your test expectations easier.

Let's say we have a Spy and want to verify if it has been called in a PHPUnit test:

That works, but here's another way to write it:

They're both totally valid. Expectations just add some more syntactic sugar to your tests and speed the debugging process by improving failure messages. Particularly, they allow building up a set of expected behaviors and then validating all of them at once. Let's use a more complex example. Here it is with just a Spy:

And here with Expectations:

That last part, $expectation->verify() is what actually tests all the expected behaviors. You can also call the function \Spies\finish_spying() which will do the same thing, and can be put in a tearDown method.

Better failures

Perhaps the most useful thing about Expectations is that they provide better failure messages. Whereas $this->assertTrue( $spy->was_called_with( 'hello' ) ) and \Spies\expect_spy( $spy )->to_have_been_called->with( 'hello' ) both assert the same thing, the former will only tell you "false is not true", and the Expectation will fail with something like this message:

finish_spying

To complete an expectation during a test, and to keep functions in the global scope from interfering with one another, it's very important to call \Spies\finish_spying() after each test.

finish_spying() does three things:

1. Calls verify() on each Expectation. expect_spy() only prepares the expectation. It is not tested until verify() is called.
2. Clears all current Spies and mocked functions.
3. Clears all current Expectations.

Because Expectations are only evaluated when we call verify() or finish_spying(), you can use expectations before or after the code that is being tested. There's syntactic sugar to make it sound right either way. The following two are the same:

Argument lists

If you use with() to test an Expectation, sometimes you don't care about the value of an argument. In this case you can use \Spies\Expectation::any() in place of that argument:

If you need to match just part of a string, you can use \Spies\match_pattern().

You can also use \Spies\match_array() to match elements of an array while ignoring other parts:

PHPUnit Custom Assertions

If you prefer to use PHPUnit custom assertions rather than Expectations, those are also available (although you must base your test class on \Spies\TestCase):

Custom assertions will provide detailed information about why your test failed, which is much better than "false is not true".

See the API document for the full list of custom assertions available.

Assertion Helpers

For any assertion, even those not involving Spies or Stubs, it can be helpful to compare partial arrays in the same manner as match_array(). You can use the helper function do_arrays_match() to do this:

Spying and Mocking existing functions

PHP does not allow mocking existing functions. However, there is a library called Patchwork which allows this. If that library is loaded, it will be used by Spies. The library must be loaded before Spies. One way to do this is to use a test bootstrap file.

If using in PHPUnit, you can require the bootstrap from your phpunit.xml file:

Here is an example bootstrap file that also loads the autoloader:

If Patchwork is loaded, you will be able to use mock_function() and get_spy_for() on existing functions:

Contributing

Please submit an issue or PR!