phrozenbyte / phpunit-throwable-asserts
Provides various Throwable-related PHPUnit assertions.
Installs: 37 596
Dependents: 2
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: ^7.2 || ^8.0
Requires (Dev)
- incompass/coverage: ^1.0
- mockery/mockery: ^1.3
- php-parallel-lint/php-parallel-lint: ^1.2
- phpunit/phpunit: ^8
- psalm/plugin-mockery: ^0.7.0
- psalm/plugin-phpunit: ^0.15.1
- symfony/yaml: ^4.4
- vimeo/psalm: ^4.5
Conflicts
- phpunit/phpunit: <8.0
This package is auto-updated.
Last update: 2024-10-16 01:53:41 UTC
README
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 ❤️ by Daniel Rudolf. PHPUnitThrowableAssertions
is free and open source software, released under the terms of the MIT license.
Table of contents:
Install
PHPUnitThrowableAssertions
is available on Packagist.org and can be installed using Composer:
composer require --dev phrozenbyte/phpunit-throwable-asserts
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:
// using `PhrozenByte\PHPUnitThrowableAsserts\ThrowableAssertsTrait` trait ThrowableAssertsTrait::assertCallableThrows( callable $callable, // the Callable to call string $throwableClassName = Throwable::class, // assert that a Throwable of the given class is thrown Constraint|string $throwableMessage = null, // assert that its message matches the given constraint int|string $throwableCode = null, // assert that its code matches the given one bool $throwableExactMatch = false, // whether an exact match of the class name is required string $throwableBaseClassName = Throwable::class, // catch all Throwables of the given class string $message = '' // additional information about the test ); // using new instance of `PhrozenByte\PHPUnitThrowableAsserts\Constraint\CallableThrows` new CallableThrows( string $className = Throwable::class, Constraint|string $message = null, int|string $code = null, bool $exactMatch = false, string $baseClassName = Throwable::class );
Example:
$controller = new BookController(); $bookName = "The Hitchhiker's Guide to the Galaxy"; $bookReleaseDate = '1979-10-12'; $this->assertCallableThrows( $this->callableProxy([ $controller, 'create' ], $bookName, $bookReleaseDate), BookAlreadyExistsException::class, 'Unable to create book: Book already exists' );
Debugging:
$service = new HitchhikersGuideService(); $towel = false; $answer = 42; $this->assertCallableThrows( static function () use ($service, $towel, $answer) { $service->checkAnswer($answer); // throws a OpaqueAnswerException $service->checkTowel($towel); // throws a PanicException (unreachable code) }, PanicException::class, 'I forgot my towel' ); // Will fail with the following message: // // Failed asserting that {closure}() throws a PanicException whose message is 'Time to panic'. // Encountered invalid OpaqueAnswerException: I do not understand. // --- Expected // +++ Actual // @@ @@ // -'Time to panic' // +'I do not understand'
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 Throwable
s 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:
// using `PhrozenByte\PHPUnitThrowableAsserts\ThrowableAssertsTrait` trait ThrowableAssertsTrait::assertCallableThrowsNot( callable $callable, // the Callable to call string $throwableClassName = Throwable::class, // assert that no Throwable of the given class is thrown Constraint|string $throwableMessage = null, // catch Throwables matching the given message constraint only int|string $throwableCode = null, // catch Throwables matching the given code only bool $throwableExactMatch = false, // whether only Throwables of the given class are caught string $message = '' // additional information about the test ); // using new instance of `PhrozenByte\PHPUnitThrowableAsserts\Constraint\CallableThrowsNot` new CallableThrowsNot( string $className = Throwable::class, Constraint|string $message = null, int|string $code = null, bool $exactMatch = false );
Example:
$controller = CharacterController(); $character = 'Prostetnik Vogon Jeltz'; $this->assertCallableThrowsNot( $this->callableProxy([ $controller, 'meet' ], $character), VogonWantsToReadPoetException::class );
Debugging:
$controller = new BookController(); $bookName = "The Hitchhiker's Guide to the Galaxy"; $bookReleaseDate = '1979-10-12'; $this->assertCallableThrowsNot( $this->callableProxy([ $controller, 'create' ], $bookName, $bookReleaseDate), BookAlreadyExistsException::class ); // Will fail with the following message: // // Failed asserting that BookController::create() does not throw a BookAlreadyExistsException // Encountered invalid BookAlreadyExistsException: Unable to create book: Book already exists
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:
// create new instance of `PhrozenByte\PHPUnitThrowableAsserts\CallableProxy` // using the `PhrozenByte\PHPUnitThrowableAsserts\ThrowableAssertsTrait` trait ThrowableAssertsTrait::callableProxy( callable $callable, // the Callable to invoke mixed ...$arguments // the arguments to pass to the Callable ); // create new instance of `PhrozenByte\PHPUnitThrowableAsserts\CachedCallableProxy` // using the `PhrozenByte\PHPUnitThrowableAsserts\ThrowableAssertsTrait` trait $proxy = ThrowableAssertsTrait::cachedCallableProxy( callable $callable, // the Callable to invoke mixed ...$arguments // the arguments to pass to the Callable ); // get return value of the Callable (`CachedCallableProxy` only) $proxy->getReturnValue(); // get a possibly thrown Throwable (`CachedCallableProxy` only) $proxy->getThrowable();
Example:
$computer = new DeepThought(); $question = 'What is the Answer to the Ultimate Question of Life, the Universe, and Everything?'; // using `PhrozenByte\PHPUnitThrowableAsserts\CallableProxy` // if the assertion fails, `ExpectationFailedException`'s message will point to DeepThought::ask() as source $askQuestion = $this->cachedCallableProxy([ $computer, 'ask' ], $question); $this->assertCallableThrowsNot($askQuestion); $answer = $askQuestion->getReturnValue(); // using anonymous function // if the assertion fails, `ExpectationFailedException` will just name {closure} as source $answer = null; $this->assertCallableThrowsNot(static function () use ($computer, $question, &$answer) { // use variable reference to pass the return value $answer = $computer->ask($question); });
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 assertCallableThrows()
and 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:
$this->assertCallableThrows( static function () { // triggers a E_NOTICE PHP error echo $undefinedVariable; }, \PHPUnit\Framework\Error\Notice::class, 'Undefined variable: undefinedVariable' );