Pest Expectations Laravel Package

Getting Started

Install via Composer:

composer require --dev spatie/pest-expectations

No configuration needed—just start using expectations in your Pest tests. The package auto-registers itself and extends Pest’s expect() function. The first go-to use case is replacing verbose assertEquals, assertTrue, etc., with expressive alternatives like expect($value)->toBeInt() or expect($collection)->toContain($item). Check the README for the full list of expectations and examples.

Implementation Patterns

• Intention-first syntax: Use expectations that read like natural language—e.g., expect($user)->toBeActive(), expect($response)->toHaveStatus(201), expect($date)->toBeToday().
• Chaining for complex checks: Combine expectations fluently:

  expect($user)
      ->toBeActive()
      ->toHaveEmail('jane@example.com')
      ->toHaveNameStartWith('Jane');
  

• Integration with Pest hooks: Use expectations inside beforeEach, afterEach, or test closures—no state management required.
• Replace common assertions: Swap assertEquals($expected, $actual) with expect($actual)->toBe($expected) and assertArrayHasKey($key, $array) with expect($array)->toHaveKey($key).
• Work with Laravel: Use alongside Pest’s Laravel extensions—e.g., expect($this->get('/'))->toBeSuccessful() in feature tests.

Gotchas and Tips

• Case sensitivity: Expectations like toBeLowercase() and toBeUppercase() are strict (e.g., toBeLowercase() rejects mixed-case strings). Use toLower() + toBe('...') for flexible checks if needed.
• Floating-point precision: toBe(0.1 + 0.2) fails due to IEEE 754—use toBeApproximately(0.3, 0.0001) instead.
• Custom expectations: Extend the package by defining your own expectations via Expectation::macro('toBeActive', fn () => $this->toHaveProperty('status', 'active')).
• Debugging failures: Pest prints clear failure messages, but you can add context with ->withMessage('User should be active').
• Conflict with custom expect() macros: If you define your own expect() macros, ensure they’re registered after this package’s service provider loads (it auto-registers, so manual registration is unnecessary).
• No static analysis: These expectations don’t integrate with static analyzers (e.g., PHPStan) out-of-the-box—stick to native types in docblocks for type safety.