Phpunit Attributes Laravel Package

Getting Started

Begin by installing the package via Composer:

composer require --dev eliashaeussler/phpunit-attributes

Once installed, start by using the included attributes—like @Test, @dataProvider, or @group replacements (e.g., Test, DataProvider, Group)—directly in your PHPUnit test classes. These are fully compatible with PHPUnit’s native attribute system and require no additional bootstrapping. Your first step should be to refactor a simple test method that uses a docblock annotation (e.g., @dataProvider) to use the corresponding native attribute. Check the src/ directory for the full list of available attributes and inspect phpunit.xml configuration if needed for extended integration.

Implementation Patterns

• Metadata Grouping: Use Group, Medium, Slow, or custom attributes to categorize tests by environment, runtime, or ownership—e.g., #[Group('integration')]—for targeted execution via CLI (--group=integration).
• dataProvider Replacement: Replace @dataProvider docblocks with #[DataProvider(SomeProvider::class)], keeping the provider class reference directly above the test.
• Test Naming & Intent: Combine Test with descriptive names and Description attributes (#[Description('Verifies ...')]) to clarify purpose without external docs.
• Test Traits: Create reusable attribute combinations (e.g., #[Test, Database, Slow]) in traits for consistent setup across suites.
• IDE & CI Alignment: Leverage attribute values for custom test runners or CI tags—attributes are parseable by static analyzers (e.g., PHPStan) and IDEs, enabling smarter autocomplete and test discovery.

Gotchas and Tips

• PHP Version Requirement: Requires PHP 8.0+; ensure your CI and local dev environments match. Failure to use phpunit-attributes on older PHP will yield parse errors.
• Attribute Name Collisions: Avoid naming your own attributes like Test or Group—they may conflict with PHPUnit’s built-in or this package’s attributes unless explicitly namespaced. Prefix your custom attributes if needed (e.g., #[App\Attributes\Coverage(…)]).
• Scanning Overhead: While minimal, attribute introspection adds a tiny runtime cost during test discovery. For very large suites (>10k tests), profile bootstrap time.
• Custom Attributes: To define your own metadata, extend EliasHaeussler\PHPUnitAttributes\AbstractAttribute and register them via phpunit.xml or a custom bootstrap if needed (though most attributes work out-of-the-box).
• Upgrading PHPUnit: PHPUnit’s attribute support evolves quickly; align versions carefully. The eliashaeussler/phpunit-attributes package typically tracks PHPUnit 9.5+ and 10+, but always check the release notes for compatibility.
• Debugging Tips: If an attribute isn’t being picked up, verify the class is imported (use EliasHaeussler\PHPUnitAttributes\...) and that PHPUnit’s autoloader loads it. Use phpunit --list-tests to confirm test discovery includes your annotated methods.