innmind/black-box

Test library

6.4.1 2025-05-25 11:42 UTC

Requires

• php: ~8.2
• innmind/json: ^1.1
• phpunit/php-code-coverage: ~10.1|~11.0|~12.0
• phpunit/php-timer: ~6.0|~7.0|~8.0
• phpunit/phpunit: ~10.0|~11.0|~12.0
• symfony/var-dumper: ~6.0|~7.0

Requires (Dev)

• innmind/coding-standard: ~2.0
• innmind/static-analysis: ^1.2.1
• ramsey/uuid: ^4.1

MIT

• Baptiste Langlade

• fixtures
• test
• property based testing

README

BlackBox is a Property Based Testing framework and test runner.

Property Based Testing is a way to verify a piece of code always behave the same way (aka a Property) by testing it with multiple values of a given type.

The common introduction to this approach is the add function that has 3 properties:

• it is commutative
• it is associative
• it is an identity function

To prove this via BlackBox you can do it this way:

use Innmind\BlackBox\{
    Application,
    Set,
    Runner\Assert,
};

Application::new([])
    ->tryToProve(static function() {
        yield proof(
            'add is commutative',
            given(
                Set::integers(),
                Set::integers(),
            ),
            static fn(Assert $assert, int $a, int $b) => $assert->same(
                add($a, $b),
                add($b, $a),
            ),
        );
        yield proof(
            'add is associative',
            given(
                Set::integers(),
                Set::integers(),
                Set::integers(),
            ),
            static fn(Assert $assert, int $a, int $b, int $c) => $assert->same(
                add(add($a, $b), $c),
                add($a, add($b, $c)),
            ),
        );
        yield proof(
            'add is an identity function',
            given(Set::integers()),
            static fn(Assert $assert, int $a) => $assert->same(
                $a,
                add($a, 0),
            ),
        );
    })
    ->exit();

By default BlackBox will generate 100 scenarii for each proof.

Note BlackBox use the term proof to emphasize that you are testing behaviours not specific scenarii, but these are NOT formal proofs

Installation

composer require --dev innmind/black-box

Documentation

Full documentation can be found in the here.