Expectations

Overview

Note: The Expectation API can be used in regular PHPUnit projects. For that, you just have to run the following command in your terminal: composer require pestphp/pest-plugin-expectations --dev.

In addition to assertions, Pest offers you a set of expectations. These functions let you test your values against certain conditions. This API is inspired by Jest. Expectations also allow you to write your tests like you would a natural sentence:

test('expect true to be true', function () {
  // assertion
  $this->assertTrue(true);

  // expectation
  expect(true)->toBe(true);
});

expect($value)

Start the expectation by passing your value to this function. Then, you can chain your check(s):

expect($value)->// chain your checks here

Available Expectations

and($value)

Pass a new value to the and function to chain multiple expectations in a single test:

expect($id)->toBe(14)->and($name)->toBe('Nuno');

not

Use the not modifier before a check to invert it:

expect($id)->not->toBe(14);

toBe()

Asserts that two variables have the same type and value. Used on objects, it asserts that the two variables reference the same object:

expect($color)->toBe('pink');

expect($user)->toBe($user);

toBeEmpty()

Asserts that the value is empty:

expect($lastSeen)->toBeEmpty();

toBeTrue()

Asserts that the value is true:

expect($published)->toBeTrue();

toBeFalse()

Asserts that the value is false:

expect($archived)->toBeFalse();

toBeGreaterThan($expected)

Asserts that the value is greater than the expected one:

expect($age)->toBeGreaterThan(20);

toBeGreaterThanOrEqual($expected)

Asserts that the value is greater than or equal to the expected one:

expect($age)->toBeGreaterThanOrEqual(21);

toBeLessThan($expected)

Asserts that the value is lesser than the expected one:

expect($count)->toBeLessThan(3);

toBeLessThanOrEqual($expected)

Asserts that the value is lesser than or equal to the expected one:

expect($count)->toBeLessThanOrEqual(2);

toContain($needle)

Asserts that the needle is an element of the value:

expect($content)->toContain('Hello World');

toHaveCount(int $count)

Asserts that the $count matches the number of elements of $value:

expect($dozen)->toHaveCount(12);

toHaveProperty(string $name, $value = null)

Asserts that the $value contains the property $name:

expect($user)->toHaveProperty('name');
expect($user)->toHaveProperty('name', 'Nuno');

toMatchArray($array)

Asserts that the $value array matches the given $array subset.

$user = [
    'id'    => 1,
    'name'  => 'Nuno',
    'email' => 'enunomaduro@gmail.com',
];

expect($user)->toMatchArray([
    'email' => 'enunomaduro@gmail.com',
    'name' => 'Nuno'
]);

toMatchObject($object)

Asserts that the $value object matches a subsetof the properties of an given $object:

$user = new stdClass();
$user->id = 1;
$user->email = 'enunomaduro@gmail.com';
$user->name = 'Nuno';

expect($user)->toMatchObject([
    'email' => 'enunomaduro@gmail.com',
    'name' => 'Nuno'
]);

toEqual($expected)

Asserts that two variables have the same value.

expect($title)->toEqual('Hello World');

toEqualCanonicalizing($expected)

Asserts that two variables have the same value. The contents of $value and $expected are canonicalized before they are compared. For instance, when the two variables are arrays, then these arrays are sorted before they are compared. When they are objects, each object is converted to an array containing all private, protected, and public attributes.

expect([4, 2, 1])->toEqualCanonicalizing([2, 4, 1]);

// this is the equivalent of:
expect([1, 2, 4])->toEqual([1, 2, 4]);

toEqualWithDelta($expected, float $delta)

Asserts that the absolute difference between $value and $expected is lower than $delta:

// Pass
expect(14)->toEqualWithDelta(10, 5);

// Fail
expect(14)->toEqualWithDelta(10, 0.1);

toBeInfinite()

Asserts that the value is infinite:

expect($universe)->toBeInfinite();

toBeInstanceOf($class)

Asserts that the value is an instance of $class:

expect($user)->toBeInstanceOf(User::class);

toBeArray()

Asserts that the value is an array:

expect($vegetables)->toBeArray();

toBeBool()

Asserts that the value is of type bool:

expect($isActive)->toBeBool();

toBeCallable()

Asserts that the value is of type callable:

expect($controller)->toBeCallable();

toBeFloat()

Asserts that the value is of type float:

expect($height)->toBeFloat();

toBeInt()

Asserts that the value is of type integer:

expect($count)->toBeInt();

toBeIterable()

Asserts that the value is of type iterable:

expect($value)->toBeIterable();

toBeNumeric()

Asserts that the value is of type numeric:

expect($age)->toBeNumeric();

toBeObject()

Asserts that the value is of type object:

expect($post)->toBeObject();

toBeResource()

Asserts that the value is of type resource:

expect($resource)->toBeResource();

toBeScalar()

Asserts that the value is of type scalar:

expect($scalar)->toBeScalar();

toBeString()

Asserts that the value is of type string:

expect($string)->toBeString();

toBeJson()

Asserts that the value is a JSON string:

expect('{"hello":"world"}')->toBeJson();

toBeNan()

Asserts that the value is not a number (NaN):

expect($nan)->toBeNan();

toBeNull()

Asserts that the value is null:

expect(null)->toBeNull();

toHaveKey(string $key)

Asserts that the value array contains the provided $key:

expect($array)->toHaveKey('key-a');

toHaveKeys(array $keys)

Asserts that the value array contains the provided $keys:

expect($array)->toHaveKeys(['key-a', 'key-b']);

toBeDirectory()

Asserts that the value is a directory:

expect($dir)->toBeDirectory();

toBeReadableDirectory()

Asserts that the value is a directory and is readable.

expect($dir)->toBeReadableDirectory();

toBeWritableDirectory()

Asserts that the value is a directory and is writable:

expect($dir)->toBeWritableDirectory();

toStartWith(string $expected)

Asserts that the value starts with the provided string:

expect($content)->toStartWith('Hello');

toMatch(string $expression)

Asserts that the value matches a regular expression:

expect('Hello World')->toMatch('/^hello wo.*$/i');

toEndWith(string $expected)

Asserts that the value ends with the provided string:

expect($content)->toEndWith('World');

toMatchConstraint(Constraint $constraint)

Asserts that the value matches a specified PHPUnit constraint:

use PHPUnit\Framework\Constraint\IsTrue;

expect(true)->toMatchConstraint(new IsTrue());

Asserts that the value matches a complex group of constraints:

use PHPUnit\Framework\Constraint\IsFalse;
use PHPUnit\Framework\Constraint\IsType;

expect(true)->toMatchConstraint(
    $this->logicalAnd(
         $this->logicalNot(new IsFalse()),
         new IsType(IsType::TYPE_BOOL)
    )
);

Asserts that the value matches a custom constraint:

expect('https://google.com')->toMatchConstraint(new IsValidUrlConstraint());
class IsValidUrlConstraint extends \PHPUnit\Framework\Constraint\Constraint
{
    public function toString()
    {
        return 'is a valid url';
    }
    protected function matches($other): bool
    {
        if (! is_string($other)) {
            return false;
        }
        return preg_match(
            Symfony\Component\Validator\Constraints\UrlValidator::PATTERN,
            $other
        ) > 0;
    }
}

Custom constraints should extend PHPUnit\Framework\Constraint\Constraint, and provide a matches() and toString() method, and optionally override the evaluate() method.

Custom Expectations

You can use expect()->extend() to add your own expectations to Pest. For example, let's say that you're testing a number utility library and you're frequently asserting that numbers appear within particular ranges of other numbers. You could abstract that into a toBeWithinRange expectation:

expect()->extend('toBeWithinRange', function ($min, $max) {
    return $this->toBeGreaterThanOrEqual($min)
                ->toBeLessThanOrEqual($max);
});

test('numeric ranges', function () {
    expect(100)->toBeWithinRange(90, 110);
});

Those custom expectations may be also placed in your tests/Pest.php file.

Next section: Setup And Teardown →