xp-forge / assert
Assertions for the XP Framework
Requires
- php: >=7.0.0
- xp-framework/core: ^11.0 | ^10.0 | ^9.0 | ^8.0 | ^7.0 | ^6.0
Requires (Dev)
- xp-framework/unittest: ^11.0 | ^10.0 | ^9.0 | ^8.0 | ^7.0 | ^6.9
README
Flexible assertions on top of the XP Framework's unittest package.
Example
use unittest\assert\{Assert, All}; class ExampleTest { #[@test] public function succeeds() { Assert::that(['The Dude'])->hasSize(1)->contains('The Dude'); } #[@test] public function fails() { All::of(function() { Assert::that('localhost')->startsWith('www'); Assert::that('example.com')->endsWith('.org'); }); } }
Running this test will yield one succeeded and one failed test. The difference to regular unittest messages is the more readable format.
On top of that, this library's assertions are also more flexible: As seen in the above case, we wrapped the chain in an All::of()
call which will yield all failed assertions, not just the first one.
$ xp test ExampleTest.class.php [.F] F unittest.TestAssertionFailed(test= ExampleTest::fails, time= 0.002 seconds) { unittest.AssertionFailedError{ The following 2 assertions have failures: 1: unittest.AssertionFailedError{ Failed to verify that "localhost" starts with "www" } 2: unittest.AssertionFailedError{ Failed to verify that "example.com" ends with ".org" } } at unittest.assert.All::of() [line 17 of ExampleTest.class.php] at ExampleTest::fails() [line 0 of StackTraceElement.class.php] at ReflectionMethod::invokeArgs() [line 90 of Method.class.php] at lang.reflect.Method::invoke() [line 334 of TestSuite.class.php] at unittest.TestSuite::runInternal() [line 565 of TestSuite.class.php] at unittest.TestSuite::run() [line 369 of Runner.class.php] at xp.unittest.Runner::run() [line 380 of Runner.class.php] at xp.unittest.Runner::main() [line 281 of class-main.php] } ✗: 2/2 run (0 skipped), 1 succeeded, 1 failed Memory used: 1610.91 kB (1710.45 kB peak) Time taken: 0.005 seconds
Assertions
Generic assertions:
is(unittest.assert.Condition $condition)
- Asserts a given condition matchesisNot(unittest.assert.Condition $condition)
- Asserts a given condition does not matchisEqualTo(var $compare)
- Asserts the value is equal to a given comparisonisNotEqualTo(var $compare)
- Asserts the value is not equal to a given comparisonisNull()
- Asserts the value is nullisTrue()
- Asserts the value is trueisFalse()
- Asserts the value is falseisIn(var $enumerable)
- Asserts the value is in a given enumerableisNotIn(var $enumerable)
- Asserts the value is not in a given enumerableisInstanceOf(string|lang.Type $type)
- Asserts the value is of a given type
With special meanings dependant on type:
isEmpty()
- Asserts a string, array or map is emptyhasSize(int $size)
- Asserts a string length, array or map sizestartsWith(var $element)
- Asserts a string or array contains the given element at its startendsWith(var $element)
- Asserts a string or array contains the given element at its endcontains(var $element)
- Asserts a string, array or map contains a given elementdoesNotContain(var $element)
- Asserts a string, array or map does not contain a given element
For numbers:
isGreaterThan(int|double $comparison)
- Asserts value > comparisonisLessThan(int|double $comparison)
- Asserts value < comparisonisBetween(int|double $start, int|double $end)
- Asserts value >= start && value <= endisCloseTo(int|double $comparison, int|double $tolerance)
- Asserts value is close (defined per tolerance)
Transformations
Values can be transformed prior to invoking assertions on them.
Extraction works directly on instances (using properties and get
-prefixed as well as plain getters):
$tim= new Person(6100, 'Tim Tailor'); Assert::that($tim)->extracting('name')->isEqualTo('Tim Tailor');
You can also pass a closure to control more precisely what's extracted:
$tim= new Person(6100, 'Tim Tailor'); Assert::that($tim)->extracting(function($p) { return $p->name(); })->isEqualTo('Tim Tailor');
For maps, extraction accesses the elements by their string keys:
$person= ['id' => 6100, 'name' => 'Test', 'age' => 42]; Assert::that($person)->extracting('age')->isEqualTo(42);
Passing an array to extracting()
will extract multiple elements and return them in an array in the order they're passed:
$person= ['id' => 6100, 'name' => 'Test', 'age' => 42]; Assert::that($person)->extracting(['name', 'age'])->isEqualTo(['Test', 42]);
Passing maps to extracting()
will extract multiple elements and return them in a map.
$person= ['id' => 6100, 'name' => 'Test', 'age' => 42]; Assert::that($person)->extracting(['identifier' => 'id'])->isEqualTo(['identifier' => 6100]);
For arrays, the extracting()
method applies the extraction on every element:
$people= [new Person(1, 'Queen'), new Person(2, 'King')]; Assert::that($people)->extracting('name')->isEqualTo(['Queen', 'King']);