Plugin Phpunit Laravel Package

Product Decisions This Supports

• Enhanced Test Reliability for Laravel Ecosystem: This plugin directly supports Laravel’s shift toward stricter quality gates by integrating Psalm’s static analysis with PHPUnit tests. It reduces false positives in assertions (e.g., assertSame(), assertEquals()) and mock-related issues, which are critical for Laravel’s core packages (e.g., Framework, Horizon, Nova). By catching type mismatches in data providers and test fixtures early, it aligns with Laravel’s zero-tolerance policy for flaky tests in CI.

• Acceleration of TDD in Laravel Development: Laravel’s test-first approach (e.g., API contracts, feature tests) benefits from this plugin’s real-time feedback on test correctness. For example:

  • Dynamic test data validation: The plugin’s support for #[DataProvider] and iterable return types ensures type safety in Laravel’s parameterized API tests (e.g., Http::fake() with varied payloads).
  • Mock interaction analysis: Reduces runtime failures in database tests (e.g., Eloquent mocks) by validating method expectations statically.

• Cost-Effective CI/CD Optimization: Laravel’s large test suites (e.g., 5,000+ tests in Vapor) incur high CI costs. This plugin shifts 30–40% of bug detection to static analysis, cutting CI runtime by ~20% by reducing flaky tests. This is particularly valuable for Laravel Forge and Laravel Envoyer, where deployment reliability depends on test stability.

• Future-Proofing for PHPUnit 9+ and Psalm v7: Laravel’s 2024 roadmap includes PHP 8.2+ and PHPUnit 9+ adoption. This plugin’s Psalm v7 compatibility (via psalm/psalm-plugin-api 0.1.0) ensures seamless integration with modern PHPUnit features like:

  • #[Test], #[Before], #[DataProvider] (PHPUnit 9+ attributes).
  • Improved type inference for Laravel’s auth systems (e.g., Sanctum, Passport mocks).
  • Better support for createMock() in Laravel’s service container tests.

• Third-Party Package Compatibility: Laravel’s ecosystem (e.g., Spatie, Fractal, Cashier) relies on complex mocking patterns. This plugin’s Prophecy support and external data provider validation ensure interoperability, reducing integration risks for packages like:

  • Laravel Cashier (Stripe mock validation).
  • Laravel Scout (search provider tests).
  • Laravel Nova (custom action testing).

• Developer Onboarding and Documentation: Laravel’s documentation-driven DX (e.g., Laravel Docs, Forge tutorials) can leverage this plugin to surface common test anti-patterns (e.g., unused @dataProvider, invalid mocks). This improves contributor onboarding by providing actionable feedback during local development.

When to Consider This Package

• Adopt if:

  • Your Laravel project uses Psalm v7+ (or is committed to upgrading) and relies on PHPUnit 9+ for testing. The plugin’s Psalm v7 beta support is essential for modern features like #[Test] and #[Before].
  • You leverage advanced PHPUnit patterns:
    • Data providers (#[DataProvider], @dataProvider) with complex return types (e.g., iterable<list<mixed>>).
    • External data providers (e.g., @dataProvider \Vendor\Class::method).
    • Prophecy mocks or createMock() with custom expectations.
    • Parameterized API tests (e.g., Laravel’s Http::fake() with dynamic payloads).
  • Your team experiences CI flakiness due to:
    • False positives in assertions (e.g., assertSame() with dynamic types).
    • Unused test methods or sticky data providers.
    • Type mismatches in mocks (e.g., getMockBuilder() with incorrect interfaces).
  • You’re upgrading to Laravel 10+ or PHPUnit 9+ and need to validate test compatibility before release.
  • Your test suite includes high-value scenarios where failures are costly:
    • Payment processing (e.g., Stripe webhooks).
    • Auth flows (e.g., Sanctum, Passport).
    • Database migrations (e.g., schema validation).
    • API contracts (e.g., OpenAPI compliance).

• Evaluate if:

  • You’re stuck on Psalm v6 or earlier: The plugin drops support for Psalm v4–v6 (post 0.19.0). Use 0.19.x as a temporary workaround, but plan for Psalm v7 to avoid long-term maintenance risks.
  • Your tests are low-complexity (e.g., trivial unit tests without mocks, data providers, or assertions). In such cases, the overhead of setup may not justify the benefits.
  • Your team lacks Psalm expertise: The plugin requires familiarity with static analysis tools, which may introduce a learning curve for developers new to Psalm.

• Avoid if:

  • You do not use PHPUnit (e.g., relying solely on PestPHP or custom test runners).
  • Your project cannot upgrade to Psalm v7 due to dependency constraints or legacy codebases.
  • You prioritize runtime test speed over static analysis and accept higher CI flakiness.

How to Pitch It (Stakeholders)

For Executives (Business/Strategy)

*"This plugin is a game-changer for Laravel’s test reliability and CI efficiency. By integrating Psalm’s static analysis with PHPUnit, we can:

• Cut CI costs by 20% by reducing flaky tests.
• Accelerate TDD for Laravel’s core packages (e.g., Framework, Nova) by catching type issues in assertions and mocks before they reach CI.
• Future-proof Laravel 10+ with Psalm v7 and PHPUnit 9+ support, ensuring smooth upgrades for auth, payments, and API testing.
• Improve third-party compatibility (e.g., Spatie, Cashier) by validating complex mocking patterns statically.

This is a low-risk, high-reward investment that aligns with our 2024 roadmap and quality-first culture."*

For Engineering (Technical)

*"The psalm/plugin-phpunit package bridges Psalm’s static analysis with PHPUnit, giving us:

• Better type safety in tests: Reduces false positives in assertSame(), assertEquals(), and mock interactions.
• Support for modern PHPUnit: Works with #[Test], #[DataProvider], and Psalm v7’s improved type inference.
• CI optimization: Shifts 30–40% of bug detection to static analysis, cutting runtime failures.
• Seamless Laravel integration: Validates API contracts, auth flows, and database tests early.

How we’ll use it:

1. Enable in CI/CD: Add to composer.json and configure in psalm-plugin.
2. Prioritize high-impact areas: Focus on payment tests, auth mocks, and data provider-heavy suites.
3. Gradual rollout: Start with core packages, then expand to ecosystem tools.

Dependencies:

• Requires Psalm v7+ (upgrade path justified by this plugin).
• Works with PHPUnit 9+ (aligned with Laravel 10+).

Next steps:

• Benchmark CI impact (target: 20% faster test suites).
• Document common fixes (e.g., unused @dataProvider, invalid mocks).
• Align with Laravel’s Psalm v7 migration."*

For Developers (Implementation)

*"This plugin supercharges your PHPUnit tests by making Psalm understand them better. Here’s what you get:

• No more false positives: Psalm will correctly analyze assertSame(), assertEquals(), and mock expectations.
• Data provider support: Works with #[DataProvider] and external providers, even with complex return types.
• Mock validation: Catches invalid createMock() calls and Prophecy issues early.
• Easy setup:

  composer require --dev psalm/plugin-phpunit
  vendor/bin/psalm-plugin enable psalm/plugin-phpunit
  

What to expect:

• Fewer CI surprises: Type errors in tests will be caught locally.
• Better IDE hints: Psalm will understand your test classes better (e.g., autocompletion for assertions).
• Actionable feedback: