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.
-
toBe()
-
toBeArray()
-
toBeBetween()
-
toBeEmpty()
-
toBeTrue()
-
toBeTruthy()
-
toBeFalse()
-
toBeFalsy()
-
toBeGreaterThan()
-
toBeGreaterThanOrEqual()
-
toBeLessThan()
-
toBeLessThanOrEqual()
-
toContain()
-
toContainEqual()
-
toContainOnlyInstancesOf()
-
toHaveCount()
-
toHaveProperty()
-
toHaveProperties()
-
toMatchArray()
-
toMatchObject()
-
toEqual()
-
toEqualCanonicalizing()
-
toEqualWithDelta()
-
toBeIn()
-
toBeInfinite()
-
toBeInstanceOf()
-
toBeBool()
-
toBeCallable()
-
toBeFile()
-
toBeFloat()
-
toBeInt()
-
toBeIterable()
-
toBeNumeric()
-
toBeDigits()
-
toBeObject()
-
toBeResource()
-
toBeScalar()
-
toBeString()
-
toBeJson()
-
toBeNan()
-
toBeNull()
-
toHaveKey()
-
toHaveKeys()
-
toHaveLength()
-
toBeReadableDirectory()
-
toBeReadableFile()
-
toBeWritableDirectory()
-
toBeWritableFile()
-
toStartWith()
-
toThrow()
-
toEndWith()
-
toMatch()
-
toMatchConstraint()
-
toBeUppercase()
-
toBeLowercase()
-
toBeAlpha()
-
toBeAlphaNumeric()
-
toBeSnakeCase()
-
toBeKebabCase()
-
toBeCamelCase()
-
toBeStudlyCase()
-
toHaveSnakeCaseKeys()
-
toHaveKebabCaseKeys()
-
toHaveCamelCaseKeys()
-
toHaveStudlyCaseKeys()
-
toHaveSameSize()
-
toBeUrl()
-
toBeUuid()
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' => 'enunomaduro@gmail.com'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' => 'enunomaduro@gmail.com', 5 'is_active' => true, 6]; 7 8expect($user)->toMatchArray([ 9 'email' => 'enunomaduro@gmail.com',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 = 'enunomaduro@gmail.com';4$user->name = 'Nuno';5 6expect($user)->toMatchObject([7 'email' => 'enunomaduro@gmail.com',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 tolerance2 3expect(14)->toEqualWithDelta(10, 5); // Pass4expect(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();
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(); // 142expect([1, 2])->sequence(3 fn ($number) => $number->toBe(1),4 fn ($number) => $number->dd(), // 25);
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) // 23);
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) // 23);
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(); // 142expect([1, 2])->sequence(3 fn ($number) => $number->toBe(1),4 fn ($number) => $number->ray(), // 25);
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 →