Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,4 +73,4 @@ composer require --dev innmind/black-box

## Documentation

Full documentation can be found in the [here](https://innmind.github.io/BlackBox/).
Full documentation can be found in the [here](https://innmind.org/BlackBox/).
5 changes: 3 additions & 2 deletions documentation/assert/memory.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,12 @@ In order for these assertions to work properly you need to:
use Innmind\BlackBox\{
Application,
Runner\Assert,
Prove,
};

Application::new([])
->tryToProve(static function(): \Generator {
yield test(
->tryToProve(static function(Prove $prove): \Generator {
yield $prove->test(
'Some memory test',
static function(Assert $assert) {
$assert
Expand Down
60 changes: 13 additions & 47 deletions documentation/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,56 +82,20 @@ Application::new([])
->exit();
```

## Changing the way the framework outputs the results

By default the framework outputs any data as soon as possible to keep the usage of memory low but this means rewinding the output to find a failure. If you want to change the output you need to implement the interface `Innmind\BlackBox\Runner\Printer` and declare it liek this:

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

Application::new([])
->usePrinter(new YourPrinter())
->tryToProve(Load::everythingIn('proofs/'))
->exit();
```

## Disable global functions

By default the framework exposes the `proof`, `test`, `property`, `properties` and `given` global functions but if you don't want them to avoid collisions with your own methods you can use the namespaced functions (available in the `Innmind\BlackBox\Runner` namespace).

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

Application::new([])
->disableGlobalFunctions()
->tryToProve(Load::everythingIn('proofs/'))
->exit();
```

??? warning
This method is deprecated and will be removed in the next major version.

## Disable GitHub Action output

When it detects it's run inside a GitHub Action the framework groups each proof output to make the output more compact for large suites. It also adds annotations to quickly jump to each failing proof.

You can disable such behaviour like this:

```php hl_lines="4 8"
```php hl_lines="7"
use Innmind\BlackBox\{
Application,
Runner\Load,
Runner\Printer\Standard,
};

Application::new([])
->usePrinter(Standard::new()->disableGitHubOutput())
->mapPrinter(static fn($printer) => $printer->disableGitHubOutput())
->tryToProve(Load::everythingIn('proofs/'))
->exit();
```
Expand All @@ -142,24 +106,26 @@ By default BlackBox will fail a proof when a scenario did not make any assertion

However if your style of making assertions may not always lead to a proof making one, then you can disable this feature this way:

```php hl_lines="4"
use Innmind\BlackBox\Application;
```php hl_lines="7"
use Innmind\BlackBox\{
Application,
Prove,
};

Application::new([])
->allowProofsToNotMakeAnyAssertions()
->tryToProve(static function() {
yield proof(
'Some proof',
given(Set::of('some input')),
static function($assert, $input) {
->tryToProve(static function(Prove $prove) {
yield $prove
->proof('Some proof')
->given(Set::of('some input'))
->test(static function($assert, $input) {
try {
doSomething($input);
$assert->fail('It should throw');
} catch (\Exception $e) {
// expected behaviour
}
},
);
});
})
->exit();
```
12 changes: 6 additions & 6 deletions documentation/getting-started/property.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ You can run this property like this:
->tryToProve(static function(Prove $prove): \Generator {
yield $prove->property(
AddIsCommutative::class,
Set::of(new Add),
Set::of(static fn() => new Add),
);
})
->exit();
Expand Down Expand Up @@ -130,27 +130,27 @@ Application::new([])
->tryToProve(static function(Prove $prove): \Generator {
yield $prove->properties(
'Add properties',
Set\Properties::any(
Set::properties(
AddIsCommutative::any(),
AddIsCumulative::any(),
ZeroIsAnIdentityValue::any(),
),
Set::of(new Add),
Set::of(static fn() => new Add),
);

yield $prove->property(
AddIsCommutative::class,
Set::of(new Add),
Set::of(static fn() => new Add),
);

yield $prove->property(
AddIsCumulative::class,
Set::of(new Add),
Set::of(static fn() => new Add),
);

yield $prove->property(
ZeroIsAnIdentityValue::class,
Set::of(new Add),
Set::of(static fn() => new Add),
);
})
->exit();
Expand Down
2 changes: 1 addition & 1 deletion documentation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ BlackBox is a [Property Based Testing](https://en.wikipedia.org/wiki/Software_te

It leverages randomness to prove the correctness of your code.

It's the main testing framework for the [Innmind ecosystem](https://innmind.github.io/documentation/).
It's the main testing framework for the [Innmind ecosystem](https://innmind.org/documentation/).

It allows to:

Expand Down
46 changes: 25 additions & 21 deletions documentation/organization/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,16 @@ Since it uses a `Generator` you can easily split them into multiple files:

=== "BlackBox"
```php title="blackbox.php"
use Innmind\BlackBox\Application;
use Innmind\BlackBox\{
Application,
Prove,
};

Application::new([])
->tryToProve(static function(): \Generator {
yield from (require 'proofs/file1.php')();
yield from (require 'proofs/file2.php')();
yield from (require 'proofs/etc.php')();
->tryToProve(static function(Prove $prove): \Generator {
yield from (require 'proofs/file1.php')($prove);
yield from (require 'proofs/file2.php')($prove);
yield from (require 'proofs/etc.php')($prove);
})
->exit();
```
Expand All @@ -22,16 +25,16 @@ Since it uses a `Generator` you can easily split them into multiple files:
use Innmind\BlackBox\{
Runner\Assert,
Set,
Prove,
};

return static function(): \Generator {
yield proof(
'Some proof',
given(Set\Integers::any()),
static function(Assert $assert, int $value) {
return static function(Prove $prove): \Generator {
yield $prove
->proof('Some proof')
->given(Set::integers()),
->test(static function(Assert $assert, int $value) {
// your code here
},
);
});
};
```

Expand All @@ -40,16 +43,16 @@ Since it uses a `Generator` you can easily split them into multiple files:
use Innmind\BlackBox\{
Runner\Assert,
Set,
Prove,
};

return static function(): \Generator {
yield proof(
'Some proof',
given(Set\Strings::any()),
static function(Assert $assert, int $value) {
return static function(Prove $prove): \Generator {
yield $prove
->proof('Some proof')
->given(Set::strings()),
->test(static function(Assert $assert, int $value) {
// your code here
},
);
});
};
```

Expand All @@ -58,10 +61,11 @@ Since it uses a `Generator` you can easily split them into multiple files:
use Innmind\BlackBox\{
Runner\Assert,
Set,
Prove,
};

return static function(): \Generator {
yield test(
return static function(Prove $prove): \Generator {
yield $prove->test(
'Some proof',
static function(Assert $assert) {
// your code here
Expand Down
8 changes: 3 additions & 5 deletions documentation/phpunit.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ Like this BlackBox is able to shrink a failing scenario. But to see the generate

If you wish to migrate to BlackBox but don't want to rewrite all your existing tests you can run them directly via BlackBox.

The first step is to prefix the `PHPUnit\Framework\TestCase` class with `Innmind\BlackBox\`.
The first step is to prefix the `PHPUnit\*` classes with `Innmind\BlackBox\`.

The second step is to load the tests like this:

Expand All @@ -126,9 +126,7 @@ use Innmind\BlackBox\{
};

Application::new()
->tryToProve(function() {
yield from Load::testsAt('path/to/your/tests');
})
->tryToProve(Load::directory('path/to/your/tests'))
->exit();
```

Expand All @@ -146,9 +144,9 @@ You can better integrate these proofs inside BlackBox via these changes:
```php title="MyTestCase.php" hl_lines="11 13 18"
use Innmind\BlackBox\{
PHPUnit\BlackBox,
PHPUnit\Framework\TestCase,
Set,
};
use PHPUnit\Framework\TestCase;

final class MyTestCase extends TestCase
{
Expand Down
4 changes: 2 additions & 2 deletions documentation/preface/terminology.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,8 @@ If you build packages, you can expose these properties. This allows developers t

Innmind uses this approach for packages such as:

- [`innmind/filesystem`](https://innmind.github.io/Filesystem/) used by [`innmind/s3`](https://packagist.org/packages/innmind/s3)
- [`formal/orm`](https://formal-php.github.io/orm/) to test its different adapters
- [`innmind/filesystem`](https://innmind.org/Filesystem/) used by [`innmind/s3`](https://packagist.org/packages/innmind/s3)
- [`formal/orm`](https://formal-php.org/orm/) to test its different adapters

## Shrinking

Expand Down
12 changes: 0 additions & 12 deletions documentation/sets.md
Original file line number Diff line number Diff line change
Expand Up @@ -447,18 +447,6 @@ Set::of(...$values);

This describes all the values that you put in (ie `#!php Set::of(true, false)` to describe booleans).

### From a generator

```php
use Innmind\BlackBox\Set;

Set::generator(static function() {
yield from $values;
});
```

This describes values that you will provide via a `Generator`.

## Higher order `Set`s

### Composite
Expand Down
Loading