k2gl/phpunit-fluent-assertions

Improves test code readability.

12.0.0 2025-05-01 23:45 UTC

Requires

• php: >=8.1
• phpunit/phpunit: ^9|^10|^11|^12

MIT

• Nickolay Harin

• testing
• phpunit
• xunit

README

This library is insperated by Vladimir Khorikov, the author of Unit Testing: Principles, Patterns and Practices and makes checks in tests more readable.

Installation

You can add this library as a local, per-project dependency to your project using Composer:

composer require --dev k2gl/phpunit-fluent-assertions

Usage

Write tests as usual, just use fluent assertions short aliases check($x)->...;, expect($x)->...; or fact($x)->...; instead of self::assert...($x, $y).

// arrange
$user = UserFactory::createOne([
    'phone' => $phoneBefore = faker()->e164PhoneNumber;
]);

// act
$user->setPhone(
    $phoneAfter = faker()->e164PhoneNumber
);

// assert

// traditional PHPUnit assertions
self::assertSame(expected: $phoneAfter, actual: $user->getPhone());
self::assertNotSame(expected: $phoneBefore, actual: $user->getPhone());

// fluent assertions
fact($user->getPhone())
    ->is($phoneAfter)
    ->equals($phoneAfter)
    ->not($phoneBefore)
    ->true()
    ->notTrue()
    ->false()
    ->notFalse()
    ->null()
    ->notNull()
    ->matchesRegularExpression('#^\d+$#')
    ->notMatchesRegularExpression('#^\D+$#')
    ->containsString('alpha')
    ->notContainsString('alpha')
    ->containsStringIgnoringCase('beta')
    ->notContainsStringIgnoringCase('beta')
    ->count(5)
    ->notCount(5)
    ->arrayHasKey('echo')
    ->arrayNotHasKey('echo')
    ->instanceOf(UserFactory::class)
    ->notInstanceOf(UserFactory::class)
    ->ulid() // Universally Unique Lexicographically Sortable Identifier https://github.com/ulid/spec
    ...
    ;

fact(
    [
        'a' => ['any' => 'thing'],
        'b' => ['any' => 'thing', 'type' => 'candy', 'color' => 'green'],
        'c' => ['miss' => 'kiss', 'foo' => 'bar', 'any' => 'thing'],
        'd' => ['any' => 'thing'],
    ]
)->arrayContainsAssociativeArray(
    [
        'c' => ['foo' => 'bar', 'miss' => 'kiss'],
        'b' => ['color' => 'green'],
    ]
); // true

Pull requests are always welcome

Collaborate with pull requests