Testing Exceptions with PHPUnit in PHP

You will learn how PHPUnit tests expected exceptions with expectException(), how to check an exception message or code, and how to ensure the exception comes from the intended line of code.

Exceptions represent abnormal or invalid situations that normal code cannot successfully complete, such as invalid input, a missing record, or an unavailable service.

A test for an exception has two jobs:

1. Arrange a situation that should fail.
2. Declare which exception is expected, then run the code.

In PHPUnit, the usual approach is to declare an expectation with expectException(). If the tested code throws an exception matching that class, the test passes. If it throws nothing, or throws a different exception type, the test fails.

Testing exceptions matters because failure behavior is part of an application's contract. For example, callers may rely on an invalid email address causing an InvalidArgumentException rather than silently creating a broken user record.

Think of an exception expectation as telling the test runner: “When I press this button, an alarm must sound.”

• expectException() describes the alarm you expect to hear.
• The method call is pressing the button.
• PHPUnit passes the test only if the matching alarm occurs.

Declare the expected alarm immediately before pressing the button. If you declare it too early, an unrelated earlier line could trigger the expected exception and make the test pass for the wrong reason.

The basic PHPUnit syntax is:

$this->expectException(ExceptionClass::class);

$object->methodThatShouldThrow();

For example, this function rejects an empty name:

function createGreeting(string $name): string
{
    if ($name === '') {
        throw new InvalidArgumentException('Name cannot be empty.');
    }

    return "Hello, {$name}!";
}

A PHPUnit test can verify that behavior:

use PHPUnit\Framework\TestCase;

final class GreetingTest extends TestCase
{
    public function (): 
    {
        ->(::);

        ();
    }
}

Consider this test:

use PHPUnit\Framework\TestCase;

final class AgeValidatorTest extends TestCase
{
    public function testNegativeAgeIsRejected(): void
    {
        $validator = new AgeValidator();

        $this->expectException(InvalidArgumentException::class);
        $this->expectExceptionMessage('Age cannot be negative.');

        $validator->validate(-1);
    }
}

Assume validate() is implemented as follows:

final class AgeValidator
{
    public function validate( ): 
    {
         ( < ) {
              ();
        }
    }
}

Exception tests are useful whenever code rejects invalid input or cannot complete an operation safely.

• API validation: Reject a request with a missing required field.
• Authentication: Throw an exception when a token is expired or malformed.
• Domain rules: Prevent an order from being paid twice.
• File processing: Report an error when an uploaded file has an unsupported format.
• Database lookups: Throw a UserNotFoundException when a required user does not exist.
• Configuration: Fail early when a required environment variable is missing.

For example, a service might reject a duplicate email address:

$this->expectException(DomainException::class);

$registrationService->register('existing@example.com', 'secret-password');

In real projects, exception tests usually focus on the public behavior of a class rather than its internal implementation.

Validate at boundaries

Validate data as it enters a controller, service, command, or domain object:

final class PasswordPolicy
{
    public function assertValid(string $password): void
    {
        if (strlen($password) < 12) {
            throw new InvalidArgumentException('Password must contain at least 12 characters.');
        }
    }
}

Test the boundary rule directly:

$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessage('at least 12 characters');

$policy->assertValid('short');

Use custom exceptions for meaningful business failures

Setting the expectation too early

This test can pass for the wrong reason if createService() throws the expected exception:

// Risky: setup might satisfy the expectation.
$this->expectException(InvalidArgumentException::class);
$service = createService();
$service->register('');

Prefer this:

$service = createService();

$this->expectException(InvalidArgumentException::class);
$service->register('');

Catching the exception without making an assertion

This test passes even if no exception is thrown:

try {
    $validator->validate(-1);
} catch (InvalidArgumentException $exception) {
    
}

// Expect an exception type
$this->expectException(InvalidArgumentException::class);
$service->run($input);

// Also require an exact message
$this->expectExceptionMessage('Input is invalid.');

// Require a message that matches a regular expression
$this->expectExceptionMessageMatches('/input.+invalid/i');

// Require an exception code
$this->expectExceptionCode(422);

• Declare expectations before the call that should throw.
• Put expectations as close as possible to that call.
• Prefer specific exception classes over Exception::class or Throwable::class.
• An expected parent exception class also matches child exceptions.
• Statements after an exception is thrown are not executed.
• Use manual try/catch plus $this->fail() only when you need custom inspection.

How do I assert that an exception is thrown in PHPUnit?

Call $this->expectException(ExceptionClass::class) immediately before invoking the code that should throw.

Does PHPUnit use assertThrows()?

The standard PHPUnit pattern is expectException(), not assertThrows(). Declare the expectation in the test, then call the method under test.

How do I test an exception message in PHPUnit?

Use $this->expectExceptionMessage('Expected message') along with expectException(). Use expectExceptionMessageMatches() when a regular expression is more appropriate.

Can I expect a parent exception class?

Yes. If you expect RuntimeException::class, an exception class that extends RuntimeException satisfies the expectation. Prefer the most specific type that your code promises to throw.

What happens if no exception is thrown?

The test fails because PHPUnit was told that an exception was expected.

Why did my exception test pass even though the wrong method threw?

The expectation was likely set before setup code or another operation that could throw the same exception. Move expectException() immediately before the intended method call.

• PHP exceptions and try/catch — Learn how application code throws, catches, and rethrows failures.
• Custom exception classes — Create meaningful exception types for domain-specific failures.
• PHPUnit assertions — Test return values, arrays, objects, and other normal outcomes.
• Input validation — Exceptions are commonly used to reject invalid data at application boundaries.
• Unit testing — Exception expectations are one way to verify a unit's observable behavior.
• Mocking dependencies in PHPUnit — Simulate dependency failures to test error translation and recovery paths.