Peststan Laravel Package

Product Decisions This Supports

• Enhanced Test Quality & Developer Experience:

  • Adopting PestStan enables type-safe assertions in Pest tests, reducing runtime errors and improving IDE autocompletion (e.g., expect($user)->toBeInstanceOf(User::class)).
  • Static analysis rules (e.g., detecting empty closures, redundant assertions) catch bugs early, aligning with shift-left testing and developer productivity goals.

• Build vs. Buy Decision:

  • Buy: PestStan is a lightweight, MIT-licensed extension with no maintenance overhead. It integrates seamlessly with existing PHPStan workflows, avoiding reinventing type-checking logic for Pest.
  • Build: Only consider custom solutions if PestStan lacks critical features (e.g., support for niche Pest plugins) or if architectural constraints prevent PHPStan integration.

• Roadmap Priorities:

  • Test-Driven Development (TDD): Accelerate TDD cycles by eliminating type-related flakiness in assertions.
  • Onboarding: Reduce ramp-up time for new developers by providing static guarantees about test correctness (e.g., $this binding, dynamic property types).
  • Architecture Testing: Leverage Pest’s architecture rules (e.g., toExtend(), toBeInvokable()) with full PHPStan type support for design validation.

• Use Cases:

  • Large Codebases: Critical for teams with thousands of tests where type safety prevents regression bugs.
  • API/Contract Testing: Ensures request/response types are statically verified (e.g., expect($response)->toBeJson()->json('data')->toBeArray()).
  • Legacy Migration: Gradually introduce Pest + PHPStan to legacy projects by type-checking assertions without rewriting tests.

When to Consider This Package

• Adopt PestStan if:

  • Your team uses Pest PHP (v3–5) and PHPStan (v2+) for static analysis.
  • You prioritize type safety in tests (e.g., catching toBeString() on an int at analysis time).
  • You want IDE-friendly test writing (autocompletion for expect() chains, $this binding).
  • Your project includes architecture testing (e.g., validating class hierarchies, interfaces).
  • You’re using Pest’s dynamic properties ($this->user = User::factory()->create()) and need type inference.

• Look Elsewhere if:

  • You don’t use PHPStan: PestStan is a PHPStan extension—no alternative exists for other tools (e.g., Psalm, InstaPHPC).
  • Your team prefers runtime assertions over static analysis (e.g., relying solely on Pest’s built-in assertions).
  • You’re using Pest <3.0 or PHP <8.2: Compatibility requirements are strict.
  • Your project lacks test coverage or type hints: PestStan amplifies the value of existing type systems.
  • You need custom Pest plugins: PestStan focuses on core Pest + PHPStan integration; niche plugins may require manual workarounds.

How to Pitch It (Stakeholders)

For Executives:

*"PestStan supercharges our test suite by eliminating type-related bugs before they reach production. Think of it as static analysis for assertions—just like how PHPStan catches type errors in code, PestStan does the same for tests. This reduces:

• Debugging time (catching toBeString() on an int at analysis time).
• Regression risks (type-safe $this binding in test hooks).
• Onboarding friction (IDE autocompletion for expect() chains).

For a one-time setup cost (adding a Composer dependency), we gain proactive test quality—critical for scaling our test suite as we grow. Teams using Pest + PHPStan (like Laravel) already rely on this; we’re just adopting a battle-tested extension."*

For Engineering:

*"PestStan bridges the gap between Pest’s expressive syntax and PHPStan’s type precision. Key wins:

1. Type-Narrowing Assertions: expect($value)->toBeString() tells PHPStan the value is a string, enabling safer chains like $value->strlen().
2. Dynamic Property Inference: No more @var annotations for $this->user = User::factory()—PHPStan auto-detects types from beforeEach hooks.
3. Static Rules: Catches anti-patterns like:
   • Empty test closures (it('test', fn() => {})).
   • Impossible assertions (expect(42)->toBeString()).
   • $this usage in beforeAll() (which runs statically).
4. Architecture Testing: Full support for Pest’s toExtend(), toBeInvokable(), etc., with accurate return types.

Setup:

composer require --dev mrpunyapal/peststan

Works with phpstan/extension-installer or manual phpstan.neon config. Zero runtime overhead—pure static analysis.

Trade-offs:

• Requires PHP 8.2+ and Pest 3+.
• Best paired with existing PHPStan (not a replacement).
• No impact on test execution speed.

Next Steps:

1. Add to composer.json (dev dependency).
2. Run phpstan analyse tests to see immediate type improvements.
3. Enable static rules in phpstan.neon (e.g., pest.test.emptyClosure)."*