#Expectations

By setting expectations for your tests using the Pest expectation API, you can easily identify bugs and other issues in your code. This is because the API allows you to specify the expected outcome of a test, making it easy to detect any deviations from the expected behavior.

You can start the expectation by passing your value to the expect($value) function. The expect() function is used every time you want to test a value. You will rarely call expect() by itself. Instead, you will use expect() along with an "expectation" method to assert something about the value.

1test('sum', function () {
2    $value = sum(1, 2);
3 
4    expect($value)->toBe(3); // Assert that the value is 3...
5});

As demonstrated, the expect function in Pest allows you to chain multiple expectations together for a given $value. This means that you can perform as many checks as necessary in a single test by simply continuing to chain additional expectations.

1expect($value)
2    ->toBeInt()
3    ->toBe(3);

At any time, you may test the opposite of an expectation by prepending the not modifier to the expectation.

1expect($value)
2    ->toBeInt()
3    ->toBe(3)
4    ->not->toBeString() // Not to be string...
5    ->not->toBe(4); // Not to be 4...

With the Pest expectation API, you have access to an extensive collection of individual expectations that are designed to test various aspects of your code. Below is a comprehensive list of the available expectations.

In addition to the individual expectations available in Pest, the expectation API also provides several modifiers that allow you to further customize your tests. These modifiers can be used to create more complex expectations and to test multiple values at once. Here are some examples of the modifiers available in Pest:

---

#toBe()

This expectation ensures that both $value and $expected share the same type and value.

If used with objects, it ensures that both variables refer to the exact same object.

1expect(1)->toBe(1);
2expect('1')->not->toBe(1);
3expect(new StdClass())->not->toBe(new StdClass());

#toBeBetween()

This expectation ensures that $value is between 2 values. It works with int, float and DateTime.

1expect(2)->toBeBetween(1, 3);
2expect(1.5)->toBeBetween(1, 2);
3 
4$expectationDate = new DateTime('2023-09-22');
5$oldestDate = new DateTime('2023-09-21');
6$latestDate = new DateTime('2023-09-23');
7 
8expect($expectationDate)->toBeBetween($oldestDate, $latestDate);

#toBeEmpty()

This expectation ensures that $value is empty.

1expect('')->toBeEmpty();
2expect([])->toBeEmpty();
3expect(null)->toBeEmpty();

#toBeTrue()

This expectation ensures that $value is true.

1expect($isPublished)->toBeTrue();

#toBeTruthy()

This expectation ensures that $value is truthy.

1expect(1)->toBeTruthy();
2expect('1')->toBeTruthy();

#toBeFalse()

This expectation ensures that $value is false.

1expect($isPublished)->toBeFalse();

#toBeFalsy()

This expectation ensures that $value is falsy.

1expect(0)->toBeFalsy();
2expect('')->toBeFalsy();

#toBeGreaterThan($expected)

This expectation ensures that $value is greater than $expected.

1expect($count)->toBeGreaterThan(20);

#toBeGreaterThanOrEqual($expected)

This expectation ensures that $value is greater than or equal to $expected.

1expect($count)->toBeGreaterThanOrEqual(21);

#toBeLessThan($expected)

This expectation ensures that $value is lesser than $expected.

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

#toBeLessThanOrEqual($expected)

This expectation ensures that $value is lesser than or equal to $expected.

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

#toContain($needles)

This expectation ensures that all the given needles are elements of the $value.

1expect('Hello World')->toContain('Hello');
2expect('Pest: an elegant PHP Testing Framework')->toContain('Pest', 'PHP', 'Framework');
3expect([1, 2, 3, 4])->toContain(2, 4);

#toContainEqual($needles)

This expectation ensures that all the given needles are elements (in terms of equality) of the $value.

1expect([1, 2, 3])->toContainEqual('1');
2expect([1, 2, 3])->toContainEqual('1', '2');

#toContainOnlyInstancesOf($class)

This expectation ensures that $value contains only instances of $class.

1$dates = [new DateTime(), new DateTime()];
2 
3expect($dates)->toContainOnlyInstancesOf(DateTime::class);

#toHaveCount(int $count)

This expectation ensures that the $count provided matches the number of elements in an iterable $value.

1expect(['Nuno', 'Luke', 'Alex', 'Dan'])->toHaveCount(4);

#toHaveProperty(string $name, $value = null)

This expectation ensures that $value has a property named $name.

In addition, you can verify the actual value of a property by providing a second argument.

1expect($user)->toHaveProperty('name');
2expect($user)->toHaveProperty('name', 'Nuno');
3expect($user)->toHaveProperty('is_active', 'true');

#toHaveProperties(iterable $name)

This expectation ensures that $value has property names matching all the names contained in $names.

1expect($user)->toHaveProperties(['name', 'email']);

