Weave Code
Plugin Phpunit Laravel Package
psalm/plugin-phpunit
Psalm plugin that teaches Psalm about PHPUnit tests. Adds better type inference and assertions for PHPUnit APIs so your test suite is analyzed more accurately. Requires Psalm v4+. Install via Composer and enable with psalm-plugin.
A PHPUnit plugin for Psalm
Frequently asked questions about Plugin Phpunit
- How do I install the Psalm PHPUnit plugin in a Laravel project?
- Run `composer require --dev psalm/plugin-phpunit` to add the package, then enable it with `vendor/bin/psalm-plugin enable psalm/plugin-phpunit`. Ensure Psalm v4+ is installed (Laravel projects typically use v5+). No Laravel-specific config changes are needed beyond adding `<dir>tests/</dir>` to your `psalm.xml` file list.
- Does this plugin support Laravel’s PHPUnit 10+ attributes like #[Test]?
- Yes, the plugin fully supports PHPUnit 9+ attributes, including #[Test], #[DataProvider], and #[Before], which are compatible with Laravel’s phpunit:10 package. It improves type inference for these annotations, reducing false positives in test analysis.
- Will this plugin break existing Laravel test suites?
- No, the plugin is designed to enhance—not disrupt—existing test suites. It adds context to Psalm’s static analysis, so warnings will become more accurate rather than introducing new errors. Start with `--no-cache` in CI to identify any edge cases early.
- Can I use this with Laravel’s Eloquent or API testing assertions?
- Absolutely. The plugin teaches Psalm about common PHPUnit assertions like `assertInstanceOf()`, `assertSame()`, and `assertDatabaseHas()`, making it ideal for Laravel’s Eloquent models, API responses, and database-driven tests. False positives for these assertions are significantly reduced.
- What Laravel versions and Psalm setups does this plugin support?
- The plugin works with Laravel 8+ (PHPUnit 9+) and Psalm v4+. Laravel’s official Psalm config targets v5+, so compatibility is high. If your project uses Psalm 4, upgrade to v5+ to avoid compatibility risks. Check your `composer.json` for the Psalm version.
- How does this plugin impact CI/CD pipeline performance?
- The plugin adds ~10–30% overhead to Psalm’s static analysis, but this runs as a pre-test step with zero runtime impact. Cache results in CI with `--cache-globals` and run Psalm in parallel with PHPUnit. Exclude large test files if performance is critical.
- What if my Laravel tests use custom PHPUnit extensions (e.g., RefreshDatabase)?
- While the plugin covers standard PHPUnit attributes, custom extensions like Laravel’s `RefreshDatabase` may not be recognized out of the box. Monitor for false positives and extend the plugin via Psalm’s plugin API if needed. Most Laravel tests use standard assertions, so coverage is broad.
- How do I configure Psalm to ignore false positives in tests?
- Use the `<exclude-files>` or `<ignore-errors>` tags in `psalm.xml` to temporarily suppress warnings in problematic files. For example, `<ignore-errors>` can target specific assertion types. Start with `--no-cache` in CI to identify and address false positives systematically.
- Are there alternatives to this plugin for type-checking Laravel tests?
- Other tools like PHPStan’s PHPUnit bridge or Infection (mutation testing) can complement Psalm, but none offer the same deep integration with PHPUnit’s assertions and attributes. Psalm’s plugin is the most Laravel-aligned choice for reducing false positives in test analysis.
- How do I troubleshoot Psalm warnings specific to my Laravel test suite?
- Run `vendor/bin/psalm --init` to generate a baseline config, then use `--strict` to enforce rules. For Laravel-specific issues, check the plugin’s [GitHub issues](https://github.com/psalm/psalm-plugin-phpunit/issues) or extend the plugin via Psalm’s API. Example: A warning about `assertSame()` mismatched types can often be fixed by adjusting test data or assertions.
Weaver
How can I help you explore Laravel packages today?