Making Expectations

Complex test suites need to make expectations about how a test might run that can't be accomplished with the assertion API. Learn how to use expectations as another form of validating tests.

Expecting An Exception

When your code under test might throw an exception a mechanism is needed to ensure that the appropriate exception with the appropriate message has been thrown. As well, if an exception is expected and one is not thrown that should signify a test failure. In AsyncUnit this scenario is taken care of with the TestCase::expect() method.

Expecting only on Exception type

If you only need to assert that an exception is thrown and don't care what message it is simply pass the appropriate fully-qualified class name to expect()->exception(). As long as the thrown exception extends the provided type the test is considered successful.

<?php

use Cspray\Labrador\AsyncUnit\TestCase;
use Cspray\Labrador\AsyncUnit\Attribute\Test;
use Cspray\Labrador\AsyncUnit\Exception\Exception;
use Cspray\Labrador\AsyncUnit\Exception\InvalidArgumentException;

class MyExceptionTestCase extends TestCase {

    #[Test]
    public function checkExceptionThrown() {
        $this->expect()->exception(Exception::class);
        
        throw new InvalidArgumentException();
    }

}

Generally, expected exception types should be as specific as possible. This example is intended to show that as long as the exception extends the type passed the test is successful. It is possible that the code under test could throw some other type of Exception that is not expected and this test will now give a false sense of security and hide potentially problematic behavior until it actually hits production.

Expecting on Exception type and message

It is possible, and recommended, to ensure that the correct exception and message is thrown. By asserting the appropriate message is thrown you can be sure that the precise expected behavior is exhibited by the code under test.

<?php

use Cspray\Labrador\AsyncUnit\TestCase;
use Cspray\Labrador\AsyncUnit\Attribute\Test;
use Cspray\Labrador\AsyncUnit\Exception\Exception;
use Cspray\Labrador\AsyncUnit\Exception\InvalidArgumentException;

class MyExceptionTestCase extends TestCase {

    #[Test]
    public function checkExceptionThrown() {
        $this->expect()->exception(Exception::class);
        $this->expect()->exceptionMessage('This is the message we expect');
        
        throw new InvalidArgumentException('This is the message we expect');
    }

}

Now this test will fail if either the exception thrown does not extend the expected exception or if the message in the thrown exception does not match our expected message.

Expecting an Exception not thrown

If you expect an exception to occur and nothing is thrown the test is marked as a failure.

<?php

use Cspray\Labrador\AsyncUnit\TestCase;
use Cspray\Labrador\AsyncUnit\Attribute\Test;
use Cspray\Labrador\AsyncUnit\Exception\Exception;
use Cspray\Labrador\AsyncUnit\Exception\InvalidArgumentException;

class MyExceptionTestCase extends TestCase {

    #[Test]
    public function checkExceptionThrown() {
        $this->expect()->exception(Exception::class);
        $this->expect()->exceptionMessage('This is the message we expect');
        
        doSomething(); // no exception is thrown
    }

}

The above test would be marked as a failure because no exception was thrown but there was one expected.

Expecting No Assertions

You could be in a testing situation where you can't easily make an assertion to validate a test. By default not making an assertion is considered a failure. To prevent this from happening you can utilize expect()->noAssertions(). This expectation ensures that no assert() or asyncAssert() operations are performed for the test.

<?php

use Cspray\Labrador\AsyncUnit\TestCase;
use Cspray\Labrador\AsyncUnit\Attribute\Test;


class MyExceptionTestCase extends TestCase {

    #[Test]
    public function checkExceptionThrown() {
        $this->expect()->noAssertions();
        
        doSomething();
        
        // Check something that can't be asserted
    }

}