bovigo/assert
Provides assertions for unit tests., (*1)
Package status
, (*2)
, (*3)
Installation
bovigo/assert is distributed as Composer package.
To install it as a development dependency of your package use the following
command:, (*4)
composer require --dev "bovigo/assert": "^8.0"
To install it as a runtime dependency for your package use the following command:, (*5)
composer require "bovigo/assert=^7.0"
Requirements
bovigo/assert 8.x requires at least PHP 8.2., (*6)
Why?
The original idea was to explore how a more functional approach to using
assertions in unit tests could look like, and if it would make for a better
reading of test code. Personally, I found the results convincing enough that I
wanted to use it in my own code, so I made a package of it., (*7)
Usage
All assertions are written in the same way using functions:, (*8)
assertThat(303, equals(303));
assertThat($someArray, isOfSize(3), 'array always must have size 3');
The first parameter is the value to test, and the second is the predicate that
should be used to test the value. Additionally, an optional description can be
supplied to enhance clarity in case the assertion fails., (*9)
In case the predicate fails an AssertionFailure will be thrown with useful
information of why the test failed. In case PHPUnit is used AssertionFailure
is an instance of \PHPUnit\Framework\AssertionFailedError so it
integrates nicely into PHPUnit, yielding a similar test output as PHPUnit's
constraints. Here is an example of the output in case of a test failure:, (*10)
1) bovigo\assert\predicate\RegexTest::stringRepresentationContainsRegex
Failed asserting that 'matches regular expression "/^([a-z]{3})$/"' is equal to <string:matches regular expession "/^([a-z]{3})$/">.
--- Expected
+++ Actual
@@ @@
-'matches regular expession "/^([a-z]{3})$/"'
+'matches regular expression "/^([a-z]{3})$/"'
bovigo-assert/src/test/php/predicate/RegexTest.php:99
For the sake of brevity below it is assumed the used functions are imported into
the current namespace via, (*11)
use function bovigo\assert\assertThat;
use function bovigo\assert\predicate\isOfSize;
use function bovigo\assert\predicate\equals;
// ... and so on
List of predicates
This is the list of predicates that are included in bovigo/assert by default., (*12)
isNull()
Tests if value is null., (*13)
assertThat($value, isNull());
Alias: bovigo\assert\assertNull($value, $description = null), (*14)
isNotNull()
Tests that value is not null., (*15)
assertThat($value, isNotNull());
Alias: bovigo\assert\assertNotNull($value, $description = null), (*16)
isEmpty()
Tests that value is empty. Empty is defined as follows:, (*17)
- In case the value is an instance of
\Countable it is empty when its count
is 0.
- For all other values the rules for PHP's
empty() apply.
assertThat($value, isEmpty());
Aliases:
* bovigo\assert\assertEmpty($value, $description = null)
* bovigo\assert\assertEmptyString($value, $description = null)
* bovigo\assert\assertEmptyArray($value, $description = null), (*18)
isNotEmpty()
Tests that value is not empty. See isEmpty() for definition of emptyness., (*19)
assertThat($value, isNotEmpty());
Alias: bovigo\assert\assertNotEmpty($value, $description = null), (*20)
isTrue()
Tests that a value is true. The value must be boolean true, no value conversion
is applied., (*21)
assertThat($value, isTrue());
Alias: bovigo\assert\assertTrue($value, $description = null), (*22)
isFalse()
Tests that a value is false. The value must be boolean false, no value
conversion is applied., (*23)
assertThat($value, isFalse());
Alias: bovigo\assert\assertFalse($value, $description = null), (*24)
equals($expected)
Tests that a value equals the expected value. The optional parameter $delta
can be used when equality of float values should be tested and allows for a
certain range in which two floats are considered equal., (*25)
assertThat($value, equals('Roland TB 303'));
In case a delta is needed, e.g. for float values, the required delta can be set:, (*26)
assertThat($value, equals(5)->withDelta(0.1));
isNotEqualTo($unexpected)
Tests that a value is not equal to the unexpected value. The optional parameter
$delta can be used when equality of float values should be tested and allows
for a certain range in which two floats are considered equal., (*27)
assertThat($value, isNotEqualTo('Roland TB 303'));
In case a delta is needed, e.g. for float values, the required delta can be set:, (*28)
assertThat($value, isNotEqualTo(5)->withDelta(0.1));
isInstanceOf($expectedType)
Tests that a value is an instance of the expected type., (*29)
assertThat($value, isInstanceOf(\stdClass::class));
isNotInstanceOf($unexpectedType)
Tests that a value is not an instance of the unexpected type., (*30)
assertThat($value, isNotInstanceOf(\stdClass::class));
isSameAs($expected)
Tests that a value is identical to the expected value. Both values are compared
with ===, the according rules apply., (*31)
assertThat($value, isSameAs($anotherValue));
isNotSameAs($unexpected)
Tests that a value is not identical to the unexpected value. Both values are
compared with ===, the according rules apply., (*32)
assertThat($value, isNotSameAs($anotherValue));
isOfSize($expectedSize)
Tests that a value has the expected size. The rules for the size are as follows:, (*33)
- For strings, their length in bytes is used.
- For array and instances of
\Countable the value of count() is used.
- For instances of
\Traversable the value of iterator_count() is used. To
prevent moving the pointer of the traversable, iterator_count() is applied
against a clone of the traversable.
- All other value types will be rejected.
assertThat($value, isOfSize(3));
isNotOfSize($unexpectedSize)
Tests that a value does not have the unexpected size. The rules are the same as
for isOfSize($expectedSize)., (*34)
assertThat($value, isNotOfSize(3));
isOfType($expectedType)
Tests that a value is of the expected internal PHP type., (*35)
assertThat($value, isOfType('resource'));
Aliases
Since release 5.0 some alias functions are provided to prevent typos in usages of that function:, (*36)
bovigo\assert\predicate\isArray()bovigo\assert\predicate\isBool()bovigo\assert\predicate\isFloat()bovigo\assert\predicate\isInt()bovigo\assert\predicate\isNumeric()bovigo\assert\predicate\isObject()bovigo\assert\predicate\isResource()bovigo\assert\predicate\isString()bovigo\assert\predicate\isScalar()bovigo\assert\predicate\isCallable()bovigo\assert\predicate\isIterable()
isNotOfType($unexpectedType)
Tests that a value is not of the unexpected internal PHP type., (*37)
assertThat($value, isNotOfType('resource'));
Aliases
Since release 5.0 some alias functions are provided to prevent typos in usages of that function. Please note that some are specific to ensure the code you write with them forms a grammatically valid sentence., (*38)
bovigo\assert\predicate\isNotAnArray()bovigo\assert\predicate\isNotBool()bovigo\assert\predicate\isNotFloat()bovigo\assert\predicate\isNotInt()bovigo\assert\predicate\isNotNumeric()bovigo\assert\predicate\isNotAnObject()bovigo\assert\predicate\isNotAResource()bovigo\assert\predicate\isNotAString()bovigo\assert\predicate\isNotScalar()bovigo\assert\predicate\isNotCallable()bovigo\assert\predicate\isNotIterable()
isGreaterThan($expected)
Tests that a value is greater than the expected value., (*39)
assertThat($value, isGreaterThan(3));
isGreaterThanOrEqualTo($expected)
Tests that a value is greater than or equal to the expected value., (*40)
assertThat($value, isGreaterThanOrEqualTo(3));
isLessThan($expected)
Tests that a value is less than the expected value., (*41)
assertThat($value, isLessThan(3));
isLessThanOrEqualTo($expected)
Tests that a value is less than or equal to the expected value., (*42)
assertThat($value, isLessThanOrEqualTo(3));
contains($needle)
Tests that $needle is contained in value. The following rules apply:, (*43)
-
null is contained in null.
- A string can be contained in another string. The comparison is case sensitive.
-
$needle can be a value of an array or a \Traversable. Value and $needle
are compared with ===.
- For all other cases, the value is rejected.
assertThat($value, contains('Roland TB 303'));
Sometimes it is necessary to differentiate between arrays, Traversables and strings.
If a particular type should be enforced it is recommended to combine predicates:, (*44)
assertThat($value, isArray()->and(contains('Roland TB 303')));
assertThat($value, isString()->and(contains('Roland TB 303')));
assertThat($value, isInstanceOf(\Iterator::class)->and(contains('Roland TB 303')));
doesNotContain($needle)
Tests that $needle is not contained in value. The rules of contains($needle)
apply., (*45)
assertThat($value, doesNotContain('Roland TB 303'));
hasKey($key)
Tests that an array or an instance of \ArrayAccess have a key with given name.
The key must be either of type integer or string. Values that are neither an
array nor an instance of \ArrayAccess are rejected., (*46)
assertThat($value, hasKey('roland'));
doesNotHaveKey($key)
Tests that an array or an instance of \ArrayAccess does not have a key with
given name. The key must be either of type integer or string. Values that
are neither an array nor an instance of \ArrayAccess are rejected., (*47)
assertThat($value, doesNotHaveKey('roland'));
containsSubset($other)
Available since release 6.2.0., (*48)
Tests that $other contains the value., (*49)
assertThat($value, containsSubset(['TB-303', 'TR-808']));
matches($pattern)
Tests that a string matches the given pattern of a regular expression. If the
value is not a string it is rejected. The test is successful if the pattern
yields at least one match in the value., (*50)
assertThat($value, matches('/^([a-z]{3})$/'));
doesNotMatch($pattern)
Tests that a string does not match the given pattern of a regular expression. If
the value is not a string it is rejected. The test is successful if the pattern
yields no match in the value., (*51)
assertThat($value, doesNotMatch('/^([a-z]{3})$/'));
Available since release 3.2.0., (*52)
Tests that a string matches the given PHP format expression. If the value is not
a string it is rejected. The test is successful if the format yields at least
one match in the value. The format string may contain the following placeholders:, (*53)
-
%e: Represents a directory separator, for example / on Linux.
-
%s: One or more of anything (character or white space) except the end of line character.
-
%S: Zero or more of anything (character or white space) except the end of line character.
-
%a: One or more of anything (character or white space) including the end of line character.
-
%A: Zero or more of anything (character or white space) including the end of line character.
-
%w: Zero or more white space characters.
-
%i: A signed integer value, for example +3142, -3142.
-
%d: An unsigned integer value, for example 123456.
-
%x: One or more hexadecimal character. That is, characters in the range 0-9, a-f, A-F.
-
%f: A floating point number, for example: 3.142, -3.142, 3.142E-10, 3.142e+10.
-
%c: A single character of any sort.
assertThat($value, matchesFormat('%w'));
Available since release 3.2.0., (*54)
Tests that a string does not match the given PHP format expression. If the value
is not a string it is rejected. The test is successful if the pattern yields no
match in the value. See above for a list of possible formats., (*55)
assertThat($value, doesNotMatchFormat('%w'));
isExistingFile($basePath = null)
Tests that the value denotes an existing file. If no $basepath is supplied the
value must either be an absolute path or a relative path to the current working
directory. When $basepath is given the value must be a relative path to this
basepath., (*56)
assertThat($value, isExistingFile());
assertThat($value, isExistingFile('/path/to/files'));
isNonExistingFile($basePath = null)
Tests that the value denotes a file which does not exist. If no $basepath is
supplied the value must either be an absolute path or a relative path to the
current working directory. When $basepath is given the value must be a
relative path to this basepath., (*57)
assertThat($value, isNonExistingFile());
assertThat($value, isNonExistingFile('/path/to/files'));
isExistingDirectory($basePath = null)
Tests that the value denotes an existing directory. If no $basepath is
supplied the value must either be an absolute path or a relative path to the
current working directory. When $basepath is given the value must be a
relative path to this basepath., (*58)
assertThat($value, isExistingDirectory());
assertThat($value, isExistingDirectory('/path/to/directories'));
isNonExistingDirectory($basePath = null)
Tests that the value denotes a non-existing directory. If no $basepath is
supplied the value must either be an absolute path or a relative path to the
current working directory. When $basepath is given the value must be a
relative path to this basepath., (*59)
assertThat($value, isNonExistingDirectory());
assertThat($value, isNonExistingDirectory('/path/to/directories'));
startsWith($prefix)
Available since release 1.1.0., (*60)
Tests that the value which must be a string starts with given prefix., (*61)
assertThat($value, startsWith('foo'));
doesNotStartWith($prefix)
Available since release 1.1.0., (*62)
Tests that the value which must be a string does not start with given prefix., (*63)
assertThat($value, startsWith('foo'));
endsWith($suffix)
Available since release 1.1.0., (*64)
Tests that the value which must be a string ends with given suffix., (*65)
assertThat($value, endsWith('foo'));
doesNotEndWith($suffix)
Available since release 1.1.0., (*66)
Tests that the value which must be a string does not end with given suffix., (*67)
assertThat($value, doesNotEndWith('foo'));
each($predicate)
Available since release 1.1.0., (*68)
Applies a predicate to each value of an array or traversable., (*69)
assertThat($value, each(isInstanceOf($expectedType));
Please note that an empty array or traversable will result in a successful test.
If it must not be empty use isNotEmpty()->and(each($predicate)):, (*70)
assertThat($value, isNotEmpty()->and(each(isInstanceOf($expectedType))));
It can also be used with any callable:, (*71)
assertThat($value, each('is_nan'));
assertThat($value, each(function($value) { return substr($value, 4, 3) === 'foo'; }));
eachKey($predicate)
Available since release 1.3.0., (*72)
Applies a predicate to each key of an array or traversable., (*73)
assertThat($value, eachKey(isOfType('int'));
Please note that an empty array or traversable will result in a successful test.
If it must not be empty use isNotEmpty()->and(eachKey($predicate)):, (*74)
assertThat($value, isNotEmpty()->and(eachKey(isOfType('int'))));
It can also be used with any callable:, (*75)
assertThat($value, eachKey('is_int'));
assertThat($value, eachKey(function($value) { return substr($value, 4, 3) === 'foo'; }));
not($predicate)
Reverses the meaning of a predicate., (*76)
assertThat($value, not(isTrue()));
It can also be used with any callable:, (*77)
assertThat($value, not('is_nan'));
assertThat($value, not(function($value) { return substr($value, 4, 3) === 'foo'; }));
Combining predicates
Each predicate provides both two methods to combine this predicate with another
predicate into a new predicate., (*78)
and($predicate)
Creates a predicate where both combined predicate must be true so that the
combined predicate is true as well. If one of the predicates fails, the
combined predicate will fail as well., (*79)
assertThat($value, isNotEmpty()->and(eachKey(isOfType('int'))));
It can also be used with any callable:, (*80)
assertThat($value, isNotEmpty()->and('is_string'));
or($predicate)
Creates a predicate where one of the combined predicates must be true. Only if
all predicates fail the combined predicate will fail as well., (*81)
assertThat($value, equals(5)->or(isLessThan(5)));
It can also be used with any callable:, (*82)
assertThat($value, isNull()->or('is_finite'));
User defined predicates
To define a predicate to be used in an assertion there are two possibilities:, (*83)
Use a callable
You can pass anything that is a callable to the assertThat() function:, (*84)
assertThat($value, 'is_nan');
This will create a predicate which uses PHP's builtin is_nan() function to
test the value., (*85)
The callable should accept a single value (the value to test, obviously) and
must return true on success and false on failure. It is also allowed to
throw any exception., (*86)
Here is an example with a closure:, (*87)
assertThat(
$value,
function($value)
{
if (!is_string($value)) {
throw new \InvalidArgumentException(
'Given value is not a string.'
);
}
return substr($value, 4, 3) === 'foo';
}
);
Extend bovigo\assert\predicate\Predicate
The other possibility is to extend the bovigo\assert\predicate\Predicate class.
You need to implement at least the following methods:, (*88)
public function test($value)
This method receives the value to test and should return true on success and
false on failure. It is also allowed to throw any exception., (*89)
public function __toString()
This method must return a proper description of the predicate which fits into
the sentences shown when an asssertion fails. These sentences are composed as
follows:, (*90)
Failed asserting that [description of value] [description of predicate]., (*91)
Additionally, the predicate can influence [description of value] by overriding
the describeValue(Exporter $exporter, $value) method., (*92)
Instant failure
Available since release 1.2.0., (*93)
In case assertions are not enough and the test needs to fail when it reaches a
certain point, bovigo\assert\fail($description) can be used to trigger an
instant assertion failure:, (*94)
try {
somethingThatThrowsFooException();
fail('Expected ' . FooException::class . ', gone none');
} catch (FooException $fo) {
// some assertions on FooException
}
phpstan and early terminating function calls
Available since release 5.1.0, (*95)
In case you are using phpstan bovigo/assert
provides a config file you can include in your phpstan config so early terminating
function calls with fail() are recognized., (*96)
includes:
- vendor/bovigo/assert/src/main/resources/phpstan/bovigo-assert.neon
Expectations
Available since release 1.6.0, (*97)
Expectations can be used to check that a specific piece of code does or does not
throw an exception or trigger an error. It can also be used to check that after
a specific piece of code ran assertions are still true, despite of whether the
code in question succeeded or not., (*98)
Expectations on exceptions
Note: since release 2.1.0 it is also possible to use expectations with \Error., (*99)
Check that a piece of code, e.g. a function or method, throws an exception:, (*100)
expect(function() {
// some piece of code which is expected to throw SomeException
})->throws(SomeException::class);
It is also possible to expect any exception, not just a specific one, by leaving
out the class name of the exception:, (*101)
expect(function() {
// some piece of code which is expected to throw any exception
})->throws();
Since release 2.1.0 it is possible to verify that exactly a given exception was
thrown:, (*102)
$exception = new \Exception('failure');
expect(function() use ($exception) {
throw $exception;
})->throws($exception);
This will perform an assertion with isSameAs($exception) for the thrown
exception., (*103)
Additionally checks on the thrown exception can be performed:, (*104)
expect(function() {
// some piece of code which is expected to throw SomeException
})
->throws(SomeException::class)
->withMessage('some failure occured');
The following checks on the exception are possible:
* withMessage(string $expectedMessage)
Performs an assertion with equals() on the exception message.
* message($predicate)
Performs an assertion with the given predicate on the exception message.
* withCode(int $expectedCode)
Performs an assertion with equals() on the exception code.
* with($predicate)
Performs an assertion on the whole exception with given predicate. The
predicate will receive the exception as argument and can perform any check., (*105)
expect(function() {
// some piece of code which is expected to throw SomeException
})
->throws(SomeException::class)
->with(
function(SomeException $e) { return null !== $e->getPrevious(); },
'exception does have a previous exception'
);
Of course you can also check that a specific exception did not occur:, (*106)
expect(function() {
// some piece of code which is expected to not throw SomeException
})->doesNotThrow(SomeException::class);
By leaving out the exception name you ensure that the code doesn't throw any
exception at all:, (*107)
expect(function() {
// some piece of code which is expected to not throw any exception
})->doesNotThrow();
In case any of these expectations fail an AssertionFailure will be thrown., (*108)
Expectations on errors
Available since release 2.1.0, (*109)
Check that a piece of code, e.g. a function or method, triggers an error:, (*110)
expect(function() {
// some piece of code which is expected to trigger an error
})->triggers(E_USER_ERROR);
It is also possible to expect any error, not just a specific one, by leaving
out the error level:, (*111)
expect(function() {
// some piece of code which is expected to trigger an error
})->triggers();
Additionally checks on the triggered error can be performed:, (*112)
expect(function() {
// some piece of code which is expected to trigger an error
})
->triggers(E_USER_WARNING)
->withMessage('some error occured');
The following checks on the exception are possible:
* withMessage(string $expectedMessage)
Performs an assertion with equals() on the error message.
* message($predicate)
Performs an assertion with the given predicate on the error message., (*113)
In case any of these expectations fail an AssertionFailure will be thrown., (*114)
Expectations on state after a piece of code was executed
Sometimes it may be useful to assert that a certain state exists after some
piece of code is executed, regardless of whether this execution succeeds., (*115)
expect(function() {
// some piece of code here
})
->after(SomeClass::$value, equals(303));
It is possible to combine this with expectations on whether an exception is
thrown or not:, (*116)
expect(function() {
// some piece of code here
})
->doesNotThrow()
->after(SomeClass::$value, equals(303));
expect(function() {
// some piece of code here
})
->throws(SomeException::class)
->after(SomeClass::$value, equals(303));
Verify output of a function or method
Available since release 2.1.0, (*117)
When a function or method utilizes echo it can be cumbersome to check if it
prints the correct output. For this, the outputOf() function was introduced:, (*118)
outputOf(
function() { echo 'Hello you!'; },
equals('Hello world!')
);
The first parameter is a callable which prints some output, the second is any
predicate which will than be applied to the output. outputOf() takes care of
enabling and disabling output buffering to catch the output., (*119)
FAQ
How can I access a property of a class or object for the assertions?
Unlike PHPUnit bovigo/assert does not provide means to assert that a property
of a class fullfills a certain constraint. If the property is public you can
pass it directly into the assertThat() function as a value. In any other case
bovigo/assert does not support accessing protected or private properties.
There's a reason why they are protected or private, and a test should only be
against the public API of a class, not against their inner workings., (*120)
Wallogit.com