In addition, you can verify the name and value of multiple properties using an associative array.

1expect($user)->toHaveProperties([
2    'name' => 'Nuno',
3    'email' => '[email protected]'
4]);

#toMatchArray($array)

This expectation ensures that the $value array matches the given $array subset.

 1$user = [
 2    'id'    => 1,
 3    'name'  => 'Nuno',
 4    'email' => '[email protected]',
 5    'is_active' => true,
 6];
 7 
 8expect($user)->toMatchArray([
 9    'email' => '[email protected]',
10    'name' => 'Nuno'
11]);

#toMatchObject($object)

This expectation ensures that the $value object matches a subset of the properties of a given $object.

1$user = new stdClass();
2$user->id = 1;
3$user->email = '[email protected]';
4$user->name = 'Nuno';
5 
6expect($user)->toMatchObject([
7    'email' => '[email protected]',
8    'name' => 'Nuno'
9]);

#toEqual($expected)

This expectation ensures that $value and $expected have the same value.

1expect($title)->toEqual('Hello World');
2expect('1')->toEqual(1);
3expect(new StdClass())->toEqual(new StdClass());

#toEqualCanonicalizing($expected)

This expectation ensures that $value and $expected have the same values, no matter what order the elements are given in.

1$usersAsc = ['Dan', 'Fabio', 'Nuno'];
2$usersDesc = ['Nuno', 'Fabio', 'Dan'];
3 
4expect($usersAsc)->toEqualCanonicalizing($usersDesc);
5expect($usersAsc)->not->toEqual($usersDesc);

#toEqualWithDelta($expected, float $delta)

This expectation ensures that the absolute difference between $value and $expected is lower than $delta.

1expect($durationInMinutes)->toEqualWithDelta(10, 5); //duration of 10 minutes with 5 minutes tolerance
2 
3expect(14)->toEqualWithDelta(10, 5);    // Pass
4expect(14)->toEqualWithDelta(10, 0.1); // Fail

#toBeIn()

This expectation ensures that $value is one of the given values.

1expect($newUser->status)->toBeIn(['pending', 'new', 'active']);

#toBeInfinite()

This expectation ensures that $value is infinite.

1expect(log(0))->toBeInfinite();

#toBeInstanceOf($class)

This expectation ensures that $value is an instance of $class.

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

#toBeArray()

This expectation ensures that $value is an array.

1expect(['Pest','PHP','Laravel'])->toBeArray();

#toBeBool()

This expectation ensures that $value is of type bool.

1expect($isActive)->toBeBool();

#toBeCallable()

This expectation ensures that $value is of type callable.

1$myFunction = function () {};
2 
3expect($myFunction)->toBeCallable();

#toBeFile()

This expectation ensures that the string $value is an existing file.

1expect('/tmp/some-file.tmp')->toBeFile();

#toBeFloat()

This expectation ensures that $value is of type float.

1expect($height)->toBeFloat();

#toBeInt()

This expectation ensures that $value is of type integer.

1expect($count)->toBeInt();

#toBeIterable()

This expectation ensures that $value is of type iterable.

1expect($array)->toBeIterable();

#toBeNumeric()

This expectation ensures that $value is of type numeric.

1expect($age)->toBeNumeric();
2expect(10)->toBeNumeric();
3expect('10')->toBeNumeric();

#toBeDigits()

This expectation ensures that $value contains only digits.

1expect($year)->toBeDigits();
2expect(15)->toBeDigits();
3expect('15')->toBeDigits();
4expect(0.123)->not->toBeDigits();
5expect('0.123')->not->toBeDigits();

#toBeObject()

This expectation ensures that $value is of type object.

1$object = new stdClass();
2 
3expect($object)->toBeObject();

#toBeResource()

This expectation ensures that $value is of type resource.

1$handle = fopen('php://memory', 'r+');
2 
3expect($handle)->toBeResource();

#toBeScalar()

This expectation ensures that $value is of type scalar.

1expect('1')->toBeScalar();
2expect(1)->toBeScalar();
3expect(1.0)->toBeScalar();
4expect(true)->toBeScalar();
5expect([1, '1'])->not->toBeScalar();

#toBeString()

This expectation ensures that $value is of type string.

1expect($string)->toBeString();

#toBeJson()

This expectation ensures that $value is a JSON string.

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

#toBeNan()

This expectation ensures that $value is not a number (NaN).

1expect(sqrt(-1))->toBeNan();

#toBeNull()

This expectation ensures that $value is null.

1expect(null)->toBeNull();

#toHaveKey(string $key)

This expectation ensures that $value contains the provided $key.

