PHPUnit Assert Exception Thrown: A Guide

• Introduction
• Step-by-Step Guide
• Code Example
• Additional Notes
• Summary
• Conclusion
• References

Testing for exceptions is a crucial part of writing robust PHP code. PHPUnit, the de facto testing framework for PHP, provides several methods for asserting that exceptions are thrown when expected. This introduction will guide you through the basics of exception testing in PHPUnit, covering how to test for specific exception types, exception messages, and the absence of exceptions. Additionally, we'll touch upon exception testing in the context of Laravel's HTTP tests.

To test for exceptions in PHPUnit, you can use the expectException() method. This method takes the name of the exception class you expect to be thrown.

public function testDivisionByZero() {
    $this->expectException(DivisionByZeroError::class);
    1 / 0;
}

You can also test for specific exception messages using expectExceptionMessage():

$this->expectExceptionMessage('Division by zero');

To assert that an exception is not thrown, you can use a try-catch block and then call fail():

try {
    // Code that should not throw an exception
    $this->assertTrue(true); 
} catch (Exception $e) {
    $this->fail('An exception was thrown when it should not have been.');
}

In Laravel, you can test for exceptions thrown in HTTP contexts using the seeStatusCode() method:

$this->get('/some-route')->seeStatusCode(404);

Remember that assertions in PHP 8 and above throw exceptions by default.

This code provides examples of how to test for exceptions in PHPUnit tests. It shows how to test for specific exception types and messages using expectException and expectExceptionMessage. It also demonstrates how to assert that an exception is not thrown using a try-catch block and the fail method. Additionally, it includes an example of testing for exceptions in Laravel HTTP contexts using the assertStatus method to check for a specific HTTP status code.

This code example demonstrates different ways to test for exceptions in PHPUnit:

1. Testing for a specific exception type:

<?php

use PHPUnit\Framework\TestCase;

class ExceptionTest extends TestCase
{
    public function testDivisionByZeroThrowsException()
    {
        $this->expectException(DivisionByZeroError::class);
        1 / 0;
    }
}

2. Testing for a specific exception message:

<?php

use PHPUnit\Framework\TestCase;

class ExceptionTest extends TestCase
{
    public function testDivisionByZeroThrowsExceptionWithMessage()
    {
        $this->expectException(DivisionByZeroError::class);
        $this->expectExceptionMessage('Division by zero');
        1 / 0;
    }
}

3. Asserting that an exception is not thrown:

<?php

use PHPUnit\Framework\TestCase;

class ExceptionTest extends TestCase
{
    public function testNoExceptionThrown()
    {
        try {
            // Code that should not throw an exception
            $result = 2 + 2;
            $this->assertEquals(4, $result);
        } catch (Exception $e) {
            $this->fail('An exception was thrown when it should not have been: ' . $e->getMessage());
        }
    }
}

4. Testing for exceptions in Laravel HTTP contexts:

<?php

use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function testRouteNotFound()
    {
        $response = $this->get('/non-existent-route');

        $response->assertStatus(404);
    }
}

Note: This example uses Laravel's built-in testing features.

These examples demonstrate how to use expectException(), expectExceptionMessage(), fail(), and Laravel's seeStatusCode() (or assertStatus()) to test for exceptions in your PHPUnit tests. Remember that assertions in PHP 8 and above throw exceptions by default, so you can use try-catch blocks to handle them.

• Purpose of Exception Testing: Exception testing is not about testing the exception class itself (PHPUnit handles that). It's about ensuring your code throws the correct exception under specific circumstances. This helps guarantee your application handles errors predictably.

• Alternatives to fail(): While try-catch with fail() works for asserting no exceptions, it can be less readable. PHPUnit offers:

  • expectNotToPerformAssertions(): Use this inside the try block if you expect the code to run without triggering any assertions (including exceptions).
  • doesNotThrowException() (deprecated): This method is less flexible and generally discouraged in favor of the above approaches.

• Exception Hierarchy: expectException() checks for the specified exception or any of its subclasses. If you need to be highly specific, consider additional checks within the try block.

• Beyond expectExceptionMessage():

  • expectExceptionCode(): Verify the exception code if your application uses custom codes.
  • Regular Expressions: For more complex message matching, use expectExceptionMessageMatches() with a regular expression.

• Laravel Specifics:

  • assertStatus() vs. seeStatusCode(): While both check HTTP status codes, assertStatus() is generally preferred in newer Laravel versions for its clearer error messages.
  • Testing Exception Handling: Laravel allows you to test custom exception handlers. You can assert on the rendered view, redirected URL, or other aspects of your error handling logic.

• Best Practices:

  • Test for Specific Exceptions: Avoid generic Exception catches in tests. Be as specific as possible to ensure the correct error is being handled.
  • One Exception per Test: Ideally, each test should focus on a single exception scenario for clarity and maintainability.
  • Meaningful Messages: Use descriptive exception messages in your code and assertions to make debugging easier.

Exception testing is a cornerstone of robust PHP development, and PHPUnit provides the tools to make it straightforward. By incorporating the techniques outlined in this article—testing for specific exception types, messages, and even the absence of exceptions—you can ensure your PHP applications are robust, reliable, and predictable in the face of errors. Remember to leverage PHPUnit's assertions and Laravel's HTTP testing features to streamline your exception testing workflow. By embracing a test-driven approach and paying close attention to exception handling, you can create high-quality PHP applications that stand up to real-world usage.

• Testing Exceptions in PHPUnit | BackEndTea | Last week i gave 10 phpunit tips. This week we’ll take a look at testing exceptions, which wasn’t covered in that post. Lets start with some example code that we will be testing. We have the Email and EmailValidator classes. Email is a value object that makes sure it is a valid email. We use the EmailValidator to make sure that the emails are only from our company.
• php - PHPUnit - testing for exception not thrown? - Stack Overflow | Sep 1, 2020 ... PHPUnit - testing for exception not thrown? · The testCanBeCreatedFromValidEmailAddress method tests the happy path. It won't pass if an ...
• Testing an exception is not thrown · Issue #171 ... | Here, http://phpunit.de/manual/current/en/writing-tests-for-phpunit.html it says that you can easily test an exception is thrown. But maybe you want to test that an exception is not thrown. For exa...
• 2. Writing Tests for PHPUnit — PHPUnit 10.5 Manual | Expecting Exceptions . Example 2.3 shows how to use the expectException() method to test whether an exception is thrown by the code under test ...
• Testing that Exception was thrown | ... test')->seeStatusCode(404); }. I just rethrow the exception in app/Exceptions/Handler.php : Copy public function render($request, Exception $e) { throw $e ...
• Testing Exceptional Exceptions > PHPUnit: Unit Testing with a Bite ... | Do you remember when we were seeing this exception because our app didn't understand Maverick's "hungry" status? Welp, we've fixed that, but we still need to take care of one minor detail. Next time GenLab throws us a curve ball, like setting "Status: Antsy" on a dino, "...
• Assertions throw exceptions by default - PHP 8.0 • PHP.Watch | In PHP 8.0, the default value for assert.exception INI value is changed from 0 to 1 . This means failed assertions will throw an AssertionError exception by ...
• testing - Magento 2 Unit test for exception - Magento Stack Exchange | Oct 17, 2017 ... ... phpunit.html#writing-tests-for-phpunit.exceptions.examples.ExceptionTest.php /** * Test save() method when exception is thrown */ public ...
• HTTP Tests - Laravel 11.x - The PHP Framework For Web Artisans | Laravel is a PHP web application framework with expressive, elegant syntax. We’ve already laid the foundation — freeing you to create without sweating the small things.