BlackBox

This is Innmind's own testing framework.

It follows Innmind's philosophy meaning it can be integrated in other tools. It is self contained and do not rely on global state.

Installation

composer require --dev innmind/black-box:~5.6

Setup

blackbox.php

<?php
declare(strict_types = 1);

require 'vendor/autoload.php';

use Innmind\BlackBox\Application;

Application::new($argv) #(1)
    ->tryToProve(function() {
        yield test(
            'More on tests in the next chapter',
            static fn($assert) => $assert->true(true),
        );
    })
    ->exit();

1. More on the usage of $argv below.

This is the simplest setup of BlackBox. A PHP file (1) that bootstraps an Application to which is passed a function that will return a generator of tests and then exits.

1. In this case the file is named blackbox.php but you can call it the way you want.

And you simply run your tests via php blackbox.php.

Organization

In the example above the tests are provided inside an inline generator. This is fine when you only have a few of them. When it's no longer convenient you should split your tests in multiple files.

File 1File 2

proofs/file1.php

<?php

return static function() {
    yield test(
        'Test 1',
        static fn($assert) => $assert->true(true),
    );
}

proofs/file2.php

<?php

return static function() {
    yield test(
        'Test 2',
        static fn($assert) => $assert->true(true),
    );
}

If you want to load these 2 files you can do:

blackbox.php

<?php
declare(strict_types = 1);

require 'vendor/autoload.php';

use Innmind\BlackBox\Application;

Application::new($argv)
    ->tryToProve(function() {
        yield from (require 'proofs/file1.php');
        yield from (require 'proofs/file2.php');
    })
    ->exit();

This is good because you can control the way your files are loaded. But adding new files becomes tedious, especially when multiple persons work on the project.

Instead you can simplify it with:

blackbox.php

<?php
declare(strict_types = 1);

require 'vendor/autoload.php';

use Innmind\BlackBox\{
    Application,
    Runner\Load,
};

Application::new($argv)
    ->tryToProve(Load::everythingIn('proofs/'))
    ->exit();

In the end you have full control over the order your tests are loaded.

Tags

After a while you may end up with a lot of tests and running them all all the time can be time consuming. You can categorize your tests via tags.

You declare them this way:

use Innmind\BlackBox\Tag;

yield test( #(1)
    'Test name',
    static fn($assert) => $assert->true(true),
)->tag(Tag::positive, Tag::wip);

1. Refer to example above to know where to place a test.

Then to only run a test with a given tag: php blackbox.php wip.

The list of arguments you pass in the CLI command is passed to BlackBox via the code Application::new($argv). Each argument must correspond to the name of a case on the Innmind\BlackBox\Tag enum.