1expect(['name' => 'Nuno', 'surname' => 'Maduro'])->toHaveKey('name');
2expect(['name' => 'Nuno', 'surname' => 'Maduro'])->toHaveKey('name', 'Nuno');
3expect(['user' => ['name' => 'Nuno', 'surname' => 'Maduro']])->toHaveKey('user.name');
4expect(['user' => ['name' => 'Nuno', 'surname' => 'Maduro']])->toHaveKey('user.name', 'Nuno');

#toHaveKeys(array $keys)

This expectation ensures that $value contains the provided $keys.

1expect(['id' => 1, 'name' => 'Nuno'])->toHaveKeys(['id', 'name']);
2expect(['message' => ['from' => 'Nuno', 'to' => 'Luke'] ])->toHaveKeys(['message.from', 'message.to']);

#toHaveLength(int $number)

This expectation ensures that the provided $number matches the length of a string $value or the number of elements in an iterable $value.

1expect('Pest')->toHaveLength(4);
2expect(['Nuno', 'Maduro'])->toHaveLength(2);

#toBeDirectory()

This expectation ensures that the string $value is a directory.

1expect('/tmp')->toBeDirectory();

#toBeReadableDirectory()

This expectation ensures that the string $value is a directory and that it is readable.

1expect('/tmp')->toBeReadableDirectory();

#toBeReadableFile()

This expectation ensures that the string $value is a file and that it is readable.

1expect('/tmp/some-file.tmp')->toBeReadableFile();

#toBeWritableDirectory()

This expectation ensures that the string $value is a directory and that it is writable.

1expect('/tmp')->toBeWritableDirectory();

#toBeWritableFile()

This expectation ensures that the string $value is a file and that it is writable.

1expect('/tmp/some-file.tmp')->toBeWritableFile();

#toStartWith(string $expected)

This expectation ensures that $value starts with the provided string.

1expect('Hello World')->toStartWith('Hello');

#toThrow()

This expectation ensures that a closure throws a specific exception class, exception message, or both.

1expect(fn() => throw new Exception('Something happened.'))->toThrow(Exception::class);
2expect(fn() => throw new Exception('Something happened.'))->toThrow('Something happened.');
3expect(fn() => throw new Exception('Something happened.'))->toThrow(Exception::class, 'Something happened.');
4expect(fn() => throw new Exception('Something happened.'))->toThrow(new Exception('Something happened.'));

#toMatch(string $expression)

This expectation ensures that $value matches a regular expression.

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

#toEndWith(string $expected)

This expectation ensures that $value ends with the provided string.

1expect('Hello World')->toEndWith('World');

#toMatchConstraint(Constraint $constraint)

This expectation ensures that $value matches a specified PHPUnit constraint.

1use PHPUnit\Framework\Constraint\IsTrue;
2 
3expect(true)->toMatchConstraint(new IsTrue());

#toBeUppercase(string $expected)

This expectation ensures that $value is uppercase.

1expect('PESTPHP')->toBeUppercase();

#toBeLowercase(string $expected)

This expectation ensures that $value is lowercase.

1expect('pestphp')->toBeLowercase();

#toBeAlpha(string $expected)

This expectation ensures that $value only contains alpha characters.

1expect('pestphp')->toBeAlpha();

#toBeAlphaNumeric(string $expected)

This expectation ensures that $value only contains alphanumeric characters.

1expect('pestPHP123')->toBeAlphaNumeric();

#toBeSnakeCase()

This expectation ensures that $value only contains string in snake_case format.

1expect('snake_case')->toBeSnakeCase();

#toBeKebabCase()

This expectation ensures that $value only contains string in kebab-case format.

1expect('kebab-case')->toBeKebabCase();

#toBeCamelCase()

This expectation ensures that $value only contains string in camelCase format.

1expect('camelCase')->toBeCamelCase();

#toBeStudlyCase()

This expectation ensures that $value only contains string in StudlyCase format.

1expect('StudlyCase')->toBeStudlyCase();

#toHaveSnakeCaseKeys()

This expectation ensures that $value only contains an array with keys in snake_case format.

1expect(['snake_case' => 'abc123'])->toHaveSnakeCaseKeys();

#toHaveKebabCaseKeys()

This expectation ensures that $value only contains an array with keys in kebab-case format.

1expect(['kebab-case' => 'abc123'])->toHaveKebabCaseKeys();

#toHaveCamelCaseKeys()

This expectation ensures that $value only contains an array with keys in camelCase format.

1expect(['camelCase' => 'abc123'])->toHaveCamelCaseKeys();

#toHaveStudlyCaseKeys()

This expectation ensures that $value only contains an array with keys in StudlyCase format.

1expect(['StudlyCase' => 'abc123'])->toHaveStudlyCaseKeys();

#toHaveSameSize()

This expectation ensures that the size of $value and the provided iterable are the same.

1expect(['foo', 'bar'])->toHaveSameSize(['baz', 'bazz']);

