README

Assertion library for PHPUnit or Codeception powered by Symfony Expression Language.

Pitch

This tiny library helps you to create domain-specific assertions in tests:

Instead of:

$this->assertTrue($user->isValid(), 'user is valid');

use

$this->assertUserIsValid($user);

Why?

See how test fails in first example:

user is valid
Failed asserting that false is true.

And how test fails in second example:

Failed asserting that `user.isValid()`.
[user]: User Object &000000005689696e000000004066036e (
    'role' => 'guest'
)

What makes more sense to you? In second example you get the business logic behind the assertion as well as values passed into it. That's why if you have business logic in your project domain-assert is your choice.

How To Use It

Install this package:

composer require codeception/domain-assert --dev

Create a trait with a custom assertion. We recommend using traits as you can reuse them accross different test cases.

use Codeception\DomainRule;

trait CustomAssertion
{
    public function assertValidUser(User $user)
    {
        $this->assertThat(
            ['user' => $user], 
            new DomainRule('user and user.isValid()')
        );
    }
}

In this example we check that $user exists and $user->isValid() return true;

That's all! Now inject this trait to TestCases and use it.

class UserTest extends \PHPUnit\Framework\TestCase
{
    use CustomAssertion;
}

Defining Business Rules

This library uses Expression Language to define domain rules for assertions.

Let's define a rule to check if we have enough products in the stock:

stock and product.getStock() == stock and product.getAmount() > amount

We have 3 items here: product, stock, and amount which is a number of items we need. Let's create assertion according to this rule:

public function assertEnoughProductsInStock(Stock stock, Product product, amount)
{
    $this->assertThat([
            'product' => $product,
            'stock' => $stock, 
            'amount' => $amount
        ], 
        new DomainRule('stock and product.getStock() == stock and product.getAmount() > amount')
    );
}

Now it can be used inside your tests:

$product = new Product('iPhone');
$stock->addProduct($product);
$stock->addProduct($product);
$stock->addProduct($product);
$this->assertEnoughProductsInStock($stock, $product, 2);

Advanced Concepts

Instead of $this->assertThat you can call static version of this method: PHPUnit\Framework\Assert::assertThat
Codeception\DomainRule extends PHPUnit\Framework\Constraint.
Codeception\DomainRule uses Symfony\Component\ExpressionLanguage\ExpressionLanguage
Expression Language can be extended by calling $domainRule->getLanguage()
assertThat can receive first parameter as scalar value. In this case it will be treated as expected inside an expression:

public function assertIsGreaterThanMinimal()
{
    $this->assertThat(
        $minimalPrice,
        new DomainRule('expected > 1000')
    );    
}

codeception / domain-assert

Maintainers

Details