Custom Assertion API

[cspray]

Custom Assertion API

This Proposal was accepted as part of the 0.2.0 release

It is anticipated that the existing Assertions will be all that the framework provides out-of-the-box until we're getting closer to a 1.0 release. There's quite a bit to do with the framework and writing advanced Assertions should not be the priority. However, for those developers that are willing to try out the framework at this stage we should make it easy for them to write their own custom Assertion in such a way that it works with the AsyncUnit Assertion API. Speficially, this project should be able to support:

#[Test]
public function ensureMyOwnAssertion() {
    $this->assert()->myCustomAssertion($expected, $actual);
    yield $this->asyncAssert()->myCustomAssertion($expected, $actualPromise);
}

CustomAssertionContext

A new Context should be created that effectively acts as a registry for custom made Assertions mapped to the name of the helper method that should be used to invoke it in the TestCase. A potential interface for this could look like:

interface CustomAssertionContext {

    public function registerAssertion(string $methodName, callable<Assertion> $assertionFactory) : void;

    public function hasRegisteredAssertion(string $methodName) : bool;

    #[Throws(AssertionNotFoundException::class)]
    public function createAssertion(string $methodName, ...$args) : Assertion;

    public function registerAsyncAssertion(string $methodName, callable<AsyncAssertion> $asyncAssertionFactory) : void;

    public function hasRegisteredAsyncAssertion(string $methodName) : bool;

    #[Throws(AsyncAssertionNotFoundException::class)]
    public function createAsyncAssertion(string $methodName, ...$args) : AsyncAssertion;


}

During booting procedures a single instance of this object can be created that is provided to implementations marked as an AssertionProvider. The CustomAssertionContext can then be passed to the AssertionContext and AsyncAssertionContext with the registry of custom Assertions. Both the AssertionContext and AsyncAssertionContext can then have __call() methods implemented that will invoked any registered custom assertion.

Loading AssertionProvider

Actually getting the AssertionProvider loaded does not necessarily have to be a concern of the testing framework itself. We can make use of Labrador Plugin system to ensure all of the appropriate AssertionProvider have an opportunity to register their Assertion. The inner working of Labrador Plugins is too complex to discuss here. If at the end of this section you're still unsure how this would work please review the Labrador Plugin documentation.

A new Plugin type is introduced by our framework called AssertionProviderPlugin. A custom Plugin loader would then ensure this Plugin is invoked with the correct dependencies during the Application startup. The interface for this Plugin could look like:

interface AssertionProviderPlugin {

    // We anticipate that advanced asynchronous assertions may need something async to setup so we make sure this is async aware
    public function registerAssertions(CustomAssertionContext $context) : Promise;

}

Registering the AssertionProviderPlugin

In a Labrador Application you're required to register the Plugin before you start your Application. Normally this would be accomplished in your bootstrapping code but for this application that's not a viable option.. the consumer would have to modify the RunTestsCommand in their vendor directory! Fortunately there's 2 mechanisms that should be straightforward to implement that will register the Plugin

Autoregistration

Because we compile information before we run tests we can simply detect which classes implement the AssertionProviderPlugin and add them to the app's plugins during app startup.

Configuration

It could be possible that an AssertionProvider comes from a third-party package and not from the consumer or AsyncUnit itself. In this case we would likely not pick up the AssertionProviderPlugin during our code parsing step... you probably shouldn't be running this library on your vendor directory! In this case the consumer still needs a way to specify which AssertionProviderPlugin should be loaded.

Example Implementation

class MyCustomAssertion implements Assertion {

    public function passes(mixed $actual, string $message = null) : AssertionResult {
        if ($actual !== 'AsyncUnit') {
            return AssertionResultFactory::invalidAssertion('This is not AsyncUnit!', myCustomComparisonDisplay());
        }
    }

}

class MyCustomAssertionPlugin implements AssertionProviderPlugin {

    public function registerAssertions(CustomAssertionContext $context) : Promise {
        return call(function() use($context) {
            // $args here is everything passed to the helper method in the TestCase
            $context->registerAssertion('isAsyncUnit', function(...$args) {
                return new MyCustomAssertion();
            });
        });
    }

}

class MyCustomAssertionTestCase extends TestCase {

    #[Test]
    public function useMyAssertion() {
        $this->assert()->isAsyncUnit('AsyncUnit'); // passes
        $this->assert()->isAsyncUnit('SomeOtherUnit'); // fails
    }

}