#toBeUrl()

This expectation ensures that $value is a URL.

1expect('https://pestphp.com/')->toBeUrl();

#toBeUuid()

This expectation ensures that $value is an UUID.

1expect('ca0a8228-cdf6-41db-b34b-c2f31485796c')->toBeUuid();

---

#and($value)

The and() modifier allows you to pass a new $value, enabling you to chain multiple expectations in a single test.

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

#dd()

The dd() modifier

Use the dd() modifier allows you to dump the current expectation $value and stop the code execution. This can be useful for debugging by allowing you to inspect the current state of the $value at a particular point in your test.

1expect(14)->dd(); // 14
2expect([1, 2])->sequence(
3    fn ($number) => $number->toBe(1),
4    fn ($number) => $number->dd(), // 2
5);

#ddWhen($condition)

Use the ddWhen() modifier allows you to dump the current expectation $value and stop the code execution when the given $condition is truthy.

1expect([1, 2])->each(
2    fn ($number) => $number->ddWhen(fn (int $number) => $number === 2) // 2
3);

#ddUnless($condition)

Use the ddUnless() modifier allows you to dump the current expectation $value and stop the code execution when the given $condition is falsy.

1expect([1, 2])->each(
2    fn ($number) => $number->ddUnless(fn (int $number) => $number === 1) // 2
3);

#each()

The each() modifier allows you to create an expectation on each item of the given iterable. It works by iterating over the iterable and applying the expectation to each item.

1expect([1, 2, 3])->each->toBeInt();
2expect([1, 2, 3])->each->not->toBeString();
3expect([1, 2, 3])->each(fn ($number) => $number->toBeLessThan(4));

#json()

The json() modifier decodes the current expectation $value from JSON to an array.

1expect('{"name":"Nuno","credit":1000.00}')
2    ->json()
3    ->toHaveCount(2)
4    ->name->toBe('Nuno')
5    ->credit->toBeFloat();
6 
7expect('not-a-json')->json(); //Fails

#match()

The match() modifier executes the closure associated with the first array key that matches the value of the first argument given to the method.

1expect($user->miles)
2    ->match($user->status, [
3        'new'  => fn ($userMiles) => $userMiles->ToBe(0),
4        'gold'  => fn ($userMiles) => $userMiles->toBeGreaterThan(500),
5        'platinum' => fn ($userMiles) => $userMiles->toBeGreaterThan(1000),
6    ]);

To check if the expected value is equal to the value associated with the matching key, you can directly pass the expected value as the array value instead of using a closure.

1expect($user->default_language)
2    ->match($user->country, [
3        'PT' => 'Português',
4        'US' => 'English',
5        'TR' => 'Türkçe',
6    ]);

#not

The not modifier allows to invert the subsequent expectation.

1expect(10)->not->toBeGreaterThan(100);
2expect(true)->not->toBeFalse();

#ray()

The ray() modifier allows you to debug the current $value with myray.app.

1expect(14)->ray(); // 14
2expect([1, 2])->sequence(
3    fn ($number) => $number->toBe(1),
4    fn ($number) => $number->ray(), // 2
5);

#sequence()

The sequence() modifier allows you to specify a sequential set of expectations for a single iterable.

1expect([1, 2, 3])->sequence(
2    fn ($number) => $number->toBe(1),
3    fn ($number) => $number->toBe(2),
4    fn ($number) => $number->toBe(3),
5);

The sequence() modifier can also be used with associative iterables. Each closure in the sequence will receive two arguments: the first argument being the expectation for the value and the second argument being the expectation for the key.

1expect(['hello' => 'world', 'foo' => 'bar', 'john' => 'doe'])->sequence(
2    fn ($value, $key) => $value->toEqual('world'),
3    fn ($value, $key) => $key->toEqual('foo'),
4    fn ($value, $key) => $value->toBeString(),
5);

The sequence() modifier can also be used to check if each value in the iterable matches a set of expected values. In this case, you can pass the expected values directly to the sequence() method instead of using closures.

1expect(['foo', 'bar', 'baz'])->sequence('foo', 'bar', 'baz');

#when()

The when() modifier runs the provided callback when the first argument passed to the method evaluates to true.

1expect($user)
2    ->when($user->is_verified === true, fn ($user) => $user->daily_limit->toBeGreaterThan(10))
3    ->email->not->toBeEmpty();

#unless()

The unless() modifier runs the provided callback when the first argument passed to the method evaluates to false.

1expect($user)
2    ->unless($user->is_verified === true, fn ($user) => $user->daily_limit->toBe(10))
3    ->email->not->toBeEmpty();

---

After learning how to write expectations, the next section in the documentation, "Hooks" covers useful functions like "beforeEach" and "afterEach" that can be used to set up preconditions and cleanup actions for your tests: Hooks →