Download the PHP package phrozenbyte/phpunit-throwable-asserts without Composer

PHPUnitThrowableAssertions

PHPUnitThrowableAssertions is a small PHPUnit extension to assert that Callables do or do not throw a specific Exception, Error, or Throwable.

This PHPUnit extension allows developers to test whether Callables throw Exceptions, Errors and other Throwables in a single assertion using the more intuitive "assert that" approach. It's a replacement for PHPUnit's built-in expectException(), expectExceptionMessage() and expectExceptionCode() methods - just more powerful.

You want more PHPUnit constraints? Check out PHPUnitArrayAssertions! It introduces various assertions to test PHP arrays and array-like data in a single assertion. The PHPUnit extension is often used for API testing to assert whether an API result matches certain criteria - regarding both its structure, and the data.

Made with :heart: by Daniel Rudolf. PHPUnitThrowableAssertions is free and open source software, released under the terms of the MIT license.

Table of contents:

1. Install
2. Usage
   1. Constraint CallableThrows
   2. Constraint CallableThrowsNot
   3. CallableProxy and CachedCallableProxy
   4. PHP errors, warnings and notices

Install

PHPUnitThrowableAssertions is available on Packagist.org and can be installed using Composer:

This PHPUnit extension was initially written for PHPUnit 8, but should work fine with any later PHPUnit version. If it doesn't, please don't hesitate to open a new Issue on GitHub, or, even better, create a Pull Request with a proposed fix.

Usage

There are three (equivalent) options to use PHPUnitThrowableAssertions:

• By using the static class PhrozenByte\PHPUnitThrowableAssertions\Assert
• By using the trait PhrozenByte\PHPUnitThrowableAssertions\ThrowableAssertsTrait in your test case
• By creating new constraint instances (PhrozenByte\PHPUnitThrowableAssertions\Constraint\…)

All options do exactly the same. Creating new constraint instances is useful for advanced assertions, e.g. together with PHPUnit\Framework\Constraint\LogicalAnd.

If you want to pass arguments to your Callable, you might want to use CallableProxy. If you want to access the Callable's return value or a possibly thrown Throwable, use CachedCallableProxy instead (specifically its getReturnValue() and getThrowable() methods). Using CallableProxy vastly improves error handling.

As explained above, PHPUnitThrowableAssertions is a more powerful alternative to PHPUnit's built-in expectException(). However, please note that PHPUnit's built-in expectExceptionMessage() matches sub strings (i.e. $this->expectExceptionMessage('test') doesn't just match the message "test", but also "This is a test"), while PHPUnitThrowableAssertions checks for equality by default (i.e. $message = 'test' matches the message "test" only). However, PHPUnitThrowableAssertions allows you to not just use strings, but also arbitrary constraints. So, for example, to achieve sub string matching, pass an instance of the PHPUnit\Framework\Constraint\StringContains constraint instead (i.e. $message = $this->stringContains('test') also matches the message "This is a test").

Constraint CallableThrows

The CallableThrows constraint asserts that a Callable throws a specific Throwable.

This constraint calls the given Callable (parameter $callable) and catches any Throwable matching the given base class (parameter $throwableBaseClassName, defaults to Throwable). Any other Throwable isn't caught. It then asserts that the Throwable's class (optional parameter $throwableClassName, defaults to Throwable), message (optional parameter $throwableMessage, defaults to null) and code (optional parameter $throwableCode, defaults to null) match the expected, or throws a ExpectationFailedException otherwise. The exception message can either be a string, requiring an exact match, or an arbitrary Constraint (e.g. PHPUnit\Framework\Constraint\StringContains) to match the exception message. The constraint optionally requires an exact match of the class name (optional parameter $throwableExactMatch, defaults to false).

The ThrowableAssertsTrait trait exposes two public methods for the CallableThrows constraint: Use ThrowableAssertsTrait::assertCallableThrows() to perform an assertion, and ThrowableAssertsTrait::callableThrows() to create a new instance of the CallableThrows constraint.

Usage:

Example:

Debugging:

Constraint CallableThrowsNot

The CallableThrowsNot constraint asserts that a Callable doesn't throw a specific Throwable. It can be used as a more specific alternative to PHPUnit's built-in expectNotToPerformAssertions() method.

This constraint calls the given Callable (parameter $callable) and catches any Throwable matching the given class (optional parameter $throwableClassName, defaults to Throwable), message (optional parameter $throwableMessage, defaults to null) and code (optional parameter $throwableCode, defaults to null). All conditions must match, otherwise the Throwable is re-thrown. The exception message can either be a string, requiring an exact match, or an arbitrary Constraint (e.g. PHPUnit\Framework\Constraint\StringContains) to match the exception message. The constraint optionally requires an exact match of the class name (optional parameter $throwableExactMatch, defaults to false).

This is not the same as negating the CallableThrows constraint, which consumes all non-matching Throwables and throws a ExpectationFailedException instead. CallableThrowsNot will rather re-throw any non-matching Throwable. A ExpectationFailedException is only thrown when the Callable throws a Throwable matching all given conditions.

The ThrowableAssertsTrait trait exposes two public methods for the CallableThrowsNot constraint: Use ThrowableAssertsTrait::assertCallableThrowsNot() to perform an assertion, and ThrowableAssertsTrait::callableThrowsNot() to create a new instance of the CallableThrowsNot constraint.

Usage:

Example:

Debugging:

CallableProxy and CachedCallableProxy

PHPUnitThrowableAsserts invokes Callables without arguments and discards a possible return value due to how PHPUnit evaluates values. One solution for this is to use anonymous functions with variable inheritance. As a neat alternative, PHPUnitThrowableAsserts provides the CallableProxy and CachedCallableProxy helper classes.

Both helper classes receive the Callable to invoke (argument $callable), and the arguments to pass (any following argument, variadic $arguments) in their constructor. They furthermore implement PHPUnit's PHPUnit\Framework\SelfDescribing interface and the toString() method, improving error handling by allowing PHPUnitThrowableAsserts to better designate the called method. CachedCallableProxy additionally implements the getReturnValue() and getThrowable() methods. getReturnValue() returns the cached return value of the Callables last invocation, while getThrowable() returns a possibly thrown Throwable.

The ThrowableAssertsTrait trait exposes two public methods to create instances of CallableProxy and CachedCallableProxy: Use ThrowableAssertsTrait::callableProxy() to create a new instance of CallableProxy, or ThrowableAssertsTrait::cachedCallableProxy() to create a new instance of CachedCallableProxy.

Usage:

Example:

PHP errors, warnings and notices

PHPUnit converts PHP errors (E_RECOVERABLE_ERROR), warnings (E_WARNING and E_USER_WARNING), notices (E_NOTICE, E_USER_NOTICE and E_STRICT), and deprecation notices (E_DEPRECATED and E_USER_DEPRECATED) to PHPUnit\Framework\Error\… exceptions (…\Error, …\Warning, …\Notice and …\Deprecated respectively) by default. This allows you to use PHPUnitThrowableAssertions's assertCallableThrowsNot() assertions to also catch any PHP error; simply use one of the PHPUnit\Framework\Error\… classes.

Please don't confuse PHP errors with PHP's Error class introduced in PHP 7.0. The latter already is a Throwable and can be caught as usual.

Example: