Weave Code
Plugin Phpunit Laravel Package
psalm/plugin-phpunit
A Psalm plugin for PHPUnit that improves static analysis of test suites by teaching Psalm about PHPUnit-specific APIs, assertions, and mocking. Install with Composer, enable via psalm-plugin, and get more accurate type checking in your tests. Requires Psalm v4 or later.
psalm/plugin-phpunit is a PHPUnit plugin for Psalm (requires Psalm v4+) that teaches Psalm to understand PHPUnit's test conventions, eliminating false positives in test suites. Install it via composer require --dev psalm/plugin-phpunit and enable it with vendor/bin/psalm-plugin enable psalm/plugin-phpunit.
- Understands PHPUnit assertions and test lifecycle methods, so Psalm won't flag valid test code
- Infers types from
assertInstanceOf,assertSame, and similar assertions - Correctly handles mocked objects, data providers, and
@dataProviderannotations - Recognizes test doubles and PHPUnit-specific magic methods
- Improves static analysis accuracy across your entire test suite
Frequently asked questions about Plugin Phpunit
- What is psalm/plugin-phpunit used for?
- It is a Psalm plugin for PHPUnit that improves static analysis of test suites. It teaches Psalm about PHPUnit assertions, mocks, data providers, and test lifecycle so type errors and unsafe test code are caught earlier. It is installed via Composer and enabled with psalm-plugin.
- How do I install psalm/plugin-phpunit in a Laravel project?
- Run composer require --dev psalm/plugin-phpunit, then enable it with vendor/bin/psalm-plugin enable psalm/plugin-phpunit. After that, make sure your psalm.xml includes the tests directory in the file-list.
- Is psalm/plugin-phpunit compatible with Laravel and PHPUnit 10?
- Yes, it is designed for Laravel projects that use Psalm for static analysis and PHPUnit for testing. It supports PHPUnit 9+ attributes and works with Laravel's PHPUnit 10+ setup, though you should confirm your installed plugin release supports your Psalm version. Laravel's official Psalm configuration targets Psalm v5+, so compatibility is usually high.
- How do I enable psalm/plugin-phpunit after installing it?
- After the Composer install, run vendor/bin/psalm-plugin enable psalm/plugin-phpunit. This registers the plugin with Psalm so it can apply PHPUnit-aware analysis to your test suite. No Laravel-specific activation step is required.
- Do I need to modify psalm.xml to analyze my Laravel tests?
- You typically only need to add tests/ to the file-list in psalm.xml so Psalm analyzes your test suite. No Laravel-specific overrides are required for the plugin itself. You can also use exclude-files temporarily if a specific test file triggers edge cases.
- Will psalm/plugin-phpunit catch type errors in PHPUnit assertions?
- Yes, the plugin teaches Psalm about PHPUnit assertions such as assertSame() and assertInstanceOf(), so it can flag mismatched types in test code. This helps catch unsafe assertions earlier, especially around Eloquent models, API responses, and container-resolved services. It reduces false positives compared with analyzing tests without PHPUnit-aware stubs.
- Does psalm/plugin-phpunit support PHPUnit attributes like #[Test] and #[DataProvider]?
- Yes, it supports PHPUnit 9+ attributes including #[Test], #[DataProvider], and #[Before], which are important for modern Laravel testing. Laravel-specific attributes may not be recognized out of the box, but most tests use standard PHPUnit attributes. If needed, you can extend the plugin through Psalm's plugin API.
- What Psalm version does psalm/plugin-phpunit require?
- The README states Psalm v4+, but newer plugin releases may require Psalm v5+ and some have dropped Psalm 4 support. Check the composer.json constraints for the exact version you install. Laravel projects on Psalm v5+ are generally well aligned.
- How does psalm/plugin-phpunit affect CI performance?
- The plugin has zero runtime overhead because it runs as a static analysis step before your tests. Psalm itself can add roughly 10–30% slower test suite initialization, so caching results in CI helps. Run Psalm before PHPUnit to fail fast and cache globals where possible.
- What are alternatives to psalm/plugin-phpunit for Laravel test analysis?
- Alternatives include using Psalm without the PHPUnit plugin, or PHPStan with phpstan/phpstan-phpunit for PHPUnit-aware static analysis. Larastan is popular for Laravel application code but is PHPStan-based, not a Psalm plugin. The best choice depends on whether your team standardizes on Psalm or PHPStan.
Weaver
How can I help you explore Laravel packages today?