mindplay/testies

Yeah, testies: a lightweight library for quick, simple unit-testing

0.3.1 2017-06-02 13:06 UTC

README

Yeah, testies: a lightweight library of functions for quick, simple unit-testing.

Tries to honor the Go language philosophy of testing - paraphrasing:

testing frameworks tend to develop into mini-languages of their own, with conditionals and controls and printing mechanisms, but PHP already has all those capabilities; why recreate them? We'd rather write tests in PHP; it's one fewer language to learn and the approach keeps the tests straightforward and easy to understand.

The primary test API is procedural-style global functions - you're cool with that, because you don't have anything else is the global namespace, right?

Internally, the procedural API is backed by a pair of simple driver and configuration classes - these are left as open as possible, and you should feel comfortable extending these and tailoring them specifically to suit the test-requirements for whatever you're testing.

Usage

Install via Composer:

composer require-dev mindplay/testies

Then create a test script - the format is pretty simple:

<?php

require dirname(__DIR__) . '/vendor/autoload.php';

test(
    'Describe your test here',
    function () {
        ok(true, 'it works!');
    }
);

exit(run()); // exits with errorlevel (for CI tools etc.)

You will call test() as many times as you need to - the tests will queue up, and execute when you call run().

Procedural API

Basic API overview:

# Assertions:

ok($result, $why, $value);                 # check the result on an expression
eq($value, $expected, $why);               # check value for strict equality with an expected value
expect($exception_type, $why, $function);  # check for an expected exception that should be thrown 

# Helper functions:

invoke($object, $method_name, $arguments); # invokes a protected or private method; returns the result
inspect($object, $property_name);          # returns a protected or private property value
format($value, $detailed = false);         # format a value for use in diagnostic messages

Rather than providing hundreds of assertion functions, you perform assertions using PHP expressions, often in concert with helper, and built-in standard functions in PHP - some examples:

test(
    'Various things of great importance',
    function () {
        ok($foo instanceof Foo);              # type-checking an object
        ok(is_int(inspect($foo, '_count')));  # type-checking a private property
        ok(123 == '123');                     # loose comparison
        ok(in_array('b', ['a','b','c']));     # check for presence of a value
        ok(isset($map['key']));               # check for presence of a key
        ok(is_string(@$map['key']));          # type-check a key/value with error-suppression
    }
);

We find that idiomatic PHP code is something you already know - rather than inventing our own domain-specific language for testing, we believe in writing tests that more closely resemble ordinary everyday code.

Custom Assertion Functions

Your custom assertion functions, like the built-in assertion functions, are just functions - usually these will call back to the ok() function to report the result. For example:

/**
 * Assert that a numeric value is very close to a given expected value 
 * 
 * @param float|int $value    actual value
 * @param float|int $expected expected near value
 * @param int       $decimals number of decimals of error tolerance
 */
function nearly($value, $expected, $decimals = 8) {
    ok(abs($value - $expected) * pow(10, $decimals) <= 1, "{$value} should be nearly {$expected}", $value);
}

test(
    'Values should be approximately right',
    function () {
        nearly(9.999999999, 10);
        nearly(10.000000001, 10);
        nearly(10.00002, 10);
    }
);

You can use the same approach to group multiple assertions:

function checkValue($value) {
    ok(is_int($value), "value should be numeric", $value);
    ok($value > 0, "value should be positive", $value);
}

test(
    'Checking out some numbers',
    function () {
        checkValue(123);
        checkValue(-1);
    }
);

Keep in mind that diagnostic output always refers to the line number in the test-closure that generated the assertion result.

Test Server

This feature is very rough at the moment.

As of release 5.4, PHP provides a built-in development web server.

For test scenarios where the code needs to run out-of-process (such as mockery, phake or phpunit) or if you need to check the response from a script (e.g. using guzzle), we provide a simple wrapper class to launch and shut down a server:

use GuzzleHttp\Client;

$server = new TestServer(__DIR__, 8088);

test(
    'Can get home page',
    function () {
        $client = new Client();

        $response = $client->get('http://127.0.0.1:8088/index.php');

        eq($response->getStatusCode(), 200);
        ok(strpos($response->getBody(), '<title>Welcome</title>') !== false);
    }
);

Note that the server is automatically shut down when the $server object falls out of scope - if you need to explicitly shut down a server, just destroy the server object with e.g. unset($server).

Keep in mind that starting and stopping many server instances can slow down your test drastically - it's often a good idea to open one server instance and share it between test-functions. Creating and disposing of clients, on the other hand, is recommended, as sharing client state could lead to unreliable tests.

Options

A few simple configuration options are provided via the configure() function, which provides access to the current instance of TestConfiguration.

Code Coverage

To enable code coverage and display the summary result on the console:

configure()->enableCodeCoverage();

To output a clover.xml file for integration with external analysis tools, specify an output path:

configure()->enableCodeCoverage(__DIR__ . '/build/clover.xml');

To enable code coverage analysis only for files in certain folders, pass a path (or array of paths) like so:

configure()->enableCodeCoverage(__DIR__ . '/build/clover.xml', dirname(__DIR__) . '/src');

Verbosity

By default, test output does not produce messages about successful assertions, only failures - if you want more stuff to look at, enable verbose output:

configure()->enableVerboseOutput();

Strict Error Handling

By default, all PHP errors/warnings/notices are automatically mapped to exceptions via a simple built-in error handler. If you're testing something that has custom error handling, you can disable it with:

configure()->disableErrorHandler();

Extensibility

The procedural API is actually a thin layer over two classes providing the actual library implementation.

One common reason to use a custom driver, is to override the TestDriver::format() method, to customize how special objects are formatted for output on the console.

To use a custom, derived TestConfiguration class:

// Derive your custom configuration class:

class MyTestConfiguration extends TestConfiguration
{
    // ...
}

// Head off your test by selecting your custom configuration object:

configure(new MyTestConfiguration);

Then proceed with business as usual.

To use a custom, derived TestDriver class:

// Derive your custom driver class:

class MyTestDriver extends TestDriver
{
    // ...
}

// Head off your test by selecting your custom driver object:

configure(new TestConfiguration(new TestDriver));

Alternatively, create a configuration class that provides a custom default driver class:

class MyTestDriver extends TestDriver
{
    // ...
}

class MyTestConfiguration extends TestConfiguration
{
    protected function createDefaultDriver()
    {
        return new MyTestDriver();        
    }
    
    // ...
}

configure(new MyTestConfiguration);

Refer to the actual implementations to see what else is possible - pretty much everything is public or protected in these classes, left open for you to call or override as needed.