Plugin Phpunit Laravel Package

Technical Evaluation

Architecture Fit

• Seamless Integration with Laravel/Psalm Ecosystem: Designed as a Psalm plugin, it leverages Psalm’s static analysis engine to augment PHPUnit test validation. Aligns perfectly with Laravel’s adoption of Psalm for type safety and PHPUnit for testing.
• Attribute-First Design: Supports PHPUnit 9+ attributes (#[Test], #[DataProvider], #[Before]), critical for modern Laravel testing (e.g., Laravel’s #[Test] in phpunit:10).
• Type Inference for Tests: Reduces false positives in test analysis by teaching Psalm about PHPUnit assertions (e.g., assertSame(), assertInstanceOf()), improving accuracy for Laravel’s Eloquent, API responses, and service container tests.
• Plugin-Based Isolation: Encapsulates PHPUnit-specific logic, avoiding contamination of core Psalm or Laravel systems.

Integration Feasibility

• Low Friction: Requires two commands post-install:

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

• Config-Driven: Works with existing psalm.xml (add <dir>tests/</dir> to <file-list>). No Laravel-specific overrides needed.
• Dependency Alignment:
  • Psalm v4+: Laravel’s official Psalm config targets v5+, so compatibility is high.
  • PHPUnit 9+: Laravel’s phpunit/phpunit package (v10+) is fully supported.
• CI/CD Ready: Zero runtime overhead; runs as a pre-test static check (e.g., in GitHub Actions via ./vendor/bin/psalm).

Technical Risk

Key Questions

1. Psalm Adoption Maturity:
   • Is Psalm already integrated into the Laravel project’s CI/CD pipeline (e.g., ./vendor/bin/psalm --init)?
   • If not, what’s the blocker (e.g., warning fatigue, legacy code)? Prioritize fixing critical issues first.
2. Test Suite Complexity:
   • What percentage of tests use data providers, attributes, or complex assertions (e.g., assertDatabaseHas)? Higher complexity = greater plugin value.
   • Are there custom PHPUnit extensions (e.g., Laravel’s RefreshDatabase) that may conflict?
3. CI/CD Pipeline Impact:
   • How will this integrate with existing test stages? Suggest running Psalm before PHPUnit to fail fast.
   • What’s the acceptable failure threshold for static analysis warnings? (e.g., "Block builds on test-related errors only.")
4. Developer Ramp-Up:
   • How will the team interpret Psalm warnings in tests? Provide examples:
     • ❌ Warning: Argument 1 of assertSame() must be of type int, string given (e.g., $user->id is string but asserted as int).
     • ❌ Warning: Data provider must return iterable, array returned (e.g., missing yield in provider).
5. Long-Term Maintenance:
   • Who will triage Psalm warnings in tests? Assign a "Psalm Champion" to resolve false positives.
   • How will the plugin be updated as Psalm/PHPUnit evolve? Use composer require --dev with version constraints (e.g., ^0.20).

Integration Approach

Stack Fit

• Laravel + Psalm + PHPUnit 10:
  • Psalm: Static analysis for production code and tests.
  • PHPUnit 10: Modern attribute syntax (#[Test]) fully supported.
  • Composer: Dev dependency with zero runtime impact.
• Toolchain Synergy:
  • Pint: Laravel’s PHP formatter (no conflict).
  • PHPStan: If used, Psalm’s stricter type system may reduce overlap (but no direct conflict).
  • GitHub Actions: Add as a pre-test step:

    - name: Psalm (Tests)
      run: ./vendor/bin/psalm --init --no-cache --output-format=github
    

Migration Path

  <file-list>
    <dir>app/</dir>
    <dir>tests/</dir> <!-- Add test directory -->
  </file-list>
  <plugins>
    <plugin-class>PsalmPlugin\PHPUnitPlugin</plugin-class>
  </plugins>
  ```                                                                                                                                                                                                 |

| Validation | Run Psalm on a subset of tests (e.g., tests/Unit/) to validate warnings. | ./vendor/bin/psalm --init --no-cache --tests-only | | CI Integration| Add Psalm to CI pipeline before PHPUnit. | GitHub Actions example: psalm-ci-template | | Iteration | Fix critical warnings (e.g., assertion type mismatches) and refine psalm.xml exclusions. | ./vendor/bin/psalm --init --fix (experimental) Adjust <exclude-files> as needed. |

Compatibility

• Laravel-Specific Considerations:
  • Eloquent Tests: Plugin improves type checks for assertDatabaseHas(), assertModelExists(), etc.
  • API Testing: Validates assertJson()/assertJsonStructure() against actual response types.
  • Service Container: Catches mismatches in bind()/singleton() assertions.
• Edge Cases:
  • Dynamic Data Providers: May require @psalm-suppress for complex generators (e.g., yield from).
  • Legacy PHPUnit 8: Unsupported; migrate to PHPUnit 10 for full attribute support.
  • Custom Assertions: Extend plugin via Psalm’s API if needed.

Sequencing

1. Start with Unit Tests:
   • Focus on tests/Unit/ first (lower complexity, higher ROI).
   • Example: Validate assertSame($user->id, 1) where $user->id is string.
2. **