Merge branch 'develop'

* develop: (24 commits)
  specify next release
  remove old documentation
  update phpunit doc
  add organization chapters
  update sets chapter
  add assertions documentation
  add getting started chapters
  add preface
  fix github link
  rebuild documentation intro
  use integers instead of letters to avoid changing the values when shrinking
  add new composite shrinking in changelog
  fix tests
  add composite shrinking documentation
  inverse logic to build the aggregate from the combination values
  replace Composite shrinking mechanism with one similar to the Sequence one
  add new sequence shrinking in changelog
  fix who calls the identity when shrinking
  CS
  document the sequence shrinking mechanism
  ...

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 5.7.0 - 2024-07-21
+
+### Added
+
+- `Innmind\BlackBox\PHPUnit\Framework\TestCase::assert()`
+- `Innmind\BlackBox\Set\Tuple`
+
+### Fixed
+
+- `$assert->same()` message not being used
+- `Innmind\BlackBox\Set\Sequence` shrinking process now correctly shrinks all values that do not affect the test
+- `Innmind\BlackBox\Set\Composite` shrinking process now correctly shrinks all values that do not affect the test
+
 ## 5.6.3 - 2024-02-19
 
 ### Fixed

documentation/assert/exceptions.md

@@ -0,0 +1,30 @@
+# Exceptions
+
+=== "Must throw"
+    ```php
+    static function(Assert $assert) {
+        $assert->throws(
+            static function() {
+                // execute some code that must throw an exception
+            },
+            $optionalExceptionClass,
+            'Optional error message',
+        );
+    }
+    ```
+
+    If the code throws an exception but it's not an instance of `$optionalExceptionClass` then the assertion fails.
+
+=== "Must not throw"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->not()
+            ->throws(
+                static function() {
+                    // execute some code that must not throw an exception
+                },
+                'Optional error message',
+            );
+    }
+    ```

documentation/assert/index.md

@@ -0,0 +1,66 @@
+# Assert
+
+The `Innmind\BlackBox\Runner\Assert` object is the only way to make assertions in your tests/proofs/properties.
+
+This object is always passed as an argument where you should apply assertions. If you don't have access to it, then you're doing something wrong.
+
+The following chapters will guide you through all the assertions you can use.
+
+The base assertions are:
+
+=== "Same"
+    ```php
+    static function(Assert $assert) {
+        $assert->same($expected, $someValue, 'Optional error message');
+        // or
+        $assert
+            ->expected($expected)
+            ->same($someValue, 'Optional error message');
+    }
+    ```
+
+    Think `===`.
+
+=== "Not same"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->expected($expected)
+            ->not()
+            ->same($someValue, 'Optional error message');
+    }
+    ```
+
+    Think `!==`.
+
+=== "Equals"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->expected($expected)
+            ->equals($someValue, 'Optional error message');
+    }
+    ```
+
+    Think `==`.
+
+=== "Not equals"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->expected($expected)
+            ->not()
+            ->equals($someValue, 'Optional error message');
+    }
+    ```
+
+    Think `!=`.
+
+=== "Force a failure"
+    ```php
+    static function(Assert $assert) {
+        $assert->fail('Error message');
+    }
+    ```
+
+    This can be useful when dealing with [exceptions](exceptions.md).

documentation/assert/memory.md

