Weave Code
At a glance
Frequently asked questions about Black Box
- How do I integrate **Innmind/BlackBox** into an existing Laravel project with PHPUnit?
- Install via Composer (`composer require --dev innmind/black-box`), then configure it in `phpunit.xml` to run alongside PHPUnit tests. Use a custom namespace (e.g., `Property`) to avoid collisions with Laravel’s `Testing` facade. You can trigger proofs via CLI or integrate them into CI pipelines as a separate stage.
- What Laravel versions does **Innmind/BlackBox** support?
- The package is framework-agnostic and works with any Laravel version (5.8+) since it has no Laravel-specific dependencies. However, ensure your PHP version (8.0+) matches Laravel’s requirements. Test it in a staging environment first to confirm compatibility with your app’s service container.
- Can **BlackBox** replace Laravel’s built-in testing tools like `phpunit`?
- No, it’s designed to complement—not replace—traditional tests. Use it for validating mathematical/logical properties (e.g., financial calculations, data transformations) where edge cases are critical. Keep PHPUnit for API contracts, UI flows, and example-based scenarios.
- How do I write a property-based test for a Laravel service class (e.g., a payment processor)?
- Define properties like `payment totals must never be negative` or `discounts must not exceed 100%`. Use `Set::floats()` or `Set::integers()` to generate random inputs, then assert invariants with `Assert::same()` or `Assert::throws()`. Example: `yield $prove->proof('validates positive amounts')->given(Set::integers(1, 1000))->test(...).`
- Will **BlackBox** slow down my CI pipeline? How can I optimize performance?
- By default, it generates 100 scenarios per proof, which may impact CI speed. Mitigate this by using `--min-shrinks` to limit test cases or running proofs in parallel. For Laravel, consider isolating PBT to critical modules (e.g., payment logic) and running them as a separate CI stage.
- How do I debug a failing **BlackBox** proof? The error messages seem cryptic.
- Failing proofs often show shrunken inputs (e.g., `[123, -456]`). Use the `--verbose` flag to see full test traces. For Laravel, log these inputs to your app’s logs or integrate with tools like Laravel Debugbar to correlate failures with business logic. Document common edge cases in your team’s testing guidelines.
- Are there alternatives to **Innmind/BlackBox** for PBT in Laravel?
- For PHP, alternatives include **PHPUnit with Prophecy** (for mock-based PBT) or **Hypo** (a lightweight PBT library). However, **BlackBox** stands out for its pure PHP implementation, no dependencies, and focus on mathematical properties. For Laravel-specific needs, consider customizing **PestPHP** with PBT plugins, though they’re less mature.
- How do I run **BlackBox** tests in parallel with Laravel’s test suite?
- Use PHPUnit’s `--group` or `--exclude-group` flags to separate PBT proofs (e.g., `@property`) from traditional tests. For parallel execution, leverage Laravel Forge/Envoyer or CI tools like GitHub Actions with `phpunit --parallel`. Example: `php artisan test --group=property --parallel`.
- Can **BlackBox** test Laravel’s Eloquent models or database interactions?
- Indirectly, yes—but focus on business logic *around* models, not the ORM itself. For example, test that `User::calculateLifetimeValue()` always returns a positive float. Avoid testing raw SQL or migrations, as PBT isn’t suited for database schema validation. Use Laravel’s `DatabaseTransactions` trait for setup/teardown.
- What’s the best way to introduce **BlackBox** to a Laravel team resistant to PBT?
- Start with a pilot: Pick a high-risk module (e.g., a payment service) and write 3–5 proofs for obvious properties (e.g., `invoice totals > 0`). Show how PBT catches edge cases PHPUnit misses (e.g., floating-point precision bugs). Pair with training on interpreting shrunk inputs and tie results to production stability metrics.
Weaver
How can I help you explore Laravel packages today?