Infrastructure testing #3

Affected Version

v0.0.0

Pre-check

• I understand this is a final or near-final architectural decision, not an open discussion
• I have reviewed existing architecture decisions, RFCs, and related issues

Context

The FireHub ecosystem contains multiple repositories with independent responsibilities:

• Core: contracts, enums, abstract classes, and architectural truth
• Runtime: execution logic and concrete implementations
• Adapters: external integrations
• Capabilities: optional extensions

Currently, testing-related infrastructure such as reusable Data Providers, Stubs, and test utilities would need to be duplicated across repositories.

This decision defines a dedicated Testing package responsible for shared testing infrastructure across the FireHub ecosystem.

Architectural Decision

Introduce a dedicated the-firehub-project/testing package.

The Testing package will provide reusable testing infrastructure:

• Data Providers for common test scenarios
• Stubs for contract implementations
• Fixtures for reusable test object creation
• Shared testing helpers and utilities

The package will be consumed as a development dependency by FireHub repositories and will not participate in production runtime execution.

Architectural placement:

Core
↓
Runtime
↓
Adapter
↓
Capability

Testing
↓
Verification layer across all repositories

Rationale

A centralized Testing package provides:

• Consistent testing patterns across all FireHub repositories
• Reduced duplication of test infrastructure
• Better maintainability of shared test components
• Clear separation between production code and verification code
• Framework-independent testing support

Testing concerns should not leak into Core contracts or Runtime implementations.

System Boundaries

INCLUDED:

• Shared Data Providers
• Shared Stubs
• Test Fixtures
• Testing utilities
• Common test abstractions

EXCLUDED:

• Production runtime logic
• Core contracts
• Application business logic
• PHPUnit/Pest specific application behavior
• Production mocks or service implementations

The Testing package must never become a runtime dependency.

Rejected Alternatives

1. Keeping test utilities inside each repository

Rejected because:

• Creates duplicated implementations
• Causes inconsistent testing patterns
• Increases maintenance effort

2. Adding testing utilities into Core

Rejected because:

• Core represents framework truth and production contracts
• Testing concerns should not be part of runtime architecture

3. Coupling directly to PHPUnit/Pest

Rejected because:

• Limits future flexibility
• Makes testing infrastructure dependent on a single framework

Impact Analysis

Core:

• No production dependency changes
• Remains independent from testing concerns

Runtime:

• Can consume Testing as a development dependency
• No runtime behavior changes

Adapters:

• Gain access to shared integration testing utilities

Capabilities:

• Gain consistent testing support

Backwards Compatibility:

• No breaking changes
• New package introduced independently

Future Extensions:

• Enables additional testing tools, fixtures, and verification layers

Implementation Guidelines

• Namespace root: FireHub\Testing\
• Package name: the-firehub-project/testing
• Must remain independent from production runtime packages
• Prefer framework-neutral abstractions
• Stubs should implement contracts instead of duplicating production implementations
• Data Providers should contain reusable deterministic datasets
• Avoid business-specific fixtures inside this package

Follow-up Work

• Create Testing repository
• Setup Composer package structure
• Add initial Data Provider collection
• Add common contract Stubs
• Add testing documentation
• Integrate Testing package into existing repositories

Additional Context

Related architecture principles:

• Core → Foundation
• Runtime → Execution
• Adapter → Integration
• Capability → Extension
• Testing → Verification

Repository:
the-firehub-project/testing