Weave Code
Pest Plugin Expectations Laravel Package
pestphp/pest-plugin-expectations
An extension for the Pest PHP testing framework that adds extra expectation APIs, letting you write fluent, readable assertions with expect(). It supports custom expectation creation and ships additional built-in expectations for cleaner, more expressive test suites.
Add expectations testing capabilities to Pest or PHPUnit
Frequently asked questions about Pest Plugin Expectations
- What is pestphp/pest-plugin-expectations used for?
- It is a dev-only Pest plugin that extends the expect() API with additional built-in expectations and lets you register your own custom expectations, so tests read as fluent chains like expect($order)->toBePaid() instead of raw PHPUnit assertions. It plugs into Pest's expectation registry and delegates the actual comparison to PHPUnit underneath. There is no runtime code path, service provider, database, queue, or HTTP surface, so its blast radius is limited to your test bootstrap and toolchain. In practice its functionality overlaps almost entirely with what Pest ships in core today.
- Do I still need pest-plugin-expectations with Pest 2.x or 3.x?
- No. The expect() entry point and expect()->extend() for authoring custom expectations are native to Pest 2.x and 3.x, so the package is at best a no-op on a current stack. On Pest 2.x+ it can also cause duplicate expect() registration, which is dangerous because it produces green tests that assert less than reviewers assume. Treat it as a deletion candidate rather than an integration candidate and confirm by running your suite with it removed.
- How do I install pest-plugin-expectations in a Laravel project?
- Mechanically it is a single dev dependency: composer require --dev pestphp/pest-plugin-expectations, with autodiscovery and no configuration publishing or provider registration. The practical gate is dependency resolution, not setup. The final release is dated 2021-05-19, which implies PHP 7.x/8.0-era and PHPUnit 8/9-era constraints, so on modern PHP and PHPUnit versions Composer will either refuse to resolve or force downgrades across your test toolchain. A throwaway-branch spike is the only admissible evidence, and even a clean install does not create a maintenance path.
- Is pest-plugin-expectations compatible with PHP 8.2+ and PHPUnit 10 or 11?
- Realistically no. With no release after May 2021, the package predates PHPUnit 10 and 11 and the PHP 8.2+ era, and Composer will typically refuse resolution or pin you to older PHPUnit versions that destabilize the rest of the test stack. Any metadata claiming Pest 2.x or 3.x compatibility should be treated as unverified, because it is inconsistent with the archive date and the release history. Verify only on a throwaway branch, and do not read a successful spike as an approval signal.
- How do I write custom expectations in Pest without this plugin?
- Use Pest's core API: expect()->extend('toBePaid', fn () => $this->toBe('paid')), registered in tests/Pest.php or a dedicated helper file so it is available across the suite. This is the same registration surface the plugin wraps, which is why the plugin became redundant once Pest absorbed custom-expectation authoring into core. Keeping expectations in your own codebase also means you own the definition and can refactor it freely. For anything exotic, fall back to plain PHPUnit assertions instead of adding a dependency.
- Is pest-plugin-expectations still maintained?
- No. The repository is archived, has zero dependents, and has had no release since 2021-05-19, so there is no upstream to inherit fixes or security responses from. One hundred percent of any maintenance burden, including future PHP and PHPUnit compatibility, transfers to your team. That abandonment risk is certain rather than speculative, which is why the recommended outcome is a scoped removal ticket and a decision record, not an integration plan.
- Is it safe to use pest-plugin-expectations in production?
- It never ships to production because it is require-dev tooling with no runtime path, so the risk is not a production outage. The real risk is asymmetric and lives in CI: a passing suite that verifies less than your review process believes, plus a ceiling on PHP, PHPUnit, and Pest upgrades over the next 12 to 18 months. If it must survive temporarily, keep it as a single dev dependency with no config publishing and a dated exit plan tied to the next Pest major upgrade.
- What are the alternatives to pest-plugin-expectations?
- Pest core's expect() and expect()->extend() cover the same fluent assertion surface and are the direct replacement. Plain PHPUnit assertions remain the fallback for anything Pest does not model, and Laravel's own testing helpers handle framework-specific checks such as database and HTTP assertions. For architecture rules, Pest's arch testing plugin is a better fit than a general expectation extension. There is no scenario on a current Laravel stack where this package is the right choice over those options.
- Will removing pest-plugin-expectations break my existing tests?
- Usually not, because core Pest already provides the same expect() entry point and extension mechanism. The failure mode to watch for is silent under-testing rather than a crash: duplicate or shadowed expect() registrations can make tests pass while asserting less than intended. Check whether any bespoke expectation in your suite is built on this plugin's registration surface or is a pass-through to behavior core already owns, then run the full suite with the package removed before deleting it from composer.json.
- How do I verify no assertions were silently dropped after removing the plugin?
- Run the full suite before and after removal and compare test counts, assertion counts, and coverage output to catch anything that quietly stopped executing. Grep for expect()->extend() and any custom expectation names to confirm each one is either re-registered in tests/Pest.php or unused. Review the diff for tests that still pass but no longer assert the intended behavior, since green tests asserting less is the dangerous case here. Record the evidence in the removal ticket so reviewers can see the coverage delta.
Weaver
How can I help you explore Laravel packages today?