Pest Plugin Arch Laravel Package

Getting Started

Install the plugin via Composer:

composer require pestphp/pest-plugin-arch --dev

Then run php artisan test (Laravel) or pest directly to discover architecture rules defined in tests/Arch.php. The primary entrypoint is tests/Arch.php, where developers declare architectural constraints (e.g., classes()->expect()->toHaveMethod('handle'), classes()->thatExtend(Widget::class)). Begin with simple assertions like namespaces()->expect()->toBeUsedIn('App\Models') to enforce命名 conventions or structural boundaries.

Implementation Patterns

• Rule-by-layer separation: Define rules per directory or namespace (e.g., App\Services, App\Actions, App\Jobs) using directories() or namespaces().
• Custom expectations: Chain .expect() with methods like toHaveMethod(), not()->toHaveMethod(), shouldImplement(), or shouldExtend() for expressive contracts.
• Grouping and filtering: Use ->which() with ->and(), ->or(), ->not() to compose complex filters (e.g., classes()->in('App/Console')->which()->areNotAbstract()).
• CI enforcement: Add pest --group=arch to your CI pipeline to fail builds when architecture drifts occur. Integrate with pest/pest-plugin-pest or pestphp/pest-plugin-laravel for unified test suites.

Gotchas and Tips

• Performance: Architecture tests use reflection and can be slow on large codebases; isolate them in dedicated files (e.g., tests/Arch/*) and run selectively.
• Namespace vs. directory scoping: namespaces() resolves based on Composer autoload mappings, while directories() inspects filesystem paths—ensure your composer.json is updated to avoid mismatches.
• PHP version: Requires PHP 8.3+; using older versions will cause Composer dependency resolution failures.
• Debugging failures: Run pest tests/Arch.php --debug to see detailed inspection logs; inspect which() filters and expect() chain errors carefully—misapplied filters are the most common cause of false positives.
• Extensibility: Extend via Pest\Plugins\Arch\Rule or register custom expectations in tests/Arch.php using the underlying ta-tikoma/phpunit-architecture-test API.