Phpspec2 Expect Laravel Package

Getting Started

Install as a dev dependency: composer require --dev bossa/phpspec2-expect. Once installed, use expect() anywhere in your PhpSpec specs (e.g., in spec/ or standalone scripts run with phpspec run) to assert on any value—scalars, arrays, objects—without wrapping it in a mock or stub. For example:

expect(strlen('hello'))->toBe(5);
expect(['a', 'b'])->toContain('a');

This is the fastest way to bring RSpec-style ergonomics to PhpSpec—ideal for quick property checks, utility function specs, or validating procedural code.

Implementation Patterns

• Scalar/Array Assertions: Use expect($scalar) directly instead of creating a dummy object just to assert on it—no need for given($value)->willReturn(...) boilerplate.
• Global/Static Function Testing: Wrap calls like expect(json_encode($data))->toContain('"key"') to test helper utilities or legacy code.
• Embedded Behavior Specs: In context examples or top-level specs (not full class specs), expect() lets you validate cross-cutting behaviors (e.g., logging, routing behavior) without full object instantiation.
• Complement to Object Specs: Combine with standard PhpSpec: use expect() for simple external condition checks (e.g., filesystem, config), and keep object-oriented matchers (shouldHaveType(), shouldBeCalled()) for method-level contract verification.
• Bootstrap Integration: Ensure expect() is auto-loaded by placing require_once __DIR__.'/../vendor/autoload.php'; in bootstrap.php or relying on Composer’s autoloader (the package registers the helper via its phpspec.yml extension).

Gotchas and Tips

• PHP/Phpspec Version Lock: Version 3.1.3 (last release: 2020) supports Phpspec ≤6 and PHP 7.1+. Phpspec 7+ is unsupported—if upgrading to Phpspec 7, either patch the package or use alternatives (e.g., custom helper + phpspec/expectation).
• Eager Evaluation Trap: expect(file_exists('x')) evaluates immediately, defeating lazy testing semantics. Wrap in closures to defer: expect(fn() => file_exists('x'))->toBeTrue();
• No Auto-completion: Since expect() is a runtime helper (not a method on a class), IDE auto-completion for matchers may lag—install phpspec/phpspec in your IDE’s PHPStan/PHPStan-Extension setup.
• Test File Naming Collision: Avoid filenames like expect_spec.php—the helper function is global and may conflict with class/method names.
• Minimal extensibility: This package only provides the expect() entry point. Custom matchers must be built using standard Phpspec Matcher classes—not via this package’s internals. Use it as a bridge, not a DSL extension layer.