PHPackages                             spatie/pest-expectations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. spatie/pest-expectations

ActiveLibrary[Testing & Quality](/categories/testing)

spatie/pest-expectations
========================

A collection of handy custom Pest customisations

1.14.0(4mo ago)79127.8k—2.8%49MITPHPPHP ^8.2CI passing

Since Jan 15Pushed 1w ago3 watchersCompare

[ Source](https://github.com/spatie/pest-expectations)[ Packagist](https://packagist.org/packages/spatie/pest-expectations)[ Docs](https://github.com/spatie/pest-expectations)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/spatie-pest-expectations/feed)WikiDiscussions main Synced 4d ago

READMEChangelog (10)Dependencies (7)Versions (24)Used By (9)

A collection of handy custom Pest customizations
================================================

[](#a-collection-of-handy-custom-pest-customizations)

[![Latest Version on Packagist](https://camo.githubusercontent.com/517036a19a888637e834687b81c73302f954448584a7cc45d40d3fb1fe247751/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f706573742d6578706563746174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pest-expectations)[![Tests](https://github.com/spatie/pest-expectations/actions/workflows/run-tests.yml/badge.svg)](https://github.com/spatie/pest-expectations/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/9868a4226b43dfb00edd32d1c46b4d09604f9732ffaae985d9df3120d37f220c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f706573742d6578706563746174696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pest-expectations)

This repo contains custom expectations to be used in a [Pest](https://pestphp.com) test suite.

It also contains various helpers to make testing with Pest easier. Imagine, you only want to run a test on GitHub Actions. You can use the `whenGitHubActions` helper to do so.

```
it('can only run well on github actions', function () {
    // your test
})->whenGitHubActions();
```

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/1e5dbe052ffe9142df6ae52e3f304f095b665b0216340abed7ca81b742c01384/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f706573742d6578706563746174696f6e732e6a70673f743d31)](https://spatie.be/github-ad-click/pest-expectations)

We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require spatie/pest-expectations
```

Usage
-----

[](#usage)

Once installed, you can use the [custom expectations](#expectations) and [helpers](#helpers) provided by this package.

### Expectations

[](#expectations)

#### toPassWith

[](#topasswith)

This expectation can be used to test if [an invokable validation rule](https://laravel.com/docs/master/validation#using-rule-objects) works correctly.

In this example, the `$value` will be given to `YourValidationRule`. The expectation will pass if your rule passed for the given value.

```
expect(new YourValidationRule())->toPassWith($value);
```

You can expect the your validation not to pass for the given value, by using Pest's `not()`.

```
expect(new YourValidationRule()->not()->toPassWith($value);
```

#### toFailWith

[](#tofailwith)

This expectation can be used to test if [an invokable validation rule](https://laravel.com/docs/master/validation#using-rule-objects) did not pass for a given value.

In this example, the `$value` will be given to `YourValidationRule`. The expectation will pass if your rule did not pass for the given value.

```
expect(new YourValidationRule())->toFailWith($value);
```

Optionally, you can also pass a message as the second argument. The expectation will pass is the validation rule return the given `$message`.

```
expect(new YourValidationRule())->toFailWith($value, 'This value is not valid.');
```

#### toBeModel

[](#tobemodel)

Expect that a value is a model an equal to the passed model.

```
expect($model)->toBeModel($anotherModel);
```

The expectation will only pass if both models are Eloquent models of the same class, with the same key.

#### toBeArrayOf

[](#tobearrayof)

Expect that a value is an array of the specified value.

```
expect(User::all())->toBeArrayOf(User::class);
```

The specified value may be a class name or a class instance, or one of the following string values:

- `'string'`
- `'int'`
- `'float'`
- `'bool'`
- `'scalar'`
- `'array'`
- `'object'`
- `'null'`

```
expect([1, 2])->toBeArrayOf('int');
expect([true, false])->toBeArrayOf('bool');
expect(['foo', 1, false])->toBeArrayOf('scalar');
```

#### toBeScheduled

[](#tobescheduled)

Expect that a value is a scheduled job, command or invokable class. The `timezone` parameter, if passed, will also check that the specified timezone was defined.

```
expect(MyJob::class)->toBeScheduled('0 * * * *', timezone: 'Europe/Paris');
```

Optionally, you may pass a callback that accepts an `Illuminate\Console\Scheduling\Event` or `Illuminate\Console\Scheduling\CallbackEvent` instance, so you can run any assertion needed:

```
expect(MyArtisanCommand::class)->toBeScheduled(function (Event $event) {
    expect($event->getExpression())->toBe('0 0 * * *');
    expect($event->getSummaryForDisplay())->toBe('Foo');
});
```

#### toHaveJsonApiPagination

[](#tohavejsonapipagination)

Expect that a response has JSON:API pagination. Have a look at our package [spatie/laravel-json-api-paginate](https://github.com/spatie/laravel-json-api-paginate) to see how to add JSON:API pagination to your Laravel app.

```
$response = $this->get('/');

expect($response)->toHaveJsonApiPagination();
```

### toBeInRange

[](#tobeinrange)

Expect that a value is in the specified range. The range is inclusive, meaning that the start and end values are included in the range.

The first argument is the start of the range, and the second argument is the end of the range.

```
expect(5)->toBeInRange(1, 10); // passes
expect(11)->toBeInRange(1, 10); // fails
```

### toBeCloseTo

[](#tobecloseto)

Expect that a value is close to the specified value. The first argument is the expected value, and the second argument is the deviation.

The deviation is the maximum difference between the expected value and the actual value.

```
expect(5)->toBeCloseTo(4.89, deviation: 0.1); // fails
expect(5)->toBeCloseTo(4.90, deviation: 0.1); // passes
expect(5)->toBeCloseTo(5.1, deviation: 0.1); // passes
expect(5)->toBeCloseTo(5.11, deviation: 0.1); // fails
```

### Helpers

[](#helpers)

This package offers various helpers that you can tack on any test. Here's an example of the `whenGitHubActions` helper. When tacked on to a test, the test will be skipped unless you're running it on GitHub Actions.

```
it('can only run well on github actions', function () {
    // your test
})->whenGitHubActions();
```

To use the helpers, you should call `registerSpatiePestHelpers()` in your `Pest.php` file.

These helpers are provided by this package:

- `whenConfig($configKey)`: only run the test when the given Laravel config key is set
- `whenEnvVar($envVarName)`: only run the test when the given environment variable is set
- `whenWindows`: the test will be skipped unless running on Windows
- `whenMac`: the test will be skipped unless running on macOS
- `whenLinux`: the test will be skipped unless running on Linux
- `whenGitHubActions()`: the test will be skipped unless running on GitHub Actions
- `skipOnGitHubActions()`: the test will be skipped when running on GitHub Actions
- `whenPhpVersion($version)`: the test will be skipped unless running on the given PHP version, or higher. You can pass a version like `8` or `8.1`.
- `whenIpv6Available`: the test will be skipped unless IPv6 is available

### Assertions

[](#assertions)

This package also provides a set of custom assertions that you can use in your tests.

In your `TestCase` class, you can use the `CustomAssertions` trait and call the `registerCustomAssertions` method in the `setUp` method.

```
class TestCase extends \Illuminate\Foundation\Testing\TestCase
{
    use CustomAssertions;

    protected function setUp(): void
    {
        parent::setUp();

        $this->registerCustomAssertions();
    }
```

#### assertHasJsonApiPagination

[](#asserthasjsonapipagination)

Assert that a response has JSON:API pagination. Have a look at our package [spatie/laravel-json-api-paginate](https://github.com/spatie/laravel-json-api-paginate) to see how to add JSON:API pagination to your Laravel app.

```
$this
    ->get('/')
    ->assertHasJsonApiPagination();
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

61

—

FairBetter than 98% of packages

Maintenance88

Actively maintained with recent releases

Popularity46

Moderate usage in the ecosystem

Community29

Small or concentrated contributor base

Maturity68

Established project with proven stability

 Bus Factor1

Top contributor holds 61.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~54 days

Total

22

Last Release

133d ago

Major Versions

0.0.1 → 1.0.02023-01-15

PHP version history (2 changes)0.0.1PHP ^8.1

1.6.0PHP ^8.2

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (94 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (25 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (15 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (7 commits)")[![innocenzi](https://avatars.githubusercontent.com/u/16060559?v=4)](https://github.com/innocenzi "innocenzi (6 commits)")[![sdkakcy](https://avatars.githubusercontent.com/u/32255629?v=4)](https://github.com/sdkakcy "sdkakcy (3 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![AdamWills](https://avatars.githubusercontent.com/u/3680753?v=4)](https://github.com/AdamWills "AdamWills (1 commits)")

---

Tags

spatiepest-expectations

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/spatie-pest-expectations/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-pest-expectations/health.svg)](https://phpackages.com/packages/spatie-pest-expectations)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k102.4M1.4k](/packages/spatie-laravel-permission)[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.5k55.4M8.5k](/packages/larastan-larastan)[spatie/laravel-medialibrary

Associate files with Eloquent models

6.1k43.2M632](/packages/spatie-laravel-medialibrary)[spatie/laravel-settings

Store your application settings

1.5k7.3M152](/packages/spatie-laravel-settings)[spatie/laravel-health

Monitor the health of a Laravel application

87512.0M167](/packages/spatie-laravel-health)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)