Weave Code
Phpunit Iterable Assertions Laravel Package
loophp/phpunit-iterable-assertions
PHPUnit helper assertions for iterables. Adds convenient, fluent checks for arrays and Traversables to simplify and clarify test expectations when working with generators, collections, and other iterable data sources.
Iterable assertions for PHPUnit
Frequently asked questions about Phpunit Iterable Assertions
- How do I install loophp/phpunit-iterable-assertions in a Laravel project?
- Run `composer require --dev loophp/phpunit-iterable-assertions` in your project root. No additional Laravel-specific setup is required—it works alongside PHPUnit’s existing assertions. Ensure your project uses PHP 8.1+ for the latest version (Laravel 10+) or pin to `^0.10` for PHP 8.0 compatibility (Laravel 9.x).
- Which Laravel versions are compatible with this package?
- The package works with Laravel 10+ (PHP 8.1+) out of the box. For Laravel 9.x, use `^0.10` to support PHP 8.0. Laravel 8.x is not recommended due to PHP 8.0’s EOL status and the package’s PHP 8.1+ requirement in v1.0+. Always check your Laravel version’s PHP baseline before installing.
- Can I use this package with Laravel’s Eloquent collections or API responses?
- Yes. The package is ideal for Eloquent collections (e.g., `assertIdenticalIterable($expected, $user->posts)`) and API responses, especially nested or paginated data. For example, validate JSON responses with `assertIterableContains($response->json(), fn($item) => $item['status'] === 'active')` to check specific items in iterables.
- Will this package conflict with existing PHPUnit extensions like spatie/laravel-test-factory?
- No, it won’t conflict. This package operates at the PHPUnit trait level and integrates cleanly with other extensions. If you’re using custom assertions, you can gradually replace them with the package’s fluent methods (e.g., swap `assertArrayHasKeyRecursive` for `assertIterableHasKey`). Always test your existing suite for regressions after installation.
- What’s the minimum PHPUnit version required, and does Laravel’s built-in PHPUnit support it?
- The package requires PHPUnit 9.x or higher. Laravel 10+ includes PHPUnit 10+, while Laravel 9.x uses PHPUnit 9.x, so no additional setup is needed. If you’re on an older Laravel version, ensure your `phpunit/phpunit` dependency in `composer.json` matches the package’s requirements (check the [README](https://github.com/loophp/phpunit-iterable-assertions)).
- How do I test generators or lazy collections with this package?
- The package is designed for generators and Traversables. Use assertions like `assertIdenticalIterable` or `assertIterableContains` directly on generator objects or Eloquent lazy collections. For example: `$generator = (function() { yield 1; yield 2; })(); self::assertIdenticalIterable([1, 2], $generator)`. The package handles iteration internally, so no manual conversion to arrays is needed.
- Are there any breaking changes in v1.0+ that affect Laravel projects?
- The main breaking change is the PHP 8.1+ requirement in v1.0+. If you’re on PHP 8.0 (e.g., Laravel 9.x), downgrade to `^0.10` or upgrade PHP. No functional changes were introduced in v1.0—only dependency updates (e.g., `loophp/iterators`). Always check the [changelog](https://github.com/loophp/phpunit-iterable-assertions/blob/main/CHANGELOG.md) for version-specific notes.
- How can I integrate this into my CI/CD pipeline for Laravel?
- Update your CI configuration (e.g., GitHub Actions) to use PHP 8.1+ if migrating to v1.0+. For example, change `php:8.0` to `php:8.1` in your workflow. No other Laravel-specific CI changes are needed, as the package is a dev dependency. Test your pipeline with a fresh `composer install` and run `php artisan test` to verify compatibility.
- Does this package support testing database migrations or seeders with bulk operations?
- Absolutely. Use assertions like `assertIterableEquals` to validate migration outputs or seeder data. For example, after running a seeder, check if the expected number of records were inserted: `self::assertCount(5, User::all())` or `self::assertIterableEquals(['admin', 'user'], array_column(User::pluck('role'), 'role'))`. It’s especially useful for verifying complex relationships or nested attributes.
- What alternatives exist for iterable assertions in Laravel, and why choose this package?
- Alternatives include custom PHPUnit assertions or libraries like `phpunit/phpunit`’s built-in methods (e.g., `assertEquals`). However, this package offers **fluent, dedicated methods** for iterables (e.g., `assertIterableContains` with callbacks), reducing boilerplate. It’s also actively maintained, with strict type coverage and CI/CD checks, making it a reliable choice for Laravel’s testing ecosystem.
Weaver
How can I help you explore Laravel packages today?