Last indexed: 7 February 2026 (101eff)

Test Attributes and Extensibility

Purpose and Scope

This document covers the attribute-based testing system in Hypervel Foundation, which provides declarative test configuration through PHP 8 attributes and extensible lifecycle hooks. The system enables test cases to be configured using attributes that are automatically discovered and executed at appropriate points in the test lifecycle.

For information about the base TestCase class and overall test lifecycle, see Test Case Foundation and Lifecycle. For specific testing concerns like HTTP request testing or container interaction, see sections 6.3 through 6.8.

Attribute System Architecture

The attribute system is built around two core components: the InteractsWithTestCase trait that manages attribute discovery and execution, and the AttributeParser class that extracts attributes from reflection metadata.

Sources: src/Testing/Concerns/InteractsWithTestCase.php1-245 src/Testing/AttributeParser.php1-114

Attribute Contracts

The testing framework defines several interfaces that attributes can implement to participate in the test lifecycle:

Contract	Purpose	Lifecycle Phase	Methods
`TestingFeature`	Base marker interface	N/A	None
`Resolvable`	Meta-attributes that resolve to concrete attributes	Discovery	`resolve(): ?TestingFeature`
`Invokable`	Direct invocation with application container	Before Each	`__invoke(Application $app)`
`Actionable`	Complex setup with callback access	Before Each	`handle(Application $app, Closure $callback)`
`BeforeEach`	Pre-test setup	Before Each	`beforeEach(Application $app)`
`AfterEach`	Post-test teardown	After Each	`afterEach(Application $app)`
`BeforeAll`	Class-level setup	Before Class	`beforeAll()`
`AfterAll`	Class-level teardown	After Class	`afterAll()`

Sources: src/Testing/Concerns/InteractsWithTestCase.php10-16

Attribute Discovery and Caching

The InteractsWithTestCase trait maintains several static caches to optimize attribute discovery:

Cache Data Structures

The caching system uses four static properties to store discovered attributes:

Class Attributes Cache

cachedTestCaseClassAttributes[className] = [
 ['key' => AttributeClassName, 'instance' => attributeInstance],
 ...
]

src/Testing/Concerns/InteractsWithTestCase.php27-31

Method Attributes Cache

cachedTestCaseMethodAttributes["ClassName:methodName"] = [
 ['key' => AttributeClassName, 'instance' => attributeInstance],
 ...
]

src/Testing/Concerns/InteractsWithTestCase.php33-38

Programmatic Features (cleared between tests)

testCaseTestingFeatures[] = ['key' => ..., 'instance' => ...]
testCaseMethodTestingFeatures[] = ['key' => ..., 'instance' => ...]

src/Testing/Concerns/InteractsWithTestCase.php40-52

Sources: src/Testing/Concerns/InteractsWithTestCase.php27-59

Attribute Resolution Process

The AttributeParser class handles the extraction and validation of attributes from PHP reflection metadata:

Attribute Validation

The validAttribute() method ensures only valid testing attributes are processed:

src/Testing/AttributeParser.php77-91

Resolvable Attributes

Resolvable attributes act as meta-attributes that transform into concrete testing features. For example, the Define attribute:

Sources: src/Testing/Attributes/Define.php1-38 src/Testing/AttributeParser.php94-112

Test Lifecycle Integration

The attribute system integrates with PHPUnit's lifecycle through specific hook methods in InteractsWithTestCase:

Setup Phase Execution Order

During setUp(), attributes are executed in the following order:

Invokable attributes - Direct invocation with application container
Actionable attributes - Complex setup with potential deferred execution
BeforeEach attributes - Standard pre-test hooks

src/Testing/Concerns/InteractsWithTestCase.php173-204

Actionable Attribute Execution

Actionable attributes receive a callback to invoke test methods and may return a Closure for deferred execution:

This pattern allows attributes to delegate work back to test methods while optionally deferring some operations until after all attributes have been processed.

src/Testing/Concerns/InteractsWithTestCase.php187-198

Sources: src/Testing/Concerns/InteractsWithTestCase.php173-244

Programmatic Feature Addition

Tests can add attributes programmatically using the usesTestingFeature() method, which is useful for test base classes or shared test traits:

API Signature

The $flag parameter controls whether the attribute applies to all tests in the class (TARGET_CLASS) or only to specific methods (TARGET_METHOD).

src/Testing/Concerns/InteractsWithTestCase.php87-113

Usage Example Pattern

Sources: src/Testing/Concerns/InteractsWithTestCase.php87-113

Cache Lifecycle Management

The attribute caching system has specific cleanup points to prevent memory leaks and stale data:

Cache	Cleared When	Rationale
`$testCaseMethodTestingFeatures`	After each test method	Method-level programmatic features are test-specific
`$testCaseTestingFeatures`	After all tests in class	Class-level features can be reused across methods
`$cachedTestCaseClassAttributes`	After all tests in class	Class metadata is static but should not persist between test classes
`$cachedTestCaseMethodAttributes`	After all tests in class	Method metadata is static but should not persist between test classes
`$cachedTestCaseUses`	After all tests in class	Trait usage is static per class

src/Testing/Concerns/InteractsWithTestCase.php209-244

Trait Detection System

The usesTestingConcern() method allows tests to conditionally execute code based on which traits are in use:

This is primarily used internally by the testing framework to determine which features are available, such as checking if a test uses InteractsWithDatabase before attempting database operations.

src/Testing/Concerns/InteractsWithTestCase.php62-85

Sources: src/Testing/Concerns/InteractsWithTestCase.php62-85