SIMPLE TESTING FRAMEWORK FOR PHP

A TAP-compliant minimal test library for PHP.

Inspired by Test::Simple for perl, but does not guarantee identical behaviour.

BACKGROUND

I made this because PHPUnit often feels like overkill for smaller projects, and like a poor fit for non-OO projects.

I considered Peridot/Leo, but could not get it to work on PHP8 (it also has not been updated in a while).

SYNOPSIS

Writing a test:

example/broken.t:

use functions TestSimple\{ok, is, done_testing};    # import test functions

ok(get_data());                                     # description is optional

is(2, 1+1, "basic math works");                     # is(expected, actual, description)

ok(function()                                       # trap errors with functions
{
    $c = new Thing();
    return $c->run();
}, "thing can run");

done_testing();

Running a test:

$ php example/broken.t
ok 1
ok 2 - basic math works
not ok 3 - thing can run
#	Failed test 'thing can run'
#	at src/TestSimple/Assert.php:182
#	ArgumentCountError in example/broken.phpt:12
1..3
Looks like you failed 1 out of 3 tests

We have a failure; new Thing() requires a parameter.

Since this is intended behaviour, we should have a test for it:

example/fixed.t:

use functions TestSimple\{ok, is, done_testing};

ok(true);

is(2, 1+1, "basic math works");

is(new ArgumentCountError(), function()
{
    $c = new Thing();
    return $c->run();
}, "thing cannot run without speed");

ok(function()
{
    $c = new Thing(5);
    return $c->run();
}, "thing can run");

done_testing();

and we run it:

$ php example/fixed.t
ok 1
ok 2 - basic math works
ok 3 - thing cannot run without speed
ok 4 - thing can run
1..4

all good :)

EXIT CODES

If all tests pass, testsimple will exit with zero - indicating no error. If anything failed, it will exit with how many failed. If the tests were run incorrectly, it will exit with 255.

0           all tests passed
1..254      how many tests failed
255         something went wrong

If more than 254 tests fail, it will be reported as 254.

TESTING EXCEPTIONS

If you pass a throwable as the expected value to is, it will compare type, and message (if defined). It will accept any ancestor class or implemented interface as a successful match

is(new Exception('Invalid input'), function()
{
    $r = new Request('garbage');
    $r->run();
}, "Request throws exception on invalid input");

CAVEATS

The test suite for testsimple-php is written in testsimple-php, make of that what you will.

When specifying the number of tests, the actual number of tests reported will be one higher since this literally adds a test at the end to validate the number of tests. However, you do not have to take this into consideration when setting the number of tests.

OO INTERFACE

$assert = new TestSimple\Assert(plan: 2);
$assert->ok(1,          "1 is truthy");
$assert->is(5, 2+3,     "math works");
$assert->done();                        # ->done_testing() also works