Phpunit Architecture Test Laravel Package

Getting Started

1. Install via Composer: composer require --dev ta-tikoma/phpunit-architecture-test
2. Create a new test class (e.g., Tests\ArchitectureTest) that extends PHPUnit\Architecture\Steps\TestCase
3. Begin with a simple assertion: $this->expectNotTargetedNamespaces([]); $this->expectClasses()->beFinal(); to enforce rules like “all classes must be final”
4. Check the README’s quick start section in the repository for minimal examples (though repo URL is missing, assume standard GitHub layout)

Implementation Patterns

• Namespace-level assertions: Enforce boundaries like expectNamespaces(['App\\Domain\\', 'App\\Application\\'])->notToDependOnEachOther()
• Class/Method constraints: Chain checks like expectClasses()->inNamespace('App\\Service')->toHaveMethod('handle')
• Dependency graph validation: Use expectClasses()->inNamespace('App\\Infra\\Persistence')->toDependOnlyOn('App\\Domain') to guard against infra leaking into domain
• Custom rules: Extend PHPUnit\Architecture\Rules\Rule for domain-specific patterns (e.g., “all DTOs must be immutable”)
• Run alongside existing tests: Add php artisan test --filter Architecture or include in CI pipeline via vendor/bin/phpunit --testsuite=Architecture

Gotchas and Tips

• Autoloading quirks: Ensure all tested classes are autoloaded before assertions run — use ->bootstrap() or group tests carefully to avoid ReflectionException
• Strict ordering matters: Chain expectClasses(), inNamespace(), and constraints in the correct order (e.g., inNamespace() must precede toHaveMethod())
• False positives in namespaces: inNamespace('App') may match AppTest — use inNamespace('App\\') with trailing backslash
• Extension points: Override setUp() carefully — parent setup handles the AST analysis context; calling parent::setUp() is critical
• Debugging: Use dump() or dd() inside rules but avoid it in final tests; enable ->withDetails() to see why a rule failed
• Performance: For large codebases, run architecture tests in isolation or scope them to focused namespaces to avoid OOM
• Dynamic code warning: Reflection-based checks may fail on magic methods/properties — prefer PHPDoc annotations or explicit attribute usage (#[ArchitectureIgnore]) when needed