PHP-Mock is a testing library which mocks non deterministic built-in PHP functions like
time() or rand(). This is achieved by PHP's namespace fallback policy:
PHP will fall back to global functions […] if a namespaced function […] does not exist.
PHP-Mock uses that feature by providing the namespaced function. I.e. you have to be in a non global namespace context and call the function unqualified:
namespace foo;
$time = time(); // This call can be mocked, a call to \time() can't.-
Only unqualified function calls in a namespace context can be mocked. E.g. a call for
time()in the namespacefoois mockable, a call for\time()is not. -
The mock has to be defined before the first call to the unqualified function in the tested class. This is documented in Bug #68541. In most cases, you can ignore this restriction but if you happen to run into this issue you can call
Mock::define()before that first call. This would define a side effectless namespaced function which can be enabled later. Another effective approach is running your test in an isolated process.
If you can't rely on or just don't want to use the namespace fallback policy, there are alternative techniques to mock built-in PHP functions:
-
PHPBuiltinMock relies on the APD extension.
-
MockFunction is a PHPUnit extension. It uses the runkit extension.
-
UOPZ is a Zend extension which allows, among others, renaming and deletion of functions.
-
vfsStream is a stream wrapper for a virtual file system. This will help you write tests which covers PHP stream functions (e.g.
fread()orreaddir()).
Use Composer:
composer require --dev php-mock/php-mockYou don't need to learn yet another API. PHP-Mock has integrations for these testing frameworks:
-
php-mock/php-mock-phpunit - PHPUnit integration
-
php-mock/php-mock-mockery - Mockery integration
-
php-mock/php-mock-prophecy - Prophecy (phpspec) integration
Note: If you plan to use one of the above mentioned testing frameworks you can skip reading any further and just go to the particular integration project.
You find the API in the namespace
phpmock.
Create a Mock
object. You can do this with the fluent API of MockBuilder:
-
MockBuilder::setNamespace()sets the target namespace of the mocked function. -
MockBuilder::setName()sets the name of the mocked function (e.g.time()). -
MockBuilder::setFunction()sets the concrete mock implementation. -
MockBuilder::setFunctionProvider()sets, alternativly toMockBuilder::setFunction(), the mock implementation as aFunctionProvider:-
FixedValueFunctionis a simple implementation which returns always the same value. -
FixedMicrotimeFunctionis a simple implementation which returns always the same microtime. This class is different toFixedValueFunctionas it contains a converter formicrotime()'s float and string format. -
FixedDateFunctionis a simple implementation which returns always a formated date for the fixed timestamp. -
SleepFunctionis asleep()implementation, which doesn't halt but increases anIncrementablee.g. atime()mock. -
UsleepFunctionis anusleep()implementation, which doesn't halt but increases anIncrementablee.g. amicrotime()mock.
-
-
MockBuilder::build()builds aMockobject.
After you have build your Mock object you have to call enable()
to enable the mock in the given namespace. When you are finished with that mock you
should disable it by calling disable()
on the mock instance.
This example illustrates mocking of the unqualified function time() in the
namespace foo:
namespace foo;
use phpmock\MockBuilder;
$builder = new MockBuilder();
$builder->setNamespace(__NAMESPACE__)
->setName("time")
->setFunction(
function () {
return 1417011228;
}
);
$mock = $builder->build();
// The mock is not enabled yet.
assert (time() != 1417011228);
$mock->enable();
assert (time() == 1417011228);
// The mock is disabled and PHP's built-in time() is called.
$mock->disable();
assert (time() != 1417011228);Instead of setting the mock function with MockBuilder::setFunction() you could also
use the existing FixedValueFunction:
namespace foo;
use phpmock\MockBuilder;
use phpmock\functions\FixedValueFunction;
$builder = new MockBuilder();
$builder->setNamespace(__NAMESPACE__)
->setName("time")
->setFunctionProvider(new FixedValueFunction(1417011228));
$mock = $builder->build();It's important to note that setNamespace() should target the namespace where the function is called, not the namespace where it's being mocked. For example:
<?php
namespace App\Code;
class Subject
{
public function foo()
{
time();
}
}
In a test mocking this call:
<?php
namespace Tests\Unit;
class SubjectTest
{
public function myTest()
{
$builder = new MockBuilder();
$builder->setNamespace('\\App\\Code'); // ... etc
}
}
An enabled mock changes global state. This will break subsequent tests if
they run code which would call the mock unintentionally. Therefore
you should always disable a mock after the test case. You will have to disable
the created mock. You could do this for all mocks by calling the
static method
Mock::disableAll().
Complex mock environments of several mocked functions can be grouped in a MockEnvironment:
-
MockEnvironment::enable()enables all mocked functions of this environment. -
MockEnvironment::disable()disables all mocked functions of this environment. -
MockEnvironment::define()defines all mocked functions of this environment.
The SleepEnvironmentBuilder
builds a mock environment where sleep() and usleep() return immediatly.
Furthermore they increase the amount of time in the mocked date(), time() and
microtime():
namespace foo;
use phpmock\environment\SleepEnvironmentBuilder;
$builder = new SleepEnvironmentBuilder();
$builder->addNamespace(__NAMESPACE__)
->setTimestamp(1417011228);
$environment = $builder->build();
$environment->enable();
// This won't delay the test for 10 seconds, but increase time().
sleep(10);
assert(1417011228 + 10 == time());If the mocked functions should be in different namespaces you can
add more namespaces with SleepEnvironmentBuilder::addNamespace()
A Spy
gives you access to the function invocations.
Spy::getInvocations()
gives you access to the arguments and return value.
As a Spy is a specialization of Mock it behaves identically. However you
could ommit the third constructor parameter callable $function which
would then create a spy using the existing function.
E.g. a new Spy(__NAMESPACE__ , "rand") would create a spy which basically
proxies PHP's built-in rand():
namespace foo;
use phpmock\spy\Spy;
function bar($min, $max) {
return rand($min, $max) + 3;
}
$spy = new Spy(__NAMESPACE__, "rand");
$spy->enable();
$result = bar(1, 2);
assert ([1, 2] == $spy->getInvocations()[0]->getArguments());
assert ($result == $spy->getInvocations()[0]->getReturn() + 3);This project is free and under the WTFPL. Responsable for this project is Markus Malkusch [email protected]. This library was inspired by Fabian Schmengler's article PHP: “Mocking” built-in functions like time() in Unit Tests.
If you like PHP-Mock and feel generous donate a few Bitcoins here: 1335STSwu9hST4vcMRppEPgENMHD2r1REK
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent