Expectations

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);
});

Here is the full list of expectations available in Pest:

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

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');

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();

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');

toEndWith(string $expected)

Asserts that the value ends with the provided string:

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

toMatch(string $expression)

Asserts that the value matches a regular expression:

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

toMatchConstraint(Constraint $constraint)

Asserts that the value matches a specificed 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.

Next section: Setup And Teardown →