eloquent/phony-kahlan

Phony for Kahlan.

2.0.0 2018-06-08 01:24 UTC

README

Current version image Current build status image Current Windows build status image Current coverage status image

Installation and documentation

What is Phony for Kahlan?

Phony for Kahlan is a plugin for the Kahlan testing framework that provides general integration with the Phony mocking framework, as well as optional auto-wired test dependencies.

In other words, if a Kahlan test (or suite) requires a mock object, it can be defined to have a parameter with an appropriate type declaration, and it will automatically receive a mock of that type as an argument when run.

Stubs for callable types, and "empty" values for other type declarations are also supported.

Plugin installation

Installation is only required when using the dependency injection features of the plugin. The plugin can be installed in the Kahlan configuration file like so:

<?php // kahlan-config.php

// disable monkey-patching for Phony classes
$this->commandLine()->set('exclude', ['Eloquent\Phony']);

// install the plugin once autoloading is available
Kahlan\Filter\Filters::apply($this, 'run', function (callable $chain) {
    Eloquent\Phony\Kahlan\install();

    return $chain();
});

Dependency injection

Once the plugin is installed, any tests or suites that are defined with parameters will be supplied with matching arguments when run:

describe('Phony for Kahlan', function () {
    it('Auto-wires test dependencies', function (PDO $db) {
        expect($db)->toBeAnInstanceOf(PDO::class);
    });
});

Injected mock objects

Phony for Kahlan supports automatic injection of mock objects. Because Phony doesn't alter the interface of mocked objects, it is necessary to use on() to retrieve the mock handle in order to perform stubbing and verification:

use function Eloquent\Phony\Kahlan\on;

describe('Phony for Kahlan', function () {
    it('Supports stubbing', function (PDO $db) {
        on($db)->exec->with('DELETE FROM users')->returns(111);

        expect($db->exec('DELETE FROM users'))->toBe(111);
    });

    it('Supports verification', function (PDO $db) {
        $db->exec('DROP TABLE users');

        on($db)->exec->calledWith('DROP TABLE users');
    });
});

Injected stubs

Phony for Kahlan supports automatic injection of stubs for parameters with a callable type declaration:

describe('Phony for Kahlan', function () {
    it('Supports callable stubs', function (callable $stub) {
        $stub->with('a', 'b')->returns('c');
        $stub('a', 'b');

        $stub->calledWith('a', 'b')->firstCall()->returned('c');
    });
});

Supported types

The following table lists the supported type declarations, and the value supplied for each:

Parameter type Supplied value
(none) null
bool false
int 0
float .0
string ''
array []
iterable []
object (object) []
stdClass (object) []
callable stub()
Closure function () {}
Generator (function () {return; yield;})()

When using a type declaration that is not listed above, the supplied value will be a mock of the specified type.

By necessity, the supplied value will not be wrapped in a mock handle. In order to obtain a handle, simply use on():

use function Eloquent\Phony\Kahlan\on;

it('Example mock handle retrieval', function (ClassA $mock) {
    $handle = on($mock);
});

License

For the full copyright and license information, please view the LICENSE file.