# Making Expectations

## 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
<?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
<?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
<?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
<?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
    }

}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.labrador-kennel.io/async-unit/tutorials/making-expectations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.