Download the PHP package lucatume/function-mocker without Composer

Function Mocker

A Patchwork powered function mocker.

Show me the code

This can be written in a PHPUnit test suite

Installation

Either zip and move it to the appropriate folder or use Composer

composer require lucatume/function-mocker:~1.0

Usage

In a perfect world you should never need to mock static methods and functions, should use TDD to write better object-oriented code and use it as a design tool.
But sometimes a grim and sad need to mock those functions and static methods might arise and this library is here to help.

Bootstrapping

To make Fucntion Mocker behave in its wrapping power (a power granted by patchwork) the FunctionMocker::init method needs to be called in the proper bootstrap file of Codeception or PHPUnit like this

The init method will accept a configuration array supporting the following arguments:

• include or whitelist - array|string; a list of absolute paths that should be included in the patching.
• exclude or blacklist - array|string; a list of absolute paths that should be excluded in the patching.
• cache-path - string; the absolute path to the folder where Pathchwork should cache the wrapped files.
• redefinable-internals - array; a list of internal PHP functions that are available for replacement; if an internal function (a function defined by PHP) is not listed here then it will never be replaced in the tests.

Excluding the project root folder, dirname(__DIR__) in the examples, is usually a good idea.

Note: the library will ignore patchwork.json files even if no configuration is provided to the FunctionMocker::init method.

Initialization parameters

Function mocker will take care of initializing Patchwork with some sensible defaults but those initialization parameters can be customized:

• whitelist - array or string, def. empty; a list of absolute paths that should be included in the patching.
• blacklist - array or string, def. empty; a list of absolute paths that should be excluded from the patching; the Patchwork library itself and the Function Mocker library are always excluded.
• cache-path - string, def. cache folder; the absolute path to the folder where Pathcwork should cache the wrapped files.
• redefinable-internals array, def. empty; a list of internal PHP functions that are available for replacement; any internal function (defined by the PHP Standard Library) that needs to be replaced in the tests should be listed here.

setUp and tearDown methods

The library is meant to be used in the context of a PHPUnit test case and provides two static methods that must be inserted in the test case setUp and tearDown method for the function mocker to work properly:

Functions

Replacing functions

The library will allow for replacement of defined and undefined functions at test run time using the FunctionMocker::replace method like:

and will allow setting a return value as a real value or as a function callback:

If you need to replace a function and make it return a sequence of values, one at each call, then you can use the FunctionMocker::replaceInOrder method:

Spying on functions

If the value returned by the FunctionMocker::replace method is stored in a variable than checks for calls can be made on that function:

The methods available for a function spy are the ones listed below in the "Methods" section.

Batch replacement of functions

When in need to stub out a batch of functions needed for a component to work this can be done:

When replacing a batch of functions the return value will be an array of spy objects that can be referenced using the function name:

Static methods

Replacing static methods

Similarly to functions the library will allow for replacement of defined static methods using the FunctionMocker::replace method

again similarly to functions a callback function return value can be set:

Note that only public static methods can be replaced.

Spying of static methods

Storing the return value of the FunctionMocker::replace function allows spying on static methods using the methods listed in the "Methods" section below like:

Batch replacement of static methods

Static methods too can be replaced in a batch assigning to any replaced method the same return value or callback:

When batch replacing static methods FunctionMocker::replace will return an array of spy objects indexed by the method name that can be used as any other static method spy object;

Instance methods

Replacing instance methods

When trying to replace an instance method the FunctionMocker::replace method will return an extended PHPUnit mock object implementing all the original methods and some (see below)

The FunctionMocker::replace method will set up the PHPUnit mock object using the any method, the call above is equivalent to

An alternative to this instance method replacement exists if the need arises to replace more than one instance method in a test:

Not specifying any method to replace will return a mock object wher just the __construct method has been replaced.

Mocking chaining methods

Since version 0.2.13 it's possible mocking instance methods meant to be chained. Given the following dependency class

and a possible client class

mocking the self-returning where method is possible in a test case using the -> as return value

Mocking abstract classes, interfaces and traits

Relying on PHPUnit instance mocking engine FunctionMocker retains its ability to mock interfaces, abstract classes and traits; the syntax to do so is the same used to mock instance methods

the interface above can be replaced in a test like this

See PHPUnit docs for a more detailed approach.

Spying instance methods

The object returned by the FunctionMocker::replace method called on an instance method will allow for the methods specified in the "Methods" section to be used to check for calls made to the replaced method:

An alternative and more fluid API allows rewriting the assertions above in a way that's more similar to the one used by prophecy:

Batch replacing instance methods

It's possible to batch replace instances using the same syntax used for batch function and static method replacement.
Given the SomeClass above:

Methods

Beside the methods defined as part of a PHPUnit mock object interface (see here), available only when replacing instance methods, the function mocker will extend the replaced functions and methods with the following methods:

• wasCalledTimes(int $times [, string $methodName]) - will assert a PHPUnit assertion if the function or static method was called $times times; the $times parameter can come using the times syntax below.
• wasCalledOnce([string $methodName]) - will assert a PHPUnit assertion if the function or static method was called once.
• wasNotCalled([string $methodName]) - will assert a PHPUnit assertion if the function or static method was not called.
• wasCalledWithTimes(array $args, int $times[, string $methodName]) - will assert a PHPUnit assertion if the function or static method was called with $args arguments $times times; the $times parameter can come using the times syntax below; the $args parameter can be any combination of primitive values and PHPUnit constraints like [23, Test::isInstanceOf('SomeClass')].
• wasCalledWithOnce(array $args[, string $methodName]) - will assert a PHPUnit assertion if the function or static method was called with $args arguments once; the $args parameter can be any combination of primitive values and PHPUnit constraints like [23, Test::isInstanceOf('SomeClass')].
• wasNotCalledWith(array $args[, string $methodName]) - will assert a PHPUnit assertion if the function or static method was not called with $args arguments; the $args parameter can be any combination of primitive values and PHPUnit constraints like [23, Test::isInstanceOf('SomeClass')].

The method name is needed to verify calls on replaced instance methods!

Times

When specifying the number of times a function or method should have been called a flexible syntax is available; in its most basic form can be expressed in numbers

but the usage of strings makes the check less cumbersome using the comparator syntax used in PHP

available comparators are >n, <n, >=n, <=n, ==n (same as inserting a number), !n.

Sugar methods

Function Mocker packs some sugar methods to make my testing life easier. The result of any of these methods can be achieved using alternative code but I've implemented those to speed things up a bit.

Test methods

Function Mocker wraps a PHPUnit_Framework_TestCase to allow the calling of test methods normally called on $this to be statically called on the FunctionMocker class or any of its aliases. A test method can be writte like this

Being a mere wrapping the test case to be used can be set using the setTestCase static method in the test case setUp method

and any method specific to the test case will be available as a static method of the tad\FunctionMocker\FunctionMocker class.
Beside methods defined by the wrapped test case any method defined by the PHPUnit_Framework_TestCase class is available for autocompletion to comment reading IDEs like PhpStorm or Sublime Text.

Replacing a global

Allows replacing a global with a mock object and restore it after the test. Best used to replace/set globally shared instances of objects to mock; e.g.:

is the same as writing

Setting a global

Allows replacing/setting a global value and restore it's state after the test.

same as writing