@@ -0,0 +1,108 @@
+# Memory
+
+In order for these assertions to work properly you need to:
+
+- add `declare(ticks = 1);` at the top of file where you call the assertion
+- the callable cannot use the anonymous function short notation
+
+??? example
+    ```php title="blackbox.php" hl_lines="3"
+    <?php
+    declare(strict_types = 1);
+    declare(ticks = 1);
+
+    require 'path/to/vendor/autoload.php';
+
+    use Innmind\BlackBox\{
+        Application,
+        Runner\Assert,
+    };
+
+    Application::new([])
+        ->tryToProve(static function(): \Generator {
+            yield test(
+                'Some memory test',
+                static function(Assert $assert) {
+                    $assert
+                        ->memory(static function() {
+                            // your code here
+                        })
+                        ->inLessThan()
+                        ->megaBytes(42);
+                },
+            );
+        })
+        ->exit();
+    ```
+
+=== "In less than x Bytes"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->memory(static function() {
+                // execute your code here
+            })
+            ->inLessThan()
+            ->bytes($number, 'Optional error message');
+    }
+    ```
+
+=== "In less than x KiloBytes"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->memory(static function() {
+                // execute your code here
+            })
+            ->inLessThan()
+            ->kiloBytes($number, 'Optional error message');
+    }
+    ```
+
+=== "In less than x MegaBytes"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->memory(static function() {
+                // execute your code here
+            })
+            ->inLessThan()
+            ->megaBytes($number, 'Optional error message');
+    }
+    ```
+
+=== "In more than x Bytes"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->memory(static function() {
+                // execute your code here
+            })
+            ->inMoreThan()
+            ->bytes($number, 'Optional error message');
+    }
+    ```
+
+=== "In more than x KiloBytes"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->memory(static function() {
+                // execute your code here
+            })
+            ->inMoreThan()
+            ->kiloBytes($number, 'Optional error message');
+    }
+    ```
+
+=== "In more than x MegaBytes"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->memory(static function() {
+                // execute your code here
+            })
+            ->inMoreThan()
+            ->megaBytes($number, 'Optional error message');
+    }
+    ```

documentation/assert/objects.md

@@ -0,0 +1,27 @@
+# Objects
+
+=== "Is an object"
+    ```php
+    static function(Assert $assert) {
+        $assert->object($someValue);
+    }
+    ```
+
+=== "Is an instance of"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->object($someValue)
+            ->instance($someClass, 'Optional error message');
+    }
+    ```
+
+=== "Isn't an instance of"
+    ```php
+    static function(Assert $assert) {
+        $assert
+            ->object($someValue)
+            ->not()
+            ->instance($someClass, 'Optional error message');
+    }
+    ```

documentation/assert/own.md

@@ -0,0 +1,93 @@
+# Write your own
+
+## Stateless
+
+A simple example would be to assert a string is a valid uuid.
+
+```php title="IsUuid.php"
+final class IsUuid
+{
+    public function __construct(
+        private mixed $value
+    ) {}
+
+    public function __invoke(Assert $assert): void
+    {
+        $assert
+            ->string($this->value)
+            ->matches(
+                '/^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/',
+                'Value is not a uuid',
+            );
+    }
+}
+```
+
+You can now use this assertion everywhere like this:
+
+```php
+static function(Assert $assert) {
+    $assert->matches(new IsUuid($someValue));
+}
+```
+
+## Stateful
+
+In some cases you want to carry a state when asserting values. This is usually the case when testing an API.
+
+The approach is to wrap the `Assert` object in an object of your own.
+
+Let's say you want to make HTTP requests and sometimes you want to impersonate them.
+
+```php title="Requests.php"
+use Innmind\BlackBox\Runner\Assert;
+
+final class Requests
+{
+    public function __construct(
+        private Assert $assert,
+        private ?string $bearer = null,
+    ) {}
+
+    public function responds(string $url): self
+    {
+        $response = somehowDoAnHTTPCallTo($url, $this->bearer);
+
+        $this->assert->same(200, $response->code());
+
+        return $this;
+    }
+
+    /**
+     * @param callable(self): void $action
+     */
+    public function impersonate(
+        string $bearer,
+        callable $action,
+    ): self {
+        $action(new self($this->assert, $bearer));
+
+        return $this;
+    }
+}
+```
+
+Now you can do:
+
+```php linenums="1"
+static function(Assert $assert) {
+    $requests = new Requests($assert);
+
+    $requests
+        ->responds('https://github.com')
+        ->impersonate(
+            'some Authorization bearer',
+            static fn(Requests $requests) => $requests->responds(
+                'https://github.com/settings/profile',
+            ),
+        )
+        ->responds('https://google.com');
+}
+```
+
+Calls to `responds` on line `5` and `12` do not use a bearer while the one on line `8